docs: add WEED_S3_SSE_KEK and WEED_S3_SSE_KEY with migration guide

Environment-Variables.md

@@ -81,14 +81,17 @@ WEED_HTTPS_CLIENT_CA=/path/to/ca.crt
 
 ### SSE-S3 Encryption Key (KEK)
 ```shell
-# Any secret string used to derive the Key Encryption Key for SSE-S3.
-# A 256-bit key is derived from this value using HKDF-SHA256.
-# When set, the S3 API server uses this instead of storing a KEK
-# on the filer at /etc/s3/sse_kek.
+# Option A: hex-encoded 256-bit key (same format as /etc/s3/sse_kek).
+# Drop-in replacement for the filer-stored KEK. If /etc/s3/sse_kek also
+# exists, the values must match.
+WEED_S3_SSE_KEK=$(openssl rand -hex 32)
+
+# Option B: any secret string. A 256-bit key is derived via HKDF-SHA256.
+# Cannot be used while /etc/s3/sse_kek exists — delete the filer file first.
 WEED_S3_SSE_KEY=my-secret-passphrase
 ```
 
-See [[Server-Side-Encryption]] for details.
+Only one of `WEED_S3_SSE_KEK` and `WEED_S3_SSE_KEY` may be set. See [[Server-Side-Encryption]] for details.
 
 For full details, see [[Security Configuration]].
 

Server-Side-Encryption.md

@@ -33,7 +33,7 @@ Use this quick guide to choose the right option:
 - **Keys live in**: SeaweedFS (we handle the key management for you)
 - **Why teams like it**: Works with explicit `x-amz-server-side-encryption: AES256` and bucket default encryption; supports multipart uploads and range requests
 - **Configuration**: Optional bucket-level default encryption via the standard S3 bucket encryption API
-- **Key Encryption Key (KEK)**: The recommended way to provide the KEK is via the `WEED_S3_SSE_KEY` environment variable (hex-encoded 256-bit key). This avoids storing the master key on the filer. See [KEK Configuration](#kek-configuration) below.
+- **Key Encryption Key (KEK)**: The recommended way to provide the KEK is via the `WEED_S3_SSE_KEK` or `WEED_S3_SSE_KEY` environment variable. This avoids storing the master key on the filer. See [KEK Configuration](#kek-configuration) below.
 
 ## Quick Start
 
@@ -123,16 +123,33 @@ SSE-S3 uses envelope encryption: a Key Encryption Key (KEK) protects per-object
 
 ### Recommended: Environment Variable
 
-Set `WEED_S3_SSE_KEY` to any secret string. A 256-bit key is derived from it automatically using HKDF-SHA256:
+Two options — pick one (they cannot both be set):
+
+#### `WEED_S3_SSE_KEK` — hex-encoded, drop-in for existing filer KEK
+
+Same format as the filer file `/etc/s3/sse_kek`. If the filer file also exists, the values **must match** or the server refuses to start. This is ideal for migrating an existing deployment.
 
 ```bash
-export WEED_S3_SSE_KEY=my-secret-passphrase
+# For new deployments, generate a fresh key:
+export WEED_S3_SSE_KEK=$(openssl rand -hex 32)
+
+# For existing deployments, copy the value from the filer:
+# weed shell → fs.cat /etc/s3/sse_kek
+export WEED_S3_SSE_KEK=<value from filer>
 
-# Start the S3 API server
 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. The secret never touches the filer filesystem. Store it in your secrets manager (Vault, AWS Secrets Manager, Kubernetes Secrets, etc.) and inject it as an environment variable at startup.
+#### `WEED_S3_SSE_KEY` — any secret string (HKDF-derived)
+
+A 256-bit key is derived automatically via HKDF-SHA256, so any passphrase works. However, this **cannot be used while `/etc/s3/sse_kek` exists** on the filer — you must delete the filer file first to avoid silently orphaning data encrypted with the old KEK.
+
+```bash
+export WEED_S3_SSE_KEY=my-secret-passphrase
+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)
 
@@ -140,9 +157,12 @@ If `WEED_S3_SSE_KEY` is not set, SeaweedFS falls back to loading the KEK from `/
 
 ### Migration from Filer KEK to Environment Variable
 
-Since the env var value is run through HKDF to derive the actual key, you **cannot** simply copy the filer KEK hex string into `WEED_S3_SSE_KEY` — it would produce a different derived key.
+1. Read the existing KEK: `weed shell` → `fs.cat /etc/s3/sse_kek`
+2. Set the env var with the **exact same value**: `export WEED_S3_SSE_KEK=<value>`
+3. Restart all S3 API servers — they will use the env var and verify it matches the filer file
+4. Once all servers use the env var, optionally delete `/etc/s3/sse_kek` from the filer
 
-For existing deployments with data already encrypted under the filer KEK, continue using the filer KEK (it is loaded automatically as a fallback). Set `WEED_S3_SSE_KEY` for **new deployments** that have no existing encrypted data.
+> **Note:** Use `WEED_S3_SSE_KEK` (not `WEED_S3_SSE_KEY`) for migration — it uses the same hex format as the filer file. `WEED_S3_SSE_KEY` derives a different key via HKDF and refuses to start while the filer file exists.
 
 ## Implementation Notes