mirror of https://github.com/rustfs/rustfs.git synced 2026-01-16 17:20:33 +00:00

Files

guojidan 9ddf6a011d feature: support kms && encryt (#573 )

* feat(kms): implement key management service with local and vault backends

Signed-off-by: junxiang Mu <1948535941@qq.com>

* feat(kms): enhance security with zeroize for sensitive data and improve key management

Signed-off-by: junxiang Mu <1948535941@qq.com>

* remove Hashi word

Signed-off-by: junxiang Mu <1948535941@qq.com>

* refactor: remove unused request structs from kms handlers

Signed-off-by: junxiang Mu <1948535941@qq.com>

---------

Signed-off-by: junxiang Mu <1948535941@qq.com>

2025-09-22 17:53:05 +08:00

2.6 KiB

Raw Blame History

KMS Troubleshooting

Use this checklist to diagnose and resolve common KMS-related issues.

Quick Diagnostics

Check status

awscurl --service s3 --region us-east-1 \
  --access_key admin --secret_key admin \
  http://localhost:9000/rustfs/admin/v3/kms/status

Inspect logs – enable RUST_LOG=rustfs::kms=debug.
Verify backend reachability – for Vault, run vault status and test network connectivity.
Run a smoke test – upload a small object with --server-side-encryption AES256.

Common Issues

Symptom	Likely Cause	Resolution
`status: NotConfigured`	KMS was never configured or configuration failed.	POST `/kms/configure`, then `/kms/start`. Check logs for JSON parsing errors.
`healthy: false`	Backend health probe failed; Vault sealed or filesystem inaccessible.	Unseal Vault, confirm permissions on the key directory, re-run `/kms/start`.
`InternalError: failed to create key`	Backend rejected the request (e.g. Vault policy).	Review Vault audit logs and ensure the RustFS policy has `transit/keys/*` access.
`AccessDenied` when downloading SSE-C objects	Missing/incorrect SSE-C headers.	Provide the same `x-amz-server-side-encryption-customer-*` headers used during upload.
Multipart SSE-C download truncated	Parts smaller than 5 MiB stored inline; older builds mishandled them.	Re-upload with ≥5 MiB parts or upgrade to the latest RustFS build.
`Operation not permitted` during tests	OS sandbox blocked launching `vault` or `rustfs`.	Re-run tests with elevated permissions (`cargo test ...` with sandbox overrides).
`KMS key directory is required for local backend`	Started RustFS with `--kms-backend local` but no `--kms-key-dir`.	Supply the flag or use the dynamic API to set the directory before calling `/kms/start`.

Clearing the Cache

If data keys become stale (e.g. after manual rotation in Vault), clear the cache:

awscurl --service s3 --region us-east-1 \
  --access_key admin --secret_key admin \
  -X POST http://localhost:9000/rustfs/admin/v3/kms/clear-cache

Resetting the Service

POST /kms/stop
POST /kms/configure with the known-good payload
POST /kms/start
Verify with /kms/status

Support Data Collection

When opening an issue, capture:

Output of /kms/status and /kms/config
Relevant RustFS logs (rustfs::kms=*)
Vault audit log snippets (if using Vault)
The SSE headers used by the failing client request

Providing these artifacts drastically speeds up triage.

2.6 KiB Raw Blame History Unescape Escape