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

* [agent] Add documentation for Agent encryption at rest Based on elastic/elastic-agent#398 and a discussion with @cmacknz . It's a somewhat common ask from synthetics users. * Apply suggestions from code review Thanks for the copy edits Dede! Co-authored-by: DeDe Morton <[email protected]> Co-authored-by: DeDe Morton <[email protected]> (cherry picked from commit 7996f31) Co-authored-by: Andrew Cholakian <[email protected]>
elastic · Nov 18, 2022 · 8038bcd · 8038bcd
1 parent 4a8f722
commit 8038bcd
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 0 deletions.
diff --git a/docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc b/docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc
@@ -0,0 +1,29 @@
+[elastic-agent-encryption]
+= {agent} configuration encryption
+
+It is important for you to understand the {agent} security model and how it handles sensitive values in integration configurations.
+At a high level, {agent} receives configuration data from {fleet-server} over an encrypted connection and persists the encrypted configuration on disk.
+This persistence allows agents to continue to operate even if they are unable to connect to the {fleet-server}.
+
+The entire Fleet Agent Policy is encrypted at rest, but is recoverable if you have access to both the encrypted configuration data and the associated key.
+The key material is stored in an OS-dependent manner as described in the following sections.
+
+[discrete]
+== Darwin (macOS)
+
+Key material is stored in the system keychain. The value is stored as is without any additional transformations.
+
+[discrete]
+== 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 a 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.
+
+[discrete]
+== Linux
+
+The encryption key is derived from crypto/rand bytes stored in the `.seed` file after PBKDF2 transformation.
+Configuration data is stored as separate files, where the name of the file is a 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.
diff --git a/docs/en/ingest-management/index.asciidoc b/docs/en/ingest-management/index.asciidoc
@@ -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]