From b6899b2040ce8251bcdcc59302ba933935cf4dcd Mon Sep 17 00:00:00 2001 From: Andrew Cholakian Date: Fri, 18 Nov 2022 15:15:43 -0600 Subject: [PATCH] [agent] Add documentation for Agent encryption at rest (#2368) * [agent] Add documentation for Agent encryption at rest Based on https://github.com/elastic/elastic-agent/pull/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 Co-authored-by: DeDe Morton --- .../elastic-agent-encryption.asciidoc | 29 +++++++++++++++++++ index.asciidoc | 2 ++ 2 files changed, 31 insertions(+) create mode 100644 elastic-agent/elastic-agent-encryption.asciidoc diff --git a/elastic-agent/elastic-agent-encryption.asciidoc b/elastic-agent/elastic-agent-encryption.asciidoc new file mode 100644 index 0000000000..71de18f990 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/index.asciidoc b/index.asciidoc index e5da77de8e..8612f905eb 100644 --- a/index.asciidoc +++ b/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]