From 3acc74dc26ac50fe7c2745266106ba2cef36fae2 Mon Sep 17 00:00:00 2001 From: overtrue Date: Sun, 2 Aug 2026 11:07:14 +0800 Subject: [PATCH] docs(kms): correct the stale backend_info and rotation error claims Two claims in docs/operations/kms-backend-security.md described code that later changes removed or replaced. The Vault KV2 section promised a `backend_info` metadata report of `at_rest_protection: vault-kv2-acl`. That implementation and its assertion test were removed by #5501 (76b3c085b5); the KMS crate has no BackendInfo type at all today. The surviving field-level expression of the boundary is the backup contract, where VaultKv2 maps to AtRestProtection::StorageOnly and is serialized into a bundle manifest's at_rest_protection field as `storage-only`. Say that instead, and say plainly that nothing reports the boundary at runtime. The rotation section named `InvalidOperation` as the error Local and Static return. Neither backend advertises `rotate` in capabilities(), so rotate_key falls through to the default trait impl and returns UnsupportedCapability, which the contract tests already pin. InvalidOperation survives only in the cfg(test) LocalKmsClient::rotate_key, off the product path. The "rotation is rejected" conclusion was correct; only the error type was wrong. Also drop the same dead vault-kv2-acl claim from the AtRestProtection doc comment so the two do not drift apart again. Documentation only; no behavior change. --- crates/kms/src/backup/capability.rs | 3 +-- docs/operations/kms-backend-security.md | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/crates/kms/src/backup/capability.rs b/crates/kms/src/backup/capability.rs index 97ea531bc..68d1dcdc4 100644 --- a/crates/kms/src/backup/capability.rs +++ b/crates/kms/src/backup/capability.rs @@ -65,8 +65,7 @@ pub enum AtRestProtection { /// for bundling purposes: re-wrap is mandatory. LegacyUnspecified, /// Vault KV2 as currently shipped: material confidentiality relies on - /// Vault ACLs, KV2 at-rest encryption, and TLS only (the backend reports - /// `at_rest_protection = "vault-kv2-acl"`); RustFS applies no + /// Vault ACLs, KV2 at-rest encryption, and TLS only; RustFS applies no /// cryptographic wrapping of its own. StorageOnly, /// Vault KV2 with material wrapped by Vault Transit before storage. Not diff --git a/docs/operations/kms-backend-security.md b/docs/operations/kms-backend-security.md index f825ded19..97af927d8 100644 --- a/docs/operations/kms-backend-security.md +++ b/docs/operations/kms-backend-security.md @@ -21,7 +21,7 @@ The Vault KV2 backend uses Vault purely as a **secure storage** service: - Master key material is generated by RustFS and written to KV v2 as a Base64-encoded value (`encrypted_key_material` is an encoding, not a ciphertext). - The backend never calls the Vault Transit engine. The `mount_path` configuration field and the `RUSTFS_KMS_VAULT_MOUNT_PATH` environment variable are deprecated leftovers: they are accepted for compatibility and ignored. - Data-encryption keys (DEKs) handed to the object-encryption path are still wrapped with AES-256-GCM under the master key; the statement above concerns the master key's storage in Vault, not the DEK envelope. -- The backend reports this boundary in its `backend_info` metadata as `at_rest_protection: vault-kv2-acl`. +- The backend exposes no runtime report of this boundary. It is expressed as a field in exactly one place: a backup bundle manifest records `at_rest_protection: storage-only` for this backend, meaning RustFS adds no cryptographic wrapping of its own on top of Vault's storage-level protection. - Key rotation retains every historical master key version as an immutable record under `{prefix}/{key_id}/versions/{N}` and only then moves the current-version pointer; see [Master key rotation](#master-key-rotation-retention-destruction-and-upgrade-ordering) for the retention preconditions and the cluster-upgrade ordering constraint. > **Warning: KV read access is equivalent to holding the master keys.** @@ -51,7 +51,7 @@ Notes: ## Master key rotation: retention, destruction, and upgrade ordering -Rotation support differs per backend. Local and Static reject rotation outright (`InvalidOperation`); their single key material is never overwritten. Vault Transit delegates rotation to the Transit engine's own key versioning (ciphertext is version-prefixed, e.g. `vault:v1:...`). Vault KV2 rotates by retaining every historical version, as described below. Rotation is reachable through the admin API as `POST /rustfs/admin/v3/kms/keys/rotate`, which the route policy classifies as high risk and gates behind `kms:RotateKey`; it is not exposed through the S3 surface. The upgrade ordering constraint below therefore applies to an operator action, not only to a call from inside the process. +Rotation support differs per backend. Local and Static reject rotation outright: neither advertises the `rotate` capability, so the call fails with `UnsupportedCapability` before reaching any backend logic, and their single key material is never overwritten. Vault Transit delegates rotation to the Transit engine's own key versioning (ciphertext is version-prefixed, e.g. `vault:v1:...`). Vault KV2 rotates by retaining every historical version, as described below. Rotation is reachable through the admin API as `POST /rustfs/admin/v3/kms/keys/rotate`, which the route policy classifies as high risk and gates behind `kms:RotateKey`; it is not exposed through the S3 surface. The upgrade ordering constraint below therefore applies to an operator action, not only to a call from inside the process. ### Vault KV2 versioned retention model