Skip to content

Commit

Permalink
[agent] Add documentation for Agent encryption at rest
Browse files Browse the repository at this point in the history
Based on elastic/elastic-agent#398
and a discussion with @cmacknz .

It's a somewhat common ask from synthetics users.
  • Loading branch information
andrewvc committed Nov 15, 2022
1 parent 4a8f722 commit 62331d1
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
[elastic-agent-encryption]
= Elastic Agent Configuration Encryption

It is important for users to understand the security model of Elastic Agent and how it handles sensitive values in integration configurations.
At a high level, Elastic Agent receives configuration data from Fleet Server over an encrypted connection, persists those secrets in an encrypted form on disk.
This persistence is necessary to allow agents to continue to operate, even in the event of a loss of connectivity to the Fleet server.

The entirety of the Fleet Agent Policy is encrypted at rest, but is recoverable if the user has access to both the encrypted configuration data and the associated key.
The key material in stored in an OS-dependent manner as described below.

[discreet]
== Darwin (Mac OS)

Key material is stored in the system keychain. The value is stored as is without any additional transformations.

[discreet]
== Windows

Configuration data is encrypted with https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection[DPAPI] `CryptProtectData` with `CRYPTPROTECT_LOCAL_MACHINE``.
Additional entropy is derived from crypto/rand bytes stored in the `.seed` file.
Configuration data is stored as separate files where the name of the file is SHA256 hash of the key and the content of the file is encrypted with DPAPI data.
The security of key data relies on file system permissions. Only the Administrator should be able to access the file.

[discreet]
== Linux

The encryption key is derived from crypto/rand bytes that is written to the `.seed` file after PBKDF2 transformation.
Configuration data is stored as separate files where the name of the file is SHA256 hash of the key and the content of the file is AES256-GSM encrypted.
The security of the key material largely relies on file system permissions.
2 changes: 2 additions & 0 deletions docs/en/ingest-management/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ include::elastic-agent/uninstall-elastic-agent.asciidoc[leveloffset=+2]

include::elastic-agent/start-stop-elastic-agent.asciidoc[leveloffset=+2]

include::elastic-agent/elastic-agent-encryption.asciidoc[leveloffset=+2]

include::security/generate-certificates.asciidoc[leveloffset=+1]

include::security/certificates.asciidoc[leveloffset=+2]
Expand Down

0 comments on commit 62331d1

Please sign in to comment.