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:

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):

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.

vault write transit/keys/<task-owned-transit-key>/config deletion_allowed=true
vault delete transit/keys/<task-owned-transit-key>

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:

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.

3.1 KiB Raw Blame History