mirror of
https://github.com/rustfs/rustfs.git
synced 2026-09-07 20:46:11 +00:00
Zhengchao An
88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
# KMS Crate Instructions
|
|
|
|
Applies to `crates/kms/`.
|
|
|
|
## Change Coordination
|
|
|
|
When changing key-management behavior, verify compatibility with:
|
|
|
|
- `rustfs/src/storage/ecfs.rs`
|
|
- `rustfs/src/admin/handlers/kms.rs`
|
|
- `rustfs/src/admin/handlers/kms_dynamic.rs`
|
|
- `rustfs/src/admin/handlers/kms_keys.rs`
|
|
- `rustfs/src/admin/handlers/kms_management.rs`
|
|
|
|
## Security
|
|
|
|
- Never log plaintext keys, key material, or sensitive request payloads.
|
|
- Prefer explicit error propagation over panic paths.
|
|
|
|
## Testing
|
|
|
|
For local KMS end-to-end tests, keep proxy bypass settings:
|
|
|
|
```bash
|
|
NO_PROXY=127.0.0.1,localhost HTTP_PROXY= HTTPS_PROXY= http_proxy= https_proxy= \
|
|
cargo test --package e2e_test test_local_kms_end_to_end -- --nocapture --test-threads=1
|
|
```
|
|
|
|
### Black-box behavior suite and the Vault lane
|
|
|
|
`crates/kms/tests/behavior_*.rs` drive the crate through its public entry
|
|
points only. By default they run against the Local and Static backends.
|
|
|
|
Setting `RUSTFS_KMS_VAULT_TOKEN` adds the Vault KV2 and Vault Transit backends
|
|
to every `for_each_backend` spec, against a live server
|
|
(`RUSTFS_KMS_VAULT_ADDR`, default `http://127.0.0.1:8200`):
|
|
|
|
```bash
|
|
NO_PROXY=127.0.0.1,localhost HTTP_PROXY= HTTPS_PROXY= http_proxy= https_proxy= \
|
|
RUSTFS_KMS_VAULT_TOKEN=<dev-token> cargo test -p rustfs-kms
|
|
```
|
|
|
|
The server needs a KV v2 engine at `secret/` and a Transit engine at
|
|
`transit/`, matching the crate's config defaults.
|
|
|
|
**Run the Vault lane whenever you touch rotation or versioning.** `rotate` and
|
|
`versioning` are advertised only by the Vault backends, so without it every
|
|
capability-gated branch for them takes the `UnsupportedCapability` side and
|
|
`behavior_rotation.rs` never asserts the working half — a rotation that dropped
|
|
prior key versions would go green.
|
|
|
|
The lane creates real keys under unique names (`behavior-kv2-*`,
|
|
`behavior-transit-*`) and does not remove them, so a dev Vault accumulates them
|
|
across runs. On a dev server, remove only exact keys confirmed to belong to the
|
|
current task. A shared prefix does not prove ownership; preserve another run's
|
|
keys and leave ambiguous keys for the operator.
|
|
|
|
```bash
|
|
vault write transit/keys/<task-owned-transit-key>/config deletion_allowed=true
|
|
vault delete transit/keys/<task-owned-transit-key>
|
|
```
|
|
|
|
```bash
|
|
vault kv metadata delete secret/rustfs/kms/keys/<task-owned-kv2-key>
|
|
```
|
|
|
|
## Local Key Export for SSE-S3 Migration Tests
|
|
|
|
Use the read-only `local_kms_key_decrypt` example to export an AES-256 Local
|
|
KMS key as the base64 value expected by `RUSTFS_SSE_S3_MASTER_KEY`:
|
|
|
|
```bash
|
|
export RUSTFS_KMS_LOCAL_MASTER_KEY='<local-kms-at-rest-master-key>'
|
|
export RUSTFS_SSE_S3_MASTER_KEY="$(
|
|
cargo run -q -p rustfs-kms --example local_kms_key_decrypt -- \
|
|
/absolute/path/to/<key-id>.key
|
|
)"
|
|
```
|
|
|
|
For a `plaintext-dev-only` Local KMS key file,
|
|
`RUSTFS_KMS_LOCAL_MASTER_KEY` is not required.
|
|
|
|
The example writes only the base64-encoded 32-byte key to stdout. Diagnostics
|
|
go to stderr. Never paste its output into logs, shell history, issue comments,
|
|
or committed configuration. The export path must remain read-only and must
|
|
reuse `LocalKmsClient` decoding so current Argon2id and legacy key-file
|
|
compatibility stay aligned with the backend.
|