Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[agent] Add documentation for Agent encryption at rest #2368

Merged
merged 2 commits into from
Nov 18, 2022
Merged

[agent] Add documentation for Agent encryption at rest #2368

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
62331d1
[agent] Add documentation for Agent encryption at rest
andrewvc Nov 15, 2022
53b0409
Apply suggestions from code review
andrewvc Nov 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
[elastic-agent-encryption]
= Elastic Agent Configuration Encryption
andrewvc marked this conversation as resolved.
Show resolved Hide resolved

It is important for users to understand the security model of Elastic Agent and how it handles sensitive values in integration configurations.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
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.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
This persistence is necessary to allow agents to continue to operate, even in the event of a loss of connectivity to the Fleet server.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we double-confirm this @cmacknz ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aleksmaus would be good to have you review this as well.

andrewvc marked this conversation as resolved.
Show resolved Hide resolved
The key material in stored in an OS-dependent manner as described below.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved

[discreet]
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
== Darwin (Mac OS)
andrewvc marked this conversation as resolved.
Show resolved Hide resolved

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

[discreet]
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
== 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.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
The security of key data relies on file system permissions. Only the Administrator should be able to access the file.

[discreet]
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
== Linux

The encryption key is derived from crypto/rand bytes that is written to the `.seed` file after PBKDF2 transformation.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
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.
andrewvc marked this conversation as resolved.
Show resolved Hide resolved
The security of the key material largely relies on file system permissions.
2 changes: 2 additions & 0 deletions docs/en/ingest-management/index.asciidoc
View file
Open in desktop
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