From 8038bcd7123f2f02606ac7551d82c5a303f7dcb0 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Fri, 18 Nov 2022 15:48:05 -0600 Subject: [PATCH] [agent] Add documentation for Agent encryption at rest (#2368) (#2389) * [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 (cherry picked from commit 7996f314f314678ef942e9f77a07c283a440e6dc) Co-authored-by: Andrew Cholakian --- .../elastic-agent-encryption.asciidoc | 29 +++++++++++++++++++ docs/en/ingest-management/index.asciidoc | 2 ++ 2 files changed, 31 insertions(+) create mode 100644 docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc diff --git a/docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc b/docs/en/ingest-management/elastic-agent/elastic-agent-encryption.asciidoc new file mode 100644 index 0000000000..71de18f990 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/en/ingest-management/index.asciidoc b/docs/en/ingest-management/index.asciidoc index e5da77de8e..8612f905eb 100644 --- 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]