Skip to content

docs: add OpenBao external KMS integration guide - #196

Merged
majinghe merged 1 commit into
rustfs:mainfrom
majinghe:docs/openbao-kms-integration
Nov 14, 2026
Merged

majinghe merged 1 commit into
rustfs:mainfrom
majinghe:docs/openbao-kms-integration

Conversation

@majinghe

Copy link
Copy Markdown
Collaborator

Summary

New page security-compliance/encryption/openbao.md in all five locales (en/zh/de/fr/ja): deploy OpenBao as an external KMS for RustFS SSE-KMS through the existing vault-transit backend — configuration only, no RustFS code changes required (verified end-to-end against RustFS 1.0.5 and OpenBao 2.7.2).

Contents:

  • OpenBao deployment with TLS (self-signed CA flow) and integrated raft storage, init/unseal
  • Dedicated rustfs-transit (Transit) and rustfs-meta (KV v2) mounts, a least-privilege ACL policy covering key CRUD + LIST + crypto operations and the KV data/metadata paths, and an orphan token for RustFS
  • RustFS RUSTFS_KMS_* configuration, default SSE key selection
  • SSE-KMS verification with documented aws s3api commands (verified verbatim)
  • A validation-results table from live testing: PUT/GET round-trip, RustFS restart recovery from KV v2, sealed-OpenBao behavior (reads fail with no plaintext fallback, auto-recovery after unseal), key rotation with old-version readability, tamper rejection on both read and delete paths, and encryption-context binding
  • Troubleshooting for every pitfall hit during verification: the hard HTTPS requirement (and the dev escape flag), token-file 0600 permission validation, context vs associated_data semantics for non-derived keys (transit ignores context — the binding is on associated_data), and inline xl.meta storage layout notes

Console screenshots of the SSE Settings KMS section included — English UI for en/de/fr/ja, Chinese UI for zh (rustfs-kms-console.png, both under 300 KB).

Cross-links to the new page added from the SSE-KMS backend overview (kms.md) in all five locales.

Validation

  • npm run docs:check: PASS (locale tree parity, code-block parity across locales, banned strings, image sizes)
  • npm run build: succeeds (4085 static files generated)
  • Every command and configuration block was executed against a live deployment: OpenBao 2.7.2 (TLS + raft) on Docker, RustFS 1.0.5 (binary, systemd), SSE-KMS round-trip verified via aws s3api and the console

Verified end-to-end against RustFS 1.0.5 and OpenBao 2.7.2 (config-only
integration through the existing vault-transit backend, no code changes):

- OpenBao deployment with TLS and integrated raft storage, init/unseal
- rustfs-transit (Transit) and rustfs-meta (KV v2) mounts with a
  least-privilege policy and an orphan token for RustFS
- RustFS configuration via RUSTFS_KMS_* variables, default SSE key
- SSE-KMS verification with documented aws s3api commands
- Validation table from live testing: round-trip, restart recovery,
  sealed behavior without plaintext fallback, key rotation, tamper
  rejection (reads and deletes), and encryption-context binding
- Troubleshooting for every pitfall hit during verification: HTTPS
  requirement, token file 0600 permissions, context vs associated_data
  semantics for non-derived keys, and probe-interval recovery

Includes RustFS console screenshots of the SSE Settings KMS section
(English for en/de/fr/ja, Chinese UI for zh). Cross-links added from
the SSE-KMS backend overview page in all locales.
@majinghe
majinghe merged commit d3f099d into rustfs:main Nov 14, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant