From cea0117bbd78e5bd86ad51df87d9e42566a7d4da Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Fri, 3 Apr 2026 11:58:31 -0700 Subject: [PATCH] docs: SSE-S3 no longer auto-generates KEK, add to production checklist - Update Server-Side-Encryption.md: clarify SSE-S3 is disabled when no KEK is configured (no more auto-generation) - Update Production-Setup.md: add SSE-S3 encryption at rest section under S3 API setup --- Production-Setup.md | 16 ++++++++++++++++ Server-Side-Encryption.md | 6 ++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/Production-Setup.md b/Production-Setup.md index 9cbaa41..c4366c4 100644 --- a/Production-Setup.md +++ b/Production-Setup.md @@ -162,6 +162,22 @@ weed filer -s3 -s3.config= -s3.port=8333 The endpoint is `http://:8333`. +### S3 Encryption at Rest (SSE-S3) + +If your S3 clients use server-side encryption (`x-amz-server-side-encryption: AES256`), you **must** configure the Key Encryption Key (KEK) before starting the S3 API server. Without it, SSE-S3 requests will fail. + +Set one of these environment variables on every S3 API server (all servers in the cluster must use the same value): + +```bash +# Option A: hex-encoded 256-bit key (use this to migrate from an existing /etc/s3/sse_kek) +export WEED_S3_SSE_KEK=$(openssl rand -hex 32) + +# Option B: any secret string (simpler, key is derived via HKDF) +export WEED_S3_SSE_KEY=my-secret-passphrase +``` + +Store the value in your secrets manager and inject it at startup. See [[Server-Side-Encryption]] for details and migration instructions. + ## Set up FUSE mount Run diff --git a/Server-Side-Encryption.md b/Server-Side-Encryption.md index b949e74..b1f7038 100644 --- a/Server-Side-Encryption.md +++ b/Server-Side-Encryption.md @@ -151,9 +151,11 @@ weed s3 -filer=localhost:8888 The same secret always produces the same derived key, so all S3 API servers in a cluster must use the same value. Store it in your secrets manager (Vault, AWS Secrets Manager, Kubernetes Secrets, etc.) and inject it at startup. -### Legacy: Filer-Stored KEK (deprecated for new deployments) +### Legacy: Filer-Stored KEK (backward compatibility only) -If `WEED_S3_SSE_KEY` is not set, SeaweedFS falls back to loading the KEK from `/etc/s3/sse_kek` on the filer. If that file doesn't exist either, a new key is auto-generated and saved there. This behavior is preserved for backward compatibility but is **deprecated for new deployments** because it stores the master key in plaintext on the filer. +If neither environment variable is set, SeaweedFS falls back to loading the KEK from `/etc/s3/sse_kek` on the filer. This supports existing deployments that already have the file. + +If the filer file does not exist either, **SSE-S3 is disabled**. Any S3 request with `x-amz-server-side-encryption: AES256` will return an error. To enable SSE-S3, set one of the environment variables above. ### Migration from Filer KEK to Environment Variable