docs: rename SSE-S3 config to [s3.sse] / WEED_S3_SSE_* everywhere

Chris Lu
2026-04-03 12:06:50 -07:00
parent f38832808f
commit b58dee51e6
3 changed files with 16 additions and 16 deletions
+5 -5
@@ -81,16 +81,16 @@ WEED_HTTPS_CLIENT_CA=/path/to/ca.crt
### SSE-S3 Encryption Key (KEK)
These map to the `[sse_s3]` section of `security.toml`:
These map to the `[s3.sse]` section of `security.toml`:
```shell
# Option A: hex-encoded 256-bit key (same format as /etc/s3/sse_kek).
# Maps to: sse_s3.kek in security.toml
WEED_SSE_S3_KEK=$(openssl rand -hex 32)
# Maps to: s3.sse.kek in security.toml
WEED_S3_SSE_KEK=$(openssl rand -hex 32)
# Option B: any secret string. A 256-bit key is derived via HKDF-SHA256.
# Maps to: sse_s3.key in security.toml
WEED_SSE_S3_KEY=my-secret-passphrase
# Maps to: s3.sse.key in security.toml
WEED_S3_SSE_KEY=my-secret-passphrase
```
Only one may be set. See [[Server-Side-Encryption]] for details.
+2 -2
@@ -169,7 +169,7 @@ If your S3 clients use server-side encryption (`x-amz-server-side-encryption: AE
Add to `security.toml` (all S3 API servers in the cluster must use the same value):
```toml
[sse_s3]
[s3.sse]
# Option A: hex-encoded 256-bit key (generate with: openssl rand -hex 32)
kek = "a1b2c3d4..."
@@ -177,7 +177,7 @@ kek = "a1b2c3d4..."
key = "my-secret-passphrase"
```
Or via environment variables: `WEED_SSE_S3_KEK` / `WEED_SSE_S3_KEY`.
Or via environment variables: `WEED_S3_SSE_KEK` / `WEED_S3_SSE_KEY`.
Store the value in your secrets manager. See [[Server-Side-Encryption]] for details and migration instructions.
+9 -9
@@ -123,10 +123,10 @@ SSE-S3 uses envelope encryption: a Key Encryption Key (KEK) protects per-object
### Recommended: `security.toml`
Add an `[sse_s3]` section to your `security.toml`. Set exactly one of `kek` or `key`:
Add an `[s3.sse]` section to your `security.toml`. Set exactly one of `kek` or `key`:
```toml
[sse_s3]
[s3.sse]
# Option A: hex-encoded 256-bit key (same format as the legacy /etc/s3/sse_kek file).
# Generate with: openssl rand -hex 32
kek = ""
@@ -136,23 +136,23 @@ kek = ""
key = ""
```
These can also be set via environment variables: `WEED_SSE_S3_KEK` and `WEED_SSE_S3_KEY`.
These can also be set via environment variables: `WEED_S3_SSE_KEK` and `WEED_S3_SSE_KEY`.
#### `sse_s3.kek` — hex-encoded, drop-in for existing filer KEK
#### `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.
```toml
[sse_s3]
[s3.sse]
kek = "a1b2c3d4..." # 64 hex characters
```
#### `sse_s3.key` — any secret string (HKDF-derived)
#### `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.
```toml
[sse_s3]
[s3.sse]
key = "my-secret-passphrase"
```
@@ -167,11 +167,11 @@ If the filer file does not exist either, **SSE-S3 is disabled**.
### Migration from Filer KEK to `security.toml`
1. Read the existing KEK: `weed shell``fs.cat /etc/s3/sse_kek`
2. Add it to `security.toml`: `[sse_s3]``kek = "<value from step 1>"`
2. Add it to `security.toml`: `[s3.sse]``kek = "<value from step 1>"`
3. Restart all S3 API servers — they will use the config and verify it matches the filer file
4. Once all servers use the config, optionally delete `/etc/s3/sse_kek` from the filer
> **Note:** Use `sse_s3.kek` (not `sse_s3.key`) for migration — it uses the same hex format as the filer file. `sse_s3.key` derives a different key via HKDF and refuses to start while the filer file exists.
> **Note:** Use `s3.sse.kek` (not `s3.sse.key`) for migration — it uses the same hex format as the filer file. `s3.sse.key` derives a different key via HKDF and refuses to start while the filer file exists.
## Implementation Notes