diff --git a/content/de/security-compliance/encryption/images/rustfs-kms-console.png b/content/de/security-compliance/encryption/images/rustfs-kms-console.png new file mode 100644 index 00000000..9bd6ed51 Binary files /dev/null and b/content/de/security-compliance/encryption/images/rustfs-kms-console.png differ diff --git a/content/de/security-compliance/encryption/kms.md b/content/de/security-compliance/encryption/kms.md index 3c1b43bc..3ebccc2a 100644 --- a/content/de/security-compliance/encryption/kms.md +++ b/content/de/security-compliance/encryption/kms.md @@ -89,6 +89,9 @@ RUSTFS_KMS_VAULT_MOUNT_PATH=transit Vault Transit behält historische Schlüsselversionen. Die Rotation eines Transit-Schlüssels allein macht Objekte, die mit einer älteren Version umhüllt wurden, nicht unlesbar. Lassen Sie alte Versionen so lange aktiviert, wie Objekte von ihnen abhängen. +Eine vollständige OpenBao-Anleitung — TLS-Setup, Secrets-Engines, minimal berechtigte Policy und Ende-zu-Ende-SSE-KMS-Verifizierung — finden Sie unter [OpenBao](./openbao.md). OpenBao behält die Vault-API-Oberfläche, daher gilt dasselbe `vault-transit`-Backend. + + ## Standardschlüssel anlegen und auswählen `RUSTFS_KMS_DEFAULT_KEY_ID` wählt einen vorhandenen Schlüssel aus und legt keinen an. Starten Sie das KMS-Backend ohne diese Variable, legen Sie den Schlüssel an und fügen Sie die Variable erst danach hinzu. Starten Sie RustFS anschließend neu. diff --git a/content/de/security-compliance/encryption/meta.json b/content/de/security-compliance/encryption/meta.json index d5ed3ded..a7ddf138 100644 --- a/content/de/security-compliance/encryption/meta.json +++ b/content/de/security-compliance/encryption/meta.json @@ -3,6 +3,7 @@ "pages": [ "sse-s", "sse-c", - "kms" + "kms", + "openbao" ] -} \ No newline at end of file +} diff --git a/content/de/security-compliance/encryption/openbao.md b/content/de/security-compliance/encryption/openbao.md new file mode 100644 index 00000000..971eee02 --- /dev/null +++ b/content/de/security-compliance/encryption/openbao.md @@ -0,0 +1,269 @@ +--- +title: "OpenBao" +description: "OpenBao über das Vault-Transit-Backend als externen KMS für RustFS-SSE-KMS betreiben." +--- + +[OpenBao](https://github.com/openbao/openbao) ist der Open-Source-Fork von HashiCorp Vault. RustFS verwaltet SSE-KMS-Schlüssel über einen externen KMS mit seinem Vault-Transit-Backend, und OpenBao bietet dieselbe API-Oberfläche — daher ist keine RustFS-Codeänderung nötig; die Integration erfolgt rein über Konfiguration. Diese Anleitung deployt OpenBao, bereitet Secrets-Engines und ein minimal berechtigtes Token vor, konfiguriert RustFS und verifiziert SSE-KMS Ende-zu-Ende. Der Ablauf wurde mit RustFS `1.0.5` und OpenBao `2.7.2` verifiziert. + +Sie benötigen Docker auf dem OpenBao-Host und einen RustFS-Server ab 1.0.5. Diese Anleitung ist eine Single-Node-Bereitstellung für Integrationstests; Produktionsumgebungen benötigen zusätzlich einen geclusterten OpenBao mit verwaltetem Unseal, siehe Hinweise am Ende. + +## Architektur + +```mermaid +flowchart LR + Console["Console / S3 API"] --> RustFS["RustFS"] + RustFS -->|"wrap, unwrap, rewrap
Transit key ops"| OpenBao["OpenBao :8200"] + RustFS -->|"key metadata
KV v2 CAS"| OpenBao + OpenBao -->|"raft storage"| Disk["Sealed storage"] +``` + +RustFS erzeugt pro Objekt Datenchlüssel lokal und wrappt sie über die OpenBao-Transit-Engine; die Schlüssel-Lebenszyklus-Metadaten liegen in einem KV-v2-Mount mit CAS-Schreibvorgängen. OpenBao hält die Hauptschlüssel-Versionen — ist OpenBao nicht erreichbar, pausieren neue SSE-KMS-Schreibvorgänge und Lesezugriffe auf verschlüsselte Objekte, bis es wieder erreichbar und entiegelt ist. + +## 1. OpenBao mit TLS und Raft-Speicher deployen + +RustFS lehnt Klartext-HTTP zum KMS ab: Der Start schlägt mit `Vault Transit requires HTTPS outside explicit development mode` fehl. Richten Sie OpenBao von Anfang an mit TLS ein. Erstellen Sie die Verzeichnisstruktur und eine Konfiguration mit integriertem Raft-Speicher: + +```bash +mkdir -p /data/openbao/{data,config,tls} +openssl req -x509 -newkey rsa:4096 -sha256 -days 825 -nodes \ + -keyout /data/openbao/tls/ca-key.pem -out /data/openbao/tls/ca.pem \ + -subj "/CN=openbao-demo-ca" +openssl req -newkey rsa:2048 -nodes -keyout /data/openbao/tls/server-key.pem \ + -out /data/openbao/tls/server.csr -subj "/CN=openbao-host" +openssl x509 -req -in /data/openbao/tls/server.csr \ + -CA /data/openbao/tls/ca.pem -CAkey /data/openbao/tls/ca-key.pem \ + -CAcreateserial -out /data/openbao/tls/server-cert.pem -days 825 -sha256 \ + -extfile <(printf "subjectAltName=IP:127.0.0.1,DNS:localhost,DNS:openbao-host") +``` + +```hcl title="/data/openbao/config/config.hcl" +storage "raft" { + path = "/openbao/data" + node_id = "openbao-1" +} +listener "tcp" { + address = "0.0.0.0:8200" + cluster_address = "0.0.0.0:8201" + tls_disable = 0 + tls_cert_file = "/openbao/tls/server-cert.pem" + tls_key_file = "/openbao/tls/server-key.pem" +} +api_addr = "https://127.0.0.1:8200" +cluster_addr = "https://127.0.0.1:8201" +disable_mlock = true +ui = false +``` + +Starten Sie den Container mit eingebundenen Data-, Config- und TLS-Verzeichnissen. Die Bind-Mounts müssen für den Container-Prozess schreibbar sein: + +```bash +chmod -R a+rX /data/openbao/tls +chmod 777 /data/openbao/data +docker run -d --name openbao --restart unless-stopped \ + -p 127.0.0.1:8200:8200 \ + -v /data/openbao/data:/openbao/data \ + -v /data/openbao/config:/openbao/config \ + -v /data/openbao/tls:/openbao/tls \ + openbao/openbao:2.7.2 server +``` + +Initialisieren Sie mit einem einzelnen Schlüsselanteil und entiegeln Sie. Bewahren Sie Unseal-Schlüssel und Root-Token sicher auf — sie werden nur einmal angezeigt: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator init -key-shares=1 -key-threshold=1 -format=json +``` + +Nach jedem Container-Neustart erneut entiegeln: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator unseal +``` + +## 2. Secrets-Engines aktivieren und ein minimal berechtigtes Token erstellen + +RustFS benötigt zwei Engines: Transit für Schlüsseloperationen und KV v2 für die von ihm gepflegten Schlüssel-Metadaten. Legen Sie dedizierte Mounts an: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-transit transit +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-meta -version=2 kv +``` + +Schreiben Sie eine Policy mit exakt den Rechten des RustFS-KMS-Clients — Transit-Schlüsselverwaltung inklusive LIST (der Startprobe), die Krypto-Operationen sowie die KV-v2-Daten- und Metadatenpfade für das konfigurierte Präfix: + +```hcl title="rustfs-kms.hcl" +path "rustfs-transit/keys" { + capabilities = ["list"] +} +path "rustfs-transit/keys/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +path "rustfs-transit/encrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/decrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/rewrap/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/keys/*/rotate" { + capabilities = ["update"] +} +path "rustfs-transit/keys/*/config" { + capabilities = ["read", "update"] +} +path "rustfs-meta/data/rustfs/kms/keys/*" { + capabilities = ["create", "update", "read"] +} +path "rustfs-meta/metadata/rustfs/kms/keys/*" { + capabilities = ["read", "list", "delete"] +} +``` + +Laden Sie die Policy und stellen Sie ein Orphan-Token aus: + +```bash +docker cp rustfs-kms.hcl openbao:/tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao policy write rustfs-kms /tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao token create -policy=rustfs-kms -orphan -format=json +``` + +Legen Sie das Token auf dem RustFS-Host ab. Die Datei muss nur für den Eigentümer lesbar sein und dem `rustfs`-Dienstkonto gehören — RustFS lehnt Gruppen- und andere-Bits ab: + +```bash +install -d -m 0755 -o rustfs -g rustfs /data/rustfs/kms +install -m 0600 -o rustfs -g rustfs /dev/null /data/rustfs/kms/openbao-token +# write the token into /data/rustfs/kms/openbao-token +cp /data/openbao/tls/ca.pem /data/rustfs/kms/openbao-ca.pem +``` + +## 3. RustFS konfigurieren + +Ergänzen Sie die KMS-Einstellungen in der RustFS-Umgebungsdatei und starten Sie neu: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_ENABLE=true +RUSTFS_KMS_BACKEND=vault-transit +RUSTFS_KMS_VAULT_ADDRESS=https://127.0.0.1:8200 +RUSTFS_KMS_VAULT_MOUNT_PATH=rustfs-transit +RUSTFS_KMS_VAULT_TOKEN_FILE=/data/rustfs/kms/openbao-token +RUSTFS_KMS_VAULT_TRANSIT_METADATA_KV_MOUNT=rustfs-meta +RUSTFS_KMS_VAULT_TRANSIT_METADATA_PREFIX=rustfs/kms/keys +RUSTFS_KMS_VAULT_CA_CERT=/data/rustfs/kms/openbao-ca.pem +``` + +```bash +sudo systemctl restart rustfs +``` + +Schlägt die Backend-Validierung fehl, verweigert RustFS den Start und benennt das genaue Problem im Log — siehe [Fehlerbehebung](#fehlerbehebung). Läuft es, prüfen Sie den KMS-Status in der Konsole unter **SSE-Einstellungen** oder über die Admin-API: + +```bash +curl -s http://localhost:9000/rustfs/admin/v3/kms/service-status +``` + +Die Antwort meldet `"backend_type":"VaultTransit"` mit `"healthy":true`, die konfigurierte Adresse, den Mount-Pfad und ob ein eigenes CA-Zertifikat verwendet wird. + +## 4. Schlüssel erstellen und als Standard wählen + +Die Konsole stellt den vollen KMS-Lebenszyklus unter **SSE-Einstellungen** bereit: Statusübersicht, Schlüsselverwaltung (Erstellen, zweistufiges Löschen), Backend-Konfiguration und Re-Encrypt-Sweeps für bestehende Objekte. + +Erstellen Sie einen Schlüssel unter **KMS-Schlüsselverwaltung** — RustFS erzeugt den passenden Transit-Schlüssel in OpenBao und seinen Metadatensatz im KV-v2-Mount gemeinsam. Setzen Sie dann den **Standard-SSE-Schlüssel** in der Konsole oder über die Umgebung: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_DEFAULT_KEY_ID=rustfs-e2e-key +``` + +Starten Sie RustFS nach der Änderung neu. Ein direkt in OpenBao angelegter Schlüssel ohne Umweg über RustFS lässt den KV-v2-Metadatensatz fehlen — erstellen Sie Schlüssel von der RustFS-Seite. + +![RustFS-Konsole, SSE-Einstellungen mit VaultTransit-Backend, Schlüsselliste und KMS-Konfiguration](./images/rustfs-kms-console.png) + +## 5. SSE-KMS Ende-zu-Ende verifizieren + +Setzen Sie den Bucket-Standard oder übergeben Sie den Schlüssel pro Schreibvorgang. Die Upload-Antwort spiegelt Algorithmus und Schlüssel-ID, und der Download liefert die ursprünglichen Bytes: + +```bash +aws s3api put-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt \ + --body ./e2e-check.txt \ + --server-side-encryption aws:kms \ + --ssekms-key-id rustfs-e2e-key +``` + +```json +{ + "ETag": "\"57a02aed...\"", + "ServerSideEncryption": "aws:kms", + "SSEKMSKeyId": "rustfs-e2e-key" +} +``` + +```bash +aws s3api get-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt ./e2e-check-back.txt +``` + +## Verifizierungsergebnisse + +Die folgenden Prüfungen wurden gegen eine Live-OpenBao-2.7.2-Bereitstellung ausgeführt und sind auf jedem gesunden Setup zu erwarten: + +| Prüfung | Erwartetes Ergebnis | +| --- | --- | +| SSE-KMS PUT/GET mit der Schlüssel-ID | Antwort spiegelt `aws:kms` und die Schlüssel-ID; heruntergeladene Bytes stimmen | +| Range-GET auf einem verschlüsselten Objekt | Byte-Bereich wird korrekt geliefert | +| RustFS-Neustart | Schlüssel-Metadaten werden aus KV v2 wiederhergestellt; verschlüsselte Objekte bleiben lesbar | +| OpenBao-Neustart (sealed) | Verschlüsselte Lesezugriffe schlagen mit `ServiceUnavailable` fehl — kein Klartext-Fallback; nach dem Entiegeln erholt sich das Lesen automatisch im Probeintervall | +| Transit-Schlüsselrotation | `latest_version` steigt, ältere Versionen bleiben erhalten; vor der Rotation gewrappte Objekte bleiben lesbar | +| Ciphertext-Manipulation im Storage | Lesezugriffe schlagen fehl, Löschung wird verweigert; kein Klartext-Fallback | +| Falscher Verschlüsselungskontext | Transit-Entschlüsselung schlägt mit Nachrichtenauthentifizierungsfehler fehl | + +Hinweis zum Speicherlayout: Kleine Objekte legen ihre verschlüsselten Bytes inline in der je Datenträger vorhandenen `xl.meta`-Datei ab — ein Grep nach Klartext im Objektverzeichnis bleibt daher leer, obwohl die Daten dort liegen. + +## Fehlerbehebung + +### Start schlägt fehl mit `Vault Transit requires HTTPS outside explicit development mode` + +Die KMS-Adresse ist kein HTTPS. Konfigurieren Sie TLS auf OpenBao und vertrauen Sie seinem CA über `RUSTFS_KMS_VAULT_CA_CERT`. Der Ausweg `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` ist nur für die Entwicklung gedacht. + +### Start schlägt fehl mit `Vault token file ... has insecure permissions 0o644` + +Die Token-Datei benötigt `0600` ohne Gruppen- und andere-Bits und gehört dem RustFS-Dienstkonto: + +```bash +chown rustfs:rustfs /data/rustfs/kms/openbao-token +chmod 600 /data/rustfs/kms/openbao-token +``` + +### Lesezugriffe schlagen mit `ServiceUnavailable` fehl, während OpenBao verriegelt ist + +Erwartetes Verhalten: verschlüsselte Lesezugriffe benötigen das externe KMS. Entiegeln Sie OpenBao; RustFS erholt sich automatisch bei seiner nächsten KMS-Probe — ohne RustFS-Neustart. + +### OpenBao-Transit entschlüsselt mit falschem `context`-Parameter + +Für nicht abgeleitete Schlüssel ignoriert Transit `context` und bindet den S3-Verschlüsselungskontext als `associated_data`. Ein falscher `associated_data` schlägt mit `cipher: message authentication failed` fehl. Beim manuellen Test über `bao` übergeben Sie `associated_data`, nicht `context`. + +### Ein manipuliertes verschlüsseltes Objekt kann weder gelesen noch gelöscht werden + +Beide Pfade schlagen by design fehl — auch die Löschung prüft die gespeicherten Metadaten. Entfernen Sie die Objektverzeichnisse auf jedem Datenträger bei gestopptem RustFS und starten Sie neu. + +## Produktion + +Die obige Single-Node-OpenBao-Bereitstellung entiegelt manuell und speichert lokal. Für die Produktion: OpenBao als Cluster mit integrierter Storage-Replikation oder einem Auto-Unseal-Mechanismus betreiben, Unseal-Zugangsdaten und Raft-Datenbackup unabhängig von RustFS-Backups schützen und die OpenBao-Version pinnen — den vaultrs-Client vor jedem OpenBao-Upgrade gegen die neue Version prüfen. + +## Nächste Schritte + +- Backend-Übersicht und Bucket-Standardverschlüsselung finden Sie unter [SSE-KMS](./kms.md). +- Lesen Sie vor weiteren SSE-Funktionen die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). diff --git a/content/en/security-compliance/encryption/images/rustfs-kms-console.png b/content/en/security-compliance/encryption/images/rustfs-kms-console.png new file mode 100644 index 00000000..9bd6ed51 Binary files /dev/null and b/content/en/security-compliance/encryption/images/rustfs-kms-console.png differ diff --git a/content/en/security-compliance/encryption/kms.md b/content/en/security-compliance/encryption/kms.md index 983dbc0d..2c0b8a16 100644 --- a/content/en/security-compliance/encryption/kms.md +++ b/content/en/security-compliance/encryption/kms.md @@ -89,6 +89,9 @@ RUSTFS_KMS_VAULT_MOUNT_PATH=transit Vault Transit retains historical key versions, so rotating a Transit key does not by itself make objects wrapped with an older version unreadable. Keep old versions enabled for as long as objects depend on them. +For a full OpenBao deployment walkthrough — TLS setup, secrets engines, least-privilege policy, and end-to-end SSE-KMS verification — see [OpenBao](./openbao.md). OpenBao keeps the Vault API surface, so the same `vault-transit` backend applies. + + ## Create and select the default key `RUSTFS_KMS_DEFAULT_KEY_ID` selects an existing key; it does not create one. Start the KMS backend without this variable, create the key, and only then add the variable and restart RustFS. diff --git a/content/en/security-compliance/encryption/meta.json b/content/en/security-compliance/encryption/meta.json index a288b978..b55df4b2 100644 --- a/content/en/security-compliance/encryption/meta.json +++ b/content/en/security-compliance/encryption/meta.json @@ -3,6 +3,7 @@ "pages": [ "sse-s", "sse-c", - "kms" + "kms", + "openbao" ] -} \ No newline at end of file +} diff --git a/content/en/security-compliance/encryption/openbao.md b/content/en/security-compliance/encryption/openbao.md new file mode 100644 index 00000000..7a07ce9f --- /dev/null +++ b/content/en/security-compliance/encryption/openbao.md @@ -0,0 +1,269 @@ +--- +title: "OpenBao" +description: "Deploy OpenBao as an external KMS for RustFS SSE-KMS through the Vault Transit backend." +--- + +[OpenBao](https://github.com/openbao/openbao) is the open-source fork of HashiCorp Vault. RustFS manages SSE-KMS keys through an external KMS using its Vault Transit backend, and OpenBao keeps the same API surface, so no RustFS code change is needed — the integration is configuration only. This guide deploys OpenBao, prepares the secrets engines and a least-privilege token, configures RustFS, and verifies SSE-KMS end to end. The workflow was verified with RustFS `1.0.5` and OpenBao `2.7.2`. + +You need Docker on the OpenBao host and a RustFS 1.0.5+ server. This guide is a single-node deployment for integration testing; production deployments additionally require clustered OpenBao with managed unseal, as described at the end. + +## Architecture + +```mermaid +flowchart LR + Console["Console / S3 API"] --> RustFS["RustFS"] + RustFS -->|"wrap, unwrap, rewrap
Transit key ops"| OpenBao["OpenBao :8200"] + RustFS -->|"key metadata
KV v2 CAS"| OpenBao + OpenBao -->|"raft storage"| Disk["Sealed storage"] +``` + +RustFS generates per-object data keys locally and wraps them through the OpenBao Transit engine; key lifecycle metadata is kept in a KV v2 mount with compare-and-set writes. OpenBao holds the master key versions, so an OpenBao outage means new SSE-KMS writes and reads of encrypted objects pause until it is reachable and unsealed again. + +## 1. Deploy OpenBao with TLS and raft storage + +RustFS refuses plain HTTP to the KMS: startup fails with `Vault Transit requires HTTPS outside explicit development mode`. Set up OpenBao with TLS from the start. Create the directory layout and a config with integrated raft storage: + +```bash +mkdir -p /data/openbao/{data,config,tls} +openssl req -x509 -newkey rsa:4096 -sha256 -days 825 -nodes \ + -keyout /data/openbao/tls/ca-key.pem -out /data/openbao/tls/ca.pem \ + -subj "/CN=openbao-demo-ca" +openssl req -newkey rsa:2048 -nodes -keyout /data/openbao/tls/server-key.pem \ + -out /data/openbao/tls/server.csr -subj "/CN=openbao-host" +openssl x509 -req -in /data/openbao/tls/server.csr \ + -CA /data/openbao/tls/ca.pem -CAkey /data/openbao/tls/ca-key.pem \ + -CAcreateserial -out /data/openbao/tls/server-cert.pem -days 825 -sha256 \ + -extfile <(printf "subjectAltName=IP:127.0.0.1,DNS:localhost,DNS:openbao-host") +``` + +```hcl title="/data/openbao/config/config.hcl" +storage "raft" { + path = "/openbao/data" + node_id = "openbao-1" +} +listener "tcp" { + address = "0.0.0.0:8200" + cluster_address = "0.0.0.0:8201" + tls_disable = 0 + tls_cert_file = "/openbao/tls/server-cert.pem" + tls_key_file = "/openbao/tls/server-key.pem" +} +api_addr = "https://127.0.0.1:8200" +cluster_addr = "https://127.0.0.1:8201" +disable_mlock = true +ui = false +``` + +Start the container with the data, config, and TLS directories mounted. The bind mounts must be writable by the container process: + +```bash +chmod -R a+rX /data/openbao/tls +chmod 777 /data/openbao/data +docker run -d --name openbao --restart unless-stopped \ + -p 127.0.0.1:8200:8200 \ + -v /data/openbao/data:/openbao/data \ + -v /data/openbao/config:/openbao/config \ + -v /data/openbao/tls:/openbao/tls \ + openbao/openbao:2.7.2 server +``` + +Initialize with a single key share and unseal. Keep the unseal key and root token safe — they are shown once: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator init -key-shares=1 -key-threshold=1 -format=json +``` + +After every container restart, unseal again: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator unseal +``` + +## 2. Enable the secrets engines and create a scoped token + +RustFS needs two engines: Transit for key operations, and KV v2 for the key metadata it maintains. Create dedicated mounts: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-transit transit +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-meta -version=2 kv +``` + +Write a policy granting exactly what the RustFS KMS client needs — Transit key management including LIST (the startup probe depends on it), the crypto operations, and the KV v2 data and metadata paths for the configured prefix: + +```hcl title="rustfs-kms.hcl" +path "rustfs-transit/keys" { + capabilities = ["list"] +} +path "rustfs-transit/keys/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +path "rustfs-transit/encrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/decrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/rewrap/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/keys/*/rotate" { + capabilities = ["update"] +} +path "rustfs-transit/keys/*/config" { + capabilities = ["read", "update"] +} +path "rustfs-meta/data/rustfs/kms/keys/*" { + capabilities = ["create", "update", "read"] +} +path "rustfs-meta/metadata/rustfs/kms/keys/*" { + capabilities = ["read", "list", "delete"] +} +``` + +Load the policy and issue an orphan token: + +```bash +docker cp rustfs-kms.hcl openbao:/tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao policy write rustfs-kms /tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao token create -policy=rustfs-kms -orphan -format=json +``` + +Store the token on the RustFS host. The file must have owner-only permissions and be owned by the `rustfs` service account — RustFS rejects group or other read bits: + +```bash +install -d -m 0755 -o rustfs -g rustfs /data/rustfs/kms +install -m 0600 -o rustfs -g rustfs /dev/null /data/rustfs/kms/openbao-token +# write the token into /data/rustfs/kms/openbao-token +cp /data/openbao/tls/ca.pem /data/rustfs/kms/openbao-ca.pem +``` + +## 3. Configure RustFS + +Add the KMS settings to the RustFS environment file and restart: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_ENABLE=true +RUSTFS_KMS_BACKEND=vault-transit +RUSTFS_KMS_VAULT_ADDRESS=https://127.0.0.1:8200 +RUSTFS_KMS_VAULT_MOUNT_PATH=rustfs-transit +RUSTFS_KMS_VAULT_TOKEN_FILE=/data/rustfs/kms/openbao-token +RUSTFS_KMS_VAULT_TRANSIT_METADATA_KV_MOUNT=rustfs-meta +RUSTFS_KMS_VAULT_TRANSIT_METADATA_PREFIX=rustfs/kms/keys +RUSTFS_KMS_VAULT_CA_CERT=/data/rustfs/kms/openbao-ca.pem +``` + +```bash +sudo systemctl restart rustfs +``` + +If the backend fails validation, RustFS refuses to start and names the exact problem in the log — see [Troubleshooting](#troubleshooting). When it starts, check the KMS status in the console under **SSE Settings**, or through the admin API: + +```bash +curl -s http://localhost:9000/rustfs/admin/v3/kms/service-status +``` + +The response reports `"backend_type":"VaultTransit"` with `"healthy":true`, the configured address, mount path, and whether a custom CA is in use. + +## 4. Create a key and select the default + +The console exposes the full KMS lifecycle under **SSE Settings**: status overview, key management (create, two-stage deletion), backend configuration, and re-encrypt sweeps for existing objects. + +Create a key in **KMS Keys Management** — RustFS creates the matching Transit key in OpenBao and its metadata record in the KV v2 mount together. Then set **Default SSE Key** either in the console or through the environment: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_DEFAULT_KEY_ID=rustfs-e2e-key +``` + +Restart RustFS after changing the default. Creating a key directly in OpenBao without going through RustFS leaves the KV v2 metadata record missing — create keys from the RustFS side. + +![RustFS console SSE Settings page showing the VaultTransit backend, key list, and KMS configuration](./images/rustfs-kms-console.png) + +## 5. Verify SSE-KMS end to end + +Set the bucket default or pass the key per write. The upload response echoes both the encryption algorithm and the key ID, and the download returns the original bytes: + +```bash +aws s3api put-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt \ + --body ./e2e-check.txt \ + --server-side-encryption aws:kms \ + --ssekms-key-id rustfs-e2e-key +``` + +```json +{ + "ETag": "\"57a02aed...\"", + "ServerSideEncryption": "aws:kms", + "SSEKMSKeyId": "rustfs-e2e-key" +} +``` + +```bash +aws s3api get-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt ./e2e-check-back.txt +``` + +## Validation results + +The following checks were executed against a live OpenBao 2.7.2 deployment and are expected to pass on any healthy setup: + +| Check | Expected result | +| --- | --- | +| SSE-KMS PUT/GET with the key ID | Response echoes `aws:kms` and the key ID; downloaded bytes match | +| Range GET on an encrypted object | Byte range returned correctly | +| RustFS restart | Key metadata recovers from KV v2; encrypted objects remain readable | +| OpenBao restart (sealed) | Encrypted reads fail with `ServiceUnavailable` — no plaintext fallback; after unsealing, reads recover automatically within the probe interval | +| Transit key rotation | `latest_version` increments with older versions retained; objects wrapped before rotation stay readable | +| Ciphertext tampering on storage | Reads fail and deletion is refused; no plaintext fallback | +| Wrong encryption context | Transit decryption fails with a message authentication error | + +On storage layout note: small objects store their encrypted bytes inline in the per-disk `xl.meta` file, so ciphertext greps against the object directory come back empty even though the data is there. + +## Troubleshooting + +### Startup fails with `Vault Transit requires HTTPS outside explicit development mode` + +The KMS address is not HTTPS. Configure TLS on OpenBao and trust its CA through `RUSTFS_KMS_VAULT_CA_CERT`. The escape hatch `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` exists for development only. + +### Startup fails with `Vault token file ... has insecure permissions 0o644` + +The token file must have `0600` permissions with group and other bits unset, owned by the RustFS service account: + +```bash +chown rustfs:rustfs /data/rustfs/kms/openbao-token +chmod 600 /data/rustfs/kms/openbao-token +``` + +### Reads fail with `ServiceUnavailable` while OpenBao is sealed + +Expected behavior: encrypted reads require the external KMS. Unseal OpenBao; RustFS recovers automatically on its next KMS probe — writes and reads resume without a RustFS restart. + +### OpenBao transit decrypts with the wrong `context` parameter + +For non-derived keys, transit ignores `context` and binds the S3 encryption context as `associated_data`. A wrong `associated_data` fails with `cipher: message authentication failed`. When testing the binding manually through `bao`, pass `associated_data`, not `context`. + +### A tampered encrypted object cannot be read or deleted + +Both paths fail by design — deletion also verifies the stored metadata. Remove the object directories from every disk while RustFS is stopped, then restart. + +## Production notes + +The single-node OpenBao deployment above keeps unseal manual and storage local. For production: run OpenBao as a cluster with integrated storage replication or an auto-unseal mechanism, protect the unseal credentials and the raft data backup independently of RustFS backups, and pin the OpenBao version — validate the vaultrs client against each OpenBao upgrade before rolling it out. + +## Next steps + +- Review the backend overview and bucket-default encryption in [SSE-KMS](./kms.md). +- Read the [S3 compatibility notes](/administration/protocols/s3) before adopting further SSE features. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). diff --git a/content/fr/security-compliance/encryption/images/rustfs-kms-console.png b/content/fr/security-compliance/encryption/images/rustfs-kms-console.png new file mode 100644 index 00000000..9bd6ed51 Binary files /dev/null and b/content/fr/security-compliance/encryption/images/rustfs-kms-console.png differ diff --git a/content/fr/security-compliance/encryption/kms.md b/content/fr/security-compliance/encryption/kms.md index bc4925ba..1d7fab77 100644 --- a/content/fr/security-compliance/encryption/kms.md +++ b/content/fr/security-compliance/encryption/kms.md @@ -89,6 +89,9 @@ RUSTFS_KMS_VAULT_MOUNT_PATH=transit Vault Transit conserve les versions historiques des clés : la rotation d’une clé Transit ne rend donc pas, à elle seule, illisibles les objets enveloppés avec une version antérieure. Laissez les anciennes versions activées tant que des objets en dépendent. +Pour un guide de déploiement OpenBao complet — configuration TLS, engines de secrets, politique à privilèges minimaux et vérification SSE-KMS de bout en bout — voir [OpenBao](./openbao.md). OpenBao conserve la surface d'API de Vault, donc le même backend `vault-transit` s'applique. + + ## Créer et sélectionner la clé par défaut `RUSTFS_KMS_DEFAULT_KEY_ID` sélectionne une clé existante ; elle n’en crée pas. Démarrez le backend KMS sans cette variable, créez la clé, puis seulement ensuite ajoutez la variable et redémarrez RustFS. diff --git a/content/fr/security-compliance/encryption/meta.json b/content/fr/security-compliance/encryption/meta.json index d2fe38d0..63574a59 100644 --- a/content/fr/security-compliance/encryption/meta.json +++ b/content/fr/security-compliance/encryption/meta.json @@ -3,6 +3,7 @@ "pages": [ "sse-s", "sse-c", - "kms" + "kms", + "openbao" ] -} \ No newline at end of file +} diff --git a/content/fr/security-compliance/encryption/openbao.md b/content/fr/security-compliance/encryption/openbao.md new file mode 100644 index 00000000..336ab32c --- /dev/null +++ b/content/fr/security-compliance/encryption/openbao.md @@ -0,0 +1,269 @@ +--- +title: "OpenBao" +description: "Déployer OpenBao comme KMS externe pour le SSE-KMS de RustFS via le backend Vault Transit." +--- + +[OpenBao](https://github.com/openbao/openbao) est le fork open source de HashiCorp Vault. RustFS gère les clés SSE-KMS via un KMS externe avec son backend Vault Transit, et OpenBao conserve la même surface d'API — aucune modification du code RustFS n'est nécessaire : l'intégration se fait par la seule configuration. Ce guide déploie OpenBao, prépare les engines de secrets et un jeton à privilèges minimaux, configure RustFS, puis vérifie le SSE-KMS de bout en bout. Le workflow a été vérifié avec RustFS `1.0.5` et OpenBao `2.7.2`. + +Vous avez besoin de Docker sur l'hôte OpenBao et d'un serveur RustFS 1.0.5 ou supérieur. Ce guide est un déploiement mono-nœud destiné aux tests d'intégration ; en production, il faut en plus un OpenBao en cluster avec unscell géré, voir les notes de fin. + +## Architecture + +```mermaid +flowchart LR + Console["Console / S3 API"] --> RustFS["RustFS"] + RustFS -->|"wrap, unwrap, rewrap
Transit key ops"| OpenBao["OpenBao :8200"] + RustFS -->|"key metadata
KV v2 CAS"| OpenBao + OpenBao -->|"raft storage"| Disk["Sealed storage"] +``` + +RustFS génère les clés de données par objet localement et les enveloppe via l'engine Transit d'OpenBao ; les métadonnées de cycle de vie des clés sont conservées dans un montage KV v2 avec des écritures CAS. OpenBao détient les versions des clés maîtresses — si OpenBao devient indisponible, les nouveaux écrits SSE-KMS et les lectures des objets chiffrés s'interrompent jusqu'à ce qu'il soit de nouveau joignable et déscealé. + +## 1. Déployer OpenBao avec TLS et le stockage raft + +RustFS refuse le HTTP en clair vers le KMS : le démarrage échoue avec `Vault Transit requires HTTPS outside explicit development mode`. Configurez OpenBao avec TLS dès le départ. Créez l'arborescence et une configuration avec le stockage raft intégré : + +```bash +mkdir -p /data/openbao/{data,config,tls} +openssl req -x509 -newkey rsa:4096 -sha256 -days 825 -nodes \ + -keyout /data/openbao/tls/ca-key.pem -out /data/openbao/tls/ca.pem \ + -subj "/CN=openbao-demo-ca" +openssl req -newkey rsa:2048 -nodes -keyout /data/openbao/tls/server-key.pem \ + -out /data/openbao/tls/server.csr -subj "/CN=openbao-host" +openssl x509 -req -in /data/openbao/tls/server.csr \ + -CA /data/openbao/tls/ca.pem -CAkey /data/openbao/tls/ca-key.pem \ + -CAcreateserial -out /data/openbao/tls/server-cert.pem -days 825 -sha256 \ + -extfile <(printf "subjectAltName=IP:127.0.0.1,DNS:localhost,DNS:openbao-host") +``` + +```hcl title="/data/openbao/config/config.hcl" +storage "raft" { + path = "/openbao/data" + node_id = "openbao-1" +} +listener "tcp" { + address = "0.0.0.0:8200" + cluster_address = "0.0.0.0:8201" + tls_disable = 0 + tls_cert_file = "/openbao/tls/server-cert.pem" + tls_key_file = "/openbao/tls/server-key.pem" +} +api_addr = "https://127.0.0.1:8200" +cluster_addr = "https://127.0.0.1:8201" +disable_mlock = true +ui = false +``` + +Démarrez le conteneur avec les répertoires de données, de configuration et TLS montés. Ces montages par liaison doivent être inscriptibles par le processus du conteneur : + +```bash +chmod -R a+rX /data/openbao/tls +chmod 777 /data/openbao/data +docker run -d --name openbao --restart unless-stopped \ + -p 127.0.0.1:8200:8200 \ + -v /data/openbao/data:/openbao/data \ + -v /data/openbao/config:/openbao/config \ + -v /data/openbao/tls:/openbao/tls \ + openbao/openbao:2.7.2 server +``` + +Initialisez avec une seule part de clé et déscealez. Conservez la clé d'unseal et le jeton root en sécurité — ils ne sont affichés qu'une fois : + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator init -key-shares=1 -key-threshold=1 -format=json +``` + +Après chaque redémarrage du conteneur, déscealez à nouveau : + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator unseal +``` + +## 2. Activer les engines de secrets et créer un jeton à portée limitée + +RustFS a besoin de deux engines : Transit pour les opérations sur les clés, et KV v2 pour les métadonnées de clés qu'il maintient. Créez des montages dédiés : + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-transit transit +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-meta -version=2 kv +``` + +Écrivez une politique accordant exactement ce dont le client KMS de RustFS a besoin — la gestion des clés Transit y compris LIST (la sonde de démarrage en dépend), les opérations de chiffrement, et les chemins data et metadata KV v2 pour le préfixe configuré : + +```hcl title="rustfs-kms.hcl" +path "rustfs-transit/keys" { + capabilities = ["list"] +} +path "rustfs-transit/keys/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +path "rustfs-transit/encrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/decrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/rewrap/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/keys/*/rotate" { + capabilities = ["update"] +} +path "rustfs-transit/keys/*/config" { + capabilities = ["read", "update"] +} +path "rustfs-meta/data/rustfs/kms/keys/*" { + capabilities = ["create", "update", "read"] +} +path "rustfs-meta/metadata/rustfs/kms/keys/*" { + capabilities = ["read", "list", "delete"] +} +``` + +Chargez la politique et émettez un jeton orphelin : + +```bash +docker cp rustfs-kms.hcl openbao:/tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao policy write rustfs-kms /tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao token create -policy=rustfs-kms -orphan -format=json +``` + +Stockez le jeton sur l'hôte RustFS. Le fichier doit être lisible par le seul propriétaire et appartenir au compte de service `rustfs` — RustFS refuse les bits de lecture de groupe et autres : + +```bash +install -d -m 0755 -o rustfs -g rustfs /data/rustfs/kms +install -m 0600 -o rustfs -g rustfs /dev/null /data/rustfs/kms/openbao-token +# write the token into /data/rustfs/kms/openbao-token +cp /data/openbao/tls/ca.pem /data/rustfs/kms/openbao-ca.pem +``` + +## 3. Configurer RustFS + +Ajoutez les réglages KMS au fichier d'environnement RustFS et redémarrez : + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_ENABLE=true +RUSTFS_KMS_BACKEND=vault-transit +RUSTFS_KMS_VAULT_ADDRESS=https://127.0.0.1:8200 +RUSTFS_KMS_VAULT_MOUNT_PATH=rustfs-transit +RUSTFS_KMS_VAULT_TOKEN_FILE=/data/rustfs/kms/openbao-token +RUSTFS_KMS_VAULT_TRANSIT_METADATA_KV_MOUNT=rustfs-meta +RUSTFS_KMS_VAULT_TRANSIT_METADATA_PREFIX=rustfs/kms/keys +RUSTFS_KMS_VAULT_CA_CERT=/data/rustfs/kms/openbao-ca.pem +``` + +```bash +sudo systemctl restart rustfs +``` + +Si la validation du backend échoue, RustFS refuse de démarrer et nomme le problème exact dans le journal — voir [Dépannage](#dépannage). Une fois démarré, consultez l'état KMS dans la console sous **Paramètres SSE**, ou via l'API d'administration : + +```bash +curl -s http://localhost:9000/rustfs/admin/v3/kms/service-status +``` + +La réponse indique `"backend_type":"VaultTransit"` avec `"healthy":true`, l'adresse configurée, le chemin de montage et l'usage éventuel d'un CA personnalisé. + +## 4. Créer une clé et sélectionner la clé par défaut + +La console expose le cycle de vie KMS complet sous **Paramètres SSE** : vue d'état, gestion des clés (création, suppression en deux temps), configuration du backend et balayages de re-chiffrement des objets existants. + +Créez une clé dans **KMS Keys Management** — RustFS crée ensemble la clé Transit correspondante dans OpenBao et son enregistrement de métadonnées dans le montage KV v2. Définissez ensuite la **clé SSE par défaut** dans la console ou via l'environnement : + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_DEFAULT_KEY_ID=rustfs-e2e-key +``` + +Redémarrez RustFS après avoir changé la clé par défaut. Une clé créée directement dans OpenBao sans passer par RustFS laisse l'enregistrement de métadonnées KV v2 manquant — créez les clés côté RustFS. + +![Page Paramètres SSE de la console RustFS montrant le backend VaultTransit, la liste des clés et la configuration KMS](./images/rustfs-kms-console.png) + +## 5. Vérifier le SSE-KMS de bout en bout + +Définissez la valeur par défaut du bucket ou transmettez la clé à chaque écriture. La réponse de téléversement renvoie l'algorithme de chiffrement et l'ID de clé, et le téléchargement restitue les octets d'origine : + +```bash +aws s3api put-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt \ + --body ./e2e-check.txt \ + --server-side-encryption aws:kms \ + --ssekms-key-id rustfs-e2e-key +``` + +```json +{ + "ETag": "\"57a02aed...\"", + "ServerSideEncryption": "aws:kms", + "SSEKMSKeyId": "rustfs-e2e-key" +} +``` + +```bash +aws s3api get-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt ./e2e-check-back.txt +``` + +## Résultats de validation + +Les vérifications suivantes ont été exécutées sur un déploiement OpenBao 2.7.2 réel et doivent passer sur tout environnement sain : + +| Vérification | Résultat attendu | +| --- | --- | +| SSE-KMS PUT/GET avec l'ID de clé | La réponse renvoie `aws:kms` et l'ID de clé ; les octets téléchargés correspondent | +| GET par plage sur un objet chiffré | La plage d'octets est restituée correctement | +| Redémarrage de RustFS | Les métadonnées des clés se rétablissent depuis KV v2 ; les objets chiffrés restent lisibles | +| Redémarrage d'OpenBao (scealed) | Les lectures chiffrées échouent avec `ServiceUnavailable` — aucun repli en clair ; après le désceal, les lectures se rétablissent automatiquement dans l'intervalle de sonde | +| Rotation de la clé Transit | `latest_version` augmente avec les versions antérieures conservées ; les objets enveloppés avant la rotation restent lisibles | +| Ciphertext falsifié sur le stockage | Les lectures échouent et la suppression est refusée ; aucun repli en clair | +| Contexte de chiffrement erroné | Le déchiffrement Transit échoue avec une erreur d'authentification de message | + +Note sur la disposition du stockage : les petits objets rangent leurs octets chiffrés en ligne dans le fichier `xl.meta` de chaque disque — un grep du texte clair dans le répertoire de l'objet reste donc vide alors que les données s'y trouvent. + +## Dépannage + +### Le démarrage échoue avec `Vault Transit requires HTTPS outside explicit development mode` + +L'adresse du KMS n'est pas en HTTPS. Configurez TLS sur OpenBao et faites confiance à son CA via `RUSTFS_KMS_VAULT_CA_CERT`. L'échappatoire `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` est réservé au développement. + +### Le démarrage échoue avec `Vault token file ... has insecure permissions 0o644` + +Le fichier de jeton doit être en `0600` sans bits de lecture groupe ni autres, et appartenir au compte de service RustFS : + +```bash +chown rustfs:rustfs /data/rustfs/kms/openbao-token +chmod 600 /data/rustfs/kms/openbao-token +``` + +### Les lectures échouent avec `ServiceUnavailable` tant qu'OpenBao est scealé + +Comportement attendu : les lectures chiffrées exigent le KMS externe. Déscealez OpenBao ; RustFS se rétablit automatiquement à sa prochaine sonde KMS — sans redémarrer RustFS. + +### Le transit OpenBao déchiffre avec un mauvais paramètre `context` + +Pour les clés non dérivées, le transit ignore `context` et lie le contexte de chiffrement S3 comme `associated_data`. Un `associated_data` erroné échoue avec `cipher: message authentication failed`. En testant la liaison manuellement via `bao`, transmettez `associated_data`, pas `context`. + +### Un objet chiffré falsifié ne peut être ni lu ni supprimé + +Les deux chemins échouent par conception — la suppression vérifie aussi les métadonnées stockées. Retirez les répertoires de l'objet sur chaque disque pendant que RustFS est arrêté, puis redémarrez. + +## Notes de production + +Le déploiement OpenBao mono-nœud ci-dessus laisse l'unseal manuel et le stockage local. En production : exécutez OpenBao en cluster avec réplication de stockage intégrée ou un mécanisme d'auto-unseal, protégez les éléments d'unseal et la sauvegarde des données raft indépendamment des sauvegardes RustFS, et figez la version d'OpenBao — validez le client vaultrs contre chaque mise à niveau d'OpenBao avant de la déployer. + +## Prochaines étapes + +- Consultez la vue d'ensemble des backends et le chiffrement par défaut des buckets dans [SSE-KMS](./kms.md). +- Lisez les [notes de compatibilité S3](/administration/protocols/s3) avant d'adopter d'autres fonctions SSE. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). diff --git a/content/ja/security-compliance/encryption/images/rustfs-kms-console.png b/content/ja/security-compliance/encryption/images/rustfs-kms-console.png new file mode 100644 index 00000000..9bd6ed51 Binary files /dev/null and b/content/ja/security-compliance/encryption/images/rustfs-kms-console.png differ diff --git a/content/ja/security-compliance/encryption/kms.md b/content/ja/security-compliance/encryption/kms.md index d8a72c60..f9c136c0 100644 --- a/content/ja/security-compliance/encryption/kms.md +++ b/content/ja/security-compliance/encryption/kms.md @@ -89,6 +89,9 @@ RUSTFS_KMS_VAULT_MOUNT_PATH=transit Vault Transit は過去の鍵バージョンを保持するため、Transit 鍵をローテーションしても、それだけでは古いバージョンでラップされたオブジェクトが読めなくなることはありません。オブジェクトが依存している間は、古いバージョンを有効なままにします。 +OpenBao の完全なデプロイ手順(TLS 設定、シークレットエンジン、最小権限ポリシー、エンドツーエンドの SSE-KMS 検証)は [OpenBao](./openbao.md) を参照してください。OpenBao は Vault の API サーフェスを維持しているため、同じ `vault-transit` バックエンドが適用されます。 + + ## デフォルト鍵を作成して選択する `RUSTFS_KMS_DEFAULT_KEY_ID` は既存の鍵を選択します。鍵は作成しません。この変数なしで KMS バックエンドを起動し、鍵を作成してから、変数を追加して RustFS を再起動します。 diff --git a/content/ja/security-compliance/encryption/meta.json b/content/ja/security-compliance/encryption/meta.json index 657e0e6a..6d1fe5d6 100644 --- a/content/ja/security-compliance/encryption/meta.json +++ b/content/ja/security-compliance/encryption/meta.json @@ -3,6 +3,7 @@ "pages": [ "sse-s", "sse-c", - "kms" + "kms", + "openbao" ] -} \ No newline at end of file +} diff --git a/content/ja/security-compliance/encryption/openbao.md b/content/ja/security-compliance/encryption/openbao.md new file mode 100644 index 00000000..454fe151 --- /dev/null +++ b/content/ja/security-compliance/encryption/openbao.md @@ -0,0 +1,269 @@ +--- +title: "OpenBao" +description: "Vault Transit バックエンド経由で OpenBao を RustFS SSE-KMS の外部 KMS としてデプロイする。" +--- + +[OpenBao](https://github.com/openbao/openbao) は HashiCorp Vault のオープンソースフォークです。RustFS は Vault Transit バックエンドで外部 KMS を介して SSE-KMS キーを管理し、OpenBao は同じ API サーフェスを維持しています。そのため RustFS のコード変更は不要で、統合は設定のみで完結します。このガイドでは OpenBao をデプロイし、シークレットエンジンと最小権限トークンを準備し、RustFS を設定して、SSE-KMS をエンドツーエンドで検証します。このワークフローは RustFS `1.0.5` と OpenBao `2.7.2` で検証しました。 + +OpenBao ホストの Docker と、RustFS 1.0.5 以降のサーバーが必要です。このガイドは統合テスト用のシングルノードデプロイです。本番ではクラスター化された OpenBao と管理されたアンシールが追加で必要になります。詳細は末尾を参照してください。 + +## アーキテクチャ + +```mermaid +flowchart LR + Console["Console / S3 API"] --> RustFS["RustFS"] + RustFS -->|"wrap, unwrap, rewrap
Transit key ops"| OpenBao["OpenBao :8200"] + RustFS -->|"key metadata
KV v2 CAS"| OpenBao + OpenBao -->|"raft storage"| Disk["Sealed storage"] +``` + +RustFS はオブジェクトごとのデータキーをローカルで生成し、OpenBao の Transit エンジン経由でラップします。キーのライフサイクルメタデータは CAS 書き込み付きの KV v2 マウントに保持されます。マスターキーのバージョンは OpenBao が保持するため、OpenBao が停止すると、新しい SSE-KMS 書き込みと暗号化オブジェクトの読み取りは、到達可能かつアンシールされるまで停止します。 + +## 1. TLS と raft ストレージ付きで OpenBao をデプロイする + +RustFS は KMS への平文 HTTP を拒否します。起動時に `Vault Transit requires HTTPS outside explicit development mode` で失敗します。最初から OpenBao に TLS を設定してください。ディレクトリ構成と、統合 raft ストレージを使う設定を作成します: + +```bash +mkdir -p /data/openbao/{data,config,tls} +openssl req -x509 -newkey rsa:4096 -sha256 -days 825 -nodes \ + -keyout /data/openbao/tls/ca-key.pem -out /data/openbao/tls/ca.pem \ + -subj "/CN=openbao-demo-ca" +openssl req -newkey rsa:2048 -nodes -keyout /data/openbao/tls/server-key.pem \ + -out /data/openbao/tls/server.csr -subj "/CN=openbao-host" +openssl x509 -req -in /data/openbao/tls/server.csr \ + -CA /data/openbao/tls/ca.pem -CAkey /data/openbao/tls/ca-key.pem \ + -CAcreateserial -out /data/openbao/tls/server-cert.pem -days 825 -sha256 \ + -extfile <(printf "subjectAltName=IP:127.0.0.1,DNS:localhost,DNS:openbao-host") +``` + +```hcl title="/data/openbao/config/config.hcl" +storage "raft" { + path = "/openbao/data" + node_id = "openbao-1" +} +listener "tcp" { + address = "0.0.0.0:8200" + cluster_address = "0.0.0.0:8201" + tls_disable = 0 + tls_cert_file = "/openbao/tls/server-cert.pem" + tls_key_file = "/openbao/tls/server-key.pem" +} +api_addr = "https://127.0.0.1:8200" +cluster_addr = "https://127.0.0.1:8201" +disable_mlock = true +ui = false +``` + +データ・設定・TLS ディレクトリをマウントしてコンテナを起動します。各バインドマウントはコンテナプロセスから書き込み可能である必要があります: + +```bash +chmod -R a+rX /data/openbao/tls +chmod 777 /data/openbao/data +docker run -d --name openbao --restart unless-stopped \ + -p 127.0.0.1:8200:8200 \ + -v /data/openbao/data:/openbao/data \ + -v /data/openbao/config:/openbao/config \ + -v /data/openbao/tls:/openbao/tls \ + openbao/openbao:2.7.2 server +``` + +キーシェア 1 つで初期化し、アンシールします。アンシールキーとルートトークンは一度しか表示されないため、安全に保管してください: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator init -key-shares=1 -key-threshold=1 -format=json +``` + +コンテナを再起動するたびに再度アンシールします: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator unseal +``` + +## 2. シークレットエンジンを有効化し、スコープ限定トークンを作成する + +RustFS には 2 つのエンジンが必要です。キー操作のための Transit と、RustFS が管理するキーメタデータのための KV v2 です。専用のマウントを作成します: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-transit transit +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-meta -version=2 kv +``` + +RustFS の KMS クライアントが必要とする権限だけを与えるポリシーを書きます。Transit キー管理(起動プローブが依存する LIST を含む)、暗号化操作、設定したプレフィックスに対応する KV v2 の data と metadata パスです: + +```hcl title="rustfs-kms.hcl" +path "rustfs-transit/keys" { + capabilities = ["list"] +} +path "rustfs-transit/keys/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +path "rustfs-transit/encrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/decrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/rewrap/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/keys/*/rotate" { + capabilities = ["update"] +} +path "rustfs-transit/keys/*/config" { + capabilities = ["read", "update"] +} +path "rustfs-meta/data/rustfs/kms/keys/*" { + capabilities = ["create", "update", "read"] +} +path "rustfs-meta/metadata/rustfs/kms/keys/*" { + capabilities = ["read", "list", "delete"] +} +``` + +ポリシーを読み込み、orphan トークンを発行します: + +```bash +docker cp rustfs-kms.hcl openbao:/tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao policy write rustfs-kms /tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao token create -policy=rustfs-kms -orphan -format=json +``` + +トークンを RustFS ホストに保存します。ファイルは所有者のみが読める権限で、`rustfs` サービスアカウントの所有である必要があります。グループやその他の読み取りビットがあると RustFS は拒否します: + +```bash +install -d -m 0755 -o rustfs -g rustfs /data/rustfs/kms +install -m 0600 -o rustfs -g rustfs /dev/null /data/rustfs/kms/openbao-token +# write the token into /data/rustfs/kms/openbao-token +cp /data/openbao/tls/ca.pem /data/rustfs/kms/openbao-ca.pem +``` + +## 3. RustFS を設定する + +KMS 設定を RustFS の環境ファイルに追加して再起動します: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_ENABLE=true +RUSTFS_KMS_BACKEND=vault-transit +RUSTFS_KMS_VAULT_ADDRESS=https://127.0.0.1:8200 +RUSTFS_KMS_VAULT_MOUNT_PATH=rustfs-transit +RUSTFS_KMS_VAULT_TOKEN_FILE=/data/rustfs/kms/openbao-token +RUSTFS_KMS_VAULT_TRANSIT_METADATA_KV_MOUNT=rustfs-meta +RUSTFS_KMS_VAULT_TRANSIT_METADATA_PREFIX=rustfs/kms/keys +RUSTFS_KMS_VAULT_CA_CERT=/data/rustfs/kms/openbao-ca.pem +``` + +```bash +sudo systemctl restart rustfs +``` + +バックエンドの検証に失敗すると、RustFS は起動を拒否し、ログに具体的な原因を出力します。[トラブルシューティング](#トラブルシューティング)を参照してください。起動すれば、コンソールの **SSE 設定**または管理 API で KMS の状態を確認できます: + +```bash +curl -s http://localhost:9000/rustfs/admin/v3/kms/service-status +``` + +レスポンスは `"backend_type":"VaultTransit"` と `"healthy":true`、設定したアドレス、マウントパス、カスタム CA の使用有無を報告します。 + +## 4. キーを作成し、デフォルトを選択する + +コンソールの **SSE 設定** には KMS のライフサイクル全体が用意されています。状態概要、キー管理(作成、二段階削除)、バックエンド設定、既存オブジェクトの再暗号化スイープです。 + +**KMS Keys Management** でキーを作成すると、RustFS は OpenBao 内の対応する Transit キーと、KV v2 マウント内のメタデータレコードを同時に作成します。その後、コンソールまたは環境変数で **デフォルト SSE キー** を設定します: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_DEFAULT_KEY_ID=rustfs-e2e-key +``` + +デフォルトを変更したら RustFS を再起動してください。RustFS を経由せずに OpenBao で直接キーを作成すると、KV v2 のメタデータレコードが欠落します。キーは RustFS 側から作成してください。 + +![VaultTransit バックエンド・キーリスト・KMS 設定を示す RustFS コンソールの SSE 設定ページ](./images/rustfs-kms-console.png) + +## 5. SSE-KMS をエンドツーエンドで検証する + +バケットのデフォルトを設定するか、書き込みごとにキーを指定します。アップロードのレスポンスは暗号化アルゴリズムとキー ID を返し、ダウンロードは元のバイト列を返します: + +```bash +aws s3api put-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt \ + --body ./e2e-check.txt \ + --server-side-encryption aws:kms \ + --ssekms-key-id rustfs-e2e-key +``` + +```json +{ + "ETag": "\"57a02aed...\"", + "ServerSideEncryption": "aws:kms", + "SSEKMSKeyId": "rustfs-e2e-key" +} +``` + +```bash +aws s3api get-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt ./e2e-check-back.txt +``` + +## 検証結果 + +以下の検査は稼働中の OpenBao 2.7.2 デプロイに対して実施したもので、健全な環境では同じ結果になります: + +| 検査 | 期待される結果 | +| --- | --- | +| キー ID を使った SSE-KMS PUT/GET | レスポンスが `aws:kms` とキー ID を返し、ダウンロードしたバイト列が一致 | +| 暗号化オブジェクトへの Range GET | バイト範囲が正しく返る | +| RustFS の再起動 | キーメタデータが KV v2 から復元され、暗号化オブジェクトは読み取り可能のまま | +| OpenBao の再起動(sealed) | 暗号化読み取りは `ServiceUnavailable` で失敗し、平文へのフォールバックなし。アンシール後、読み取りはプローブ間隔で自動回復 | +| Transit キーのローテーション | `latest_version` が増加し旧バージョンは保持される。ローテーション前にラップされたオブジェクトは読み取り可能のまま | +| ストレージ上の暗号文の改ざん | 読み取りが失敗し、削除も拒否される。平文へのフォールバックなし | +| 誤った暗号化コンテキスト | Transit の復号がメッセージ認証エラーで失敗する | + +ストレージレイアウトに関する注記:小さいオブジェクトは暗号化済みバイトを各ディスクの `xl.meta` ファイルにインラインで格納します。そのためオブジェクトディレクトリへの平文 grep は、データが存在してもヒットしません。 + +## トラブルシューティング + +### 起動が `Vault Transit requires HTTPS outside explicit development mode` で失敗する + +KMS アドレスが HTTPS ではありません。OpenBao に TLS を設定し、`RUSTFS_KMS_VAULT_CA_CERT` でその CA を信頼してください。逃げ道の `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` は開発専用です。 + +### 起動が `Vault token file ... has insecure permissions 0o644` で失敗する + +トークンファイルは `0600` 権限(グループとその他のビットなし)で、RustFS サービスアカウントの所有である必要があります: + +```bash +chown rustfs:rustfs /data/rustfs/kms/openbao-token +chmod 600 /data/rustfs/kms/openbao-token +``` + +### OpenBao が sealed の間に読み取りが `ServiceUnavailable` で失敗する + +想定された動作です。暗号化読み取りには外部 KMS が必要です。OpenBao をアンシールしてください。RustFS は次の KMS プローブで自動的に回復し、RustFS の再起動は不要です。 + +### OpenBao transit が誤った `context` パラメータでも復号できる + +派生なしキーでは、transit は `context` を無視し、S3 の暗号化コンテキストを `associated_data` としてバインドします。誤った `associated_data` は `cipher: message authentication failed` で失敗します。`bao` で手動テストする際は `context` ではなく `associated_data` を渡してください。 + +### 改ざんされた暗号化オブジェクトが読めず、削除もできない + +どちらの経路も設計どおり失敗します。削除時にも保存されたメタデータが検証されます。RustFS を停止してから全ディスクのオブジェクトディレクトリを削除し、再起動してください。 + +## 本番の注意点 + +上記のシングルノード OpenBao はアンシールが手動で、ストレージもローカルです。本番では、統合ストレージレプリケーションまたはオートアンシール機構を備えたクラスターで OpenBao を実行し、アンシール credentials と raft データのバックアップを RustFS のバックアップとは独立に保護し、OpenBao のバージョンを固定してください。OpenBao をアップグレードする前に、そのバージョンに対して vaultrs クライアントを検証してください。 + +## 次のステップ + +- バックエンドの概要とバケットデフォルト暗号化は [SSE-KMS](./kms.md) を参照してください。 +- さらなる SSE 機能を採用する前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 diff --git a/content/zh/security-compliance/encryption/images/rustfs-kms-console.png b/content/zh/security-compliance/encryption/images/rustfs-kms-console.png new file mode 100644 index 00000000..0bce9bb2 Binary files /dev/null and b/content/zh/security-compliance/encryption/images/rustfs-kms-console.png differ diff --git a/content/zh/security-compliance/encryption/kms.md b/content/zh/security-compliance/encryption/kms.md index b01f97da..ce7bd935 100644 --- a/content/zh/security-compliance/encryption/kms.md +++ b/content/zh/security-compliance/encryption/kms.md @@ -89,6 +89,9 @@ RUSTFS_KMS_VAULT_MOUNT_PATH=transit Vault Transit 会保留历史密钥版本,因此轮换 Transit 密钥本身不会导致使用旧版本封装的对象无法读取。只要仍有对象依赖旧版本,就应保持这些版本启用。 +完整的 OpenBao 部署指引(TLS 设置、密钥引擎、最小权限策略与端到端 SSE-KMS 验证)见 [OpenBao](./openbao.md)。OpenBao 保持 Vault 的 API 接口,因此同样适用 `vault-transit` 后端。 + + ## 创建并选择默认密钥 `RUSTFS_KMS_DEFAULT_KEY_ID` 用于选择现有密钥,不会创建密钥。启动 KMS 后端时先不设置此变量,创建密钥后再添加该变量并重启 RustFS。 diff --git a/content/zh/security-compliance/encryption/meta.json b/content/zh/security-compliance/encryption/meta.json index d9d9f314..a1eb073f 100644 --- a/content/zh/security-compliance/encryption/meta.json +++ b/content/zh/security-compliance/encryption/meta.json @@ -3,6 +3,7 @@ "pages": [ "sse-s", "sse-c", - "kms" + "kms", + "openbao" ] -} \ No newline at end of file +} diff --git a/content/zh/security-compliance/encryption/openbao.md b/content/zh/security-compliance/encryption/openbao.md new file mode 100644 index 00000000..3033baf0 --- /dev/null +++ b/content/zh/security-compliance/encryption/openbao.md @@ -0,0 +1,269 @@ +--- +title: "OpenBao" +description: "通过 Vault Transit 后端把 OpenBao 部署为 RustFS SSE-KMS 的外部 KMS。" +--- + +[OpenBao](https://github.com/openbao/openbao) 是 HashiCorp Vault 的开源分支。RustFS 通过其 Vault Transit 后端使用外部 KMS 管理 SSE-KMS 密钥,而 OpenBao 保持相同的 API 接口,因此无需修改 RustFS 代码——集成只需要配置。本指南部署 OpenBao、准备密钥引擎和最小权限令牌、配置 RustFS,并端到端验证 SSE-KMS。整个流程在 RustFS `1.0.5` 与 OpenBao `2.7.2` 上验证通过。 + +你需要 OpenBao 宿主机上的 Docker 和一台 RustFS 1.0.5+ 服务器。本指南是用于集成测试的单节点部署;生产部署还需要集群化 OpenBao 与托管解封,见文末说明。 + +## 架构 + +```mermaid +flowchart LR + Console["Console / S3 API"] --> RustFS["RustFS"] + RustFS -->|"wrap, unwrap, rewrap
Transit key ops"| OpenBao["OpenBao :8200"] + RustFS -->|"key metadata
KV v2 CAS"| OpenBao + OpenBao -->|"raft storage"| Disk["Sealed storage"] +``` + +RustFS 在本地生成每对象数据密钥,并通过 OpenBao Transit 引擎包装;密钥生命周期元数据保存在 KV v2 挂载中(带 CAS 写入)。OpenBao 持有主密钥版本,因此 OpenBao 不可用时,新的 SSE-KMS 写入和已加密对象的读取会暂停,直到它恢复可达并完成解封。 + +## 1. 部署带 TLS 和 raft 存储的 OpenBao + +RustFS 拒绝明文 HTTP 连接 KMS:启动即报 `Vault Transit requires HTTPS outside explicit development mode`。一开始就给 OpenBao 配好 TLS。创建目录结构和使用 raft 集成存储的配置: + +```bash +mkdir -p /data/openbao/{data,config,tls} +openssl req -x509 -newkey rsa:4096 -sha256 -days 825 -nodes \ + -keyout /data/openbao/tls/ca-key.pem -out /data/openbao/tls/ca.pem \ + -subj "/CN=openbao-demo-ca" +openssl req -newkey rsa:2048 -nodes -keyout /data/openbao/tls/server-key.pem \ + -out /data/openbao/tls/server.csr -subj "/CN=openbao-host" +openssl x509 -req -in /data/openbao/tls/server.csr \ + -CA /data/openbao/tls/ca.pem -CAkey /data/openbao/tls/ca-key.pem \ + -CAcreateserial -out /data/openbao/tls/server-cert.pem -days 825 -sha256 \ + -extfile <(printf "subjectAltName=IP:127.0.0.1,DNS:localhost,DNS:openbao-host") +``` + +```hcl title="/data/openbao/config/config.hcl" +storage "raft" { + path = "/openbao/data" + node_id = "openbao-1" +} +listener "tcp" { + address = "0.0.0.0:8200" + cluster_address = "0.0.0.0:8201" + tls_disable = 0 + tls_cert_file = "/openbao/tls/server-cert.pem" + tls_key_file = "/openbao/tls/server-key.pem" +} +api_addr = "https://127.0.0.1:8200" +cluster_addr = "https://127.0.0.1:8201" +disable_mlock = true +ui = false +``` + +挂载数据、配置和 TLS 目录启动容器。这些 bind mount 必须对容器进程可写: + +```bash +chmod -R a+rX /data/openbao/tls +chmod 777 /data/openbao/data +docker run -d --name openbao --restart unless-stopped \ + -p 127.0.0.1:8200:8200 \ + -v /data/openbao/data:/openbao/data \ + -v /data/openbao/config:/openbao/config \ + -v /data/openbao/tls:/openbao/tls \ + openbao/openbao:2.7.2 server +``` + +以单密钥分片初始化并解封。妥善保存解封密钥和 root 令牌——它们只显示一次: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator init -key-shares=1 -key-threshold=1 -format=json +``` + +每次容器重启后需再次解封: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + openbao bao operator unseal +``` + +## 2. 启用密钥引擎并创建受限令牌 + +RustFS 需要两个引擎:用于密钥操作的 Transit,以及存放它所维护密钥元数据的 KV v2。创建专用挂载: + +```bash +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-transit transit +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao secrets enable -path=rustfs-meta -version=2 kv +``` + +编写策略,只授予 RustFS KMS 客户端所需权限——Transit 密钥管理含 LIST(启动探测依赖它)、加密操作,以及已配置前缀对应的 KV v2 data 与 metadata 路径: + +```hcl title="rustfs-kms.hcl" +path "rustfs-transit/keys" { + capabilities = ["list"] +} +path "rustfs-transit/keys/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +path "rustfs-transit/encrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/decrypt/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/rewrap/*" { + capabilities = ["create", "update"] +} +path "rustfs-transit/keys/*/rotate" { + capabilities = ["update"] +} +path "rustfs-transit/keys/*/config" { + capabilities = ["read", "update"] +} +path "rustfs-meta/data/rustfs/kms/keys/*" { + capabilities = ["create", "update", "read"] +} +path "rustfs-meta/metadata/rustfs/kms/keys/*" { + capabilities = ["read", "list", "delete"] +} +``` + +加载策略并签发 orphan 令牌: + +```bash +docker cp rustfs-kms.hcl openbao:/tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao policy write rustfs-kms /tmp/rustfs-kms.hcl +docker exec -e BAO_ADDR=https://127.0.0.1:8200 -e BAO_CACERT=/openbao/tls/ca.pem \ + -e BAO_TOKEN= openbao \ + bao token create -policy=rustfs-kms -orphan -format=json +``` + +把令牌存放到 RustFS 宿主机。文件必须是属主只读权限并归 `rustfs` 服务账号所有——RustFS 会拒绝组或其他用户的读权限: + +```bash +install -d -m 0755 -o rustfs -g rustfs /data/rustfs/kms +install -m 0600 -o rustfs -g rustfs /dev/null /data/rustfs/kms/openbao-token +# write the token into /data/rustfs/kms/openbao-token +cp /data/openbao/tls/ca.pem /data/rustfs/kms/openbao-ca.pem +``` + +## 3. 配置 RustFS + +把 KMS 配置加入 RustFS 环境文件并重启: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_ENABLE=true +RUSTFS_KMS_BACKEND=vault-transit +RUSTFS_KMS_VAULT_ADDRESS=https://127.0.0.1:8200 +RUSTFS_KMS_VAULT_MOUNT_PATH=rustfs-transit +RUSTFS_KMS_VAULT_TOKEN_FILE=/data/rustfs/kms/openbao-token +RUSTFS_KMS_VAULT_TRANSIT_METADATA_KV_MOUNT=rustfs-meta +RUSTFS_KMS_VAULT_TRANSIT_METADATA_PREFIX=rustfs/kms/keys +RUSTFS_KMS_VAULT_CA_CERT=/data/rustfs/kms/openbao-ca.pem +``` + +```bash +sudo systemctl restart rustfs +``` + +如果后端校验失败,RustFS 会拒绝启动并在日志中写明具体原因——见[故障排查](#故障排查)。启动成功后,在控制台 **SSE 设置**下查看 KMS 状态,或通过管理 API: + +```bash +curl -s http://localhost:9000/rustfs/admin/v3/kms/service-status +``` + +响应会报告 `"backend_type":"VaultTransit"`、`"healthy":true`、配置的地址、挂载路径以及是否使用自定义 CA。 + +## 4. 创建密钥并设置默认密钥 + +控制台在 **SSE 设置**下提供完整 KMS 生命周期:状态概览、密钥管理(创建、两段式删除)、后端配置,以及针对存量对象的重加密扫描。 + +在 **KMS 密钥管理**中创建密钥——RustFS 会同时在 OpenBao 里创建对应的 Transit 密钥,并在 KV v2 挂载中写入其元数据记录。然后在控制台或通过环境变量设置**默认 SSE 密钥**: + +```ini title="/etc/default/rustfs" +RUSTFS_KMS_DEFAULT_KEY_ID=rustfs-e2e-key +``` + +修改默认密钥后重启 RustFS。绕过 RustFS 直接在 OpenBao 里建密钥会缺少 KV v2 元数据记录——请从 RustFS 侧创建密钥。 + +![RustFS 控制台 SSE 设置页,展示 VaultTransit 后端、密钥列表与 KMS 配置](./images/rustfs-kms-console.png) + +## 5. 端到端验证 SSE-KMS + +设置桶默认加密,或在写入时指定密钥。上传响应会回显加密算法和密钥 ID,下载返回原始字节: + +```bash +aws s3api put-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt \ + --body ./e2e-check.txt \ + --server-side-encryption aws:kms \ + --ssekms-key-id rustfs-e2e-key +``` + +```json +{ + "ETag": "\"57a02aed...\"", + "ServerSideEncryption": "aws:kms", + "SSEKMSKeyId": "rustfs-e2e-key" +} +``` + +```bash +aws s3api get-object \ + --endpoint-url http://localhost:9000 \ + --bucket my-bucket --key docs/e2e-check.txt ./e2e-check-back.txt +``` + +## 验证结果 + +以下检查已在真实的 OpenBao 2.7.2 部署上执行,任何健康环境都应得到相同结果: + +| 检查项 | 预期结果 | +| --- | --- | +| 使用密钥 ID 的 SSE-KMS PUT/GET | 响应回显 `aws:kms` 和密钥 ID;下载字节一致 | +| 加密对象的 Range GET | 字节区间正确返回 | +| RustFS 重启 | 密钥元数据从 KV v2 恢复;加密对象保持可读 | +| OpenBao 重启(sealed) | 加密读取失败并报 `ServiceUnavailable`——无明文回退;解封后读取在探测周期内自动恢复 | +| Transit 密钥轮换 | `latest_version` 递增且保留旧版本;轮换前包装的对象保持可读 | +| 存储上密文被篡改 | 读取失败且删除被拒绝;无明文回退 | +| 错误的加密上下文 | Transit 解密失败并报消息认证错误 | + +存储布局说明:小对象的加密字节内联存放在每块盘的 `xl.meta` 文件中,因此对对象目录 grep 明文不会命中,尽管数据就在那里。 + +## 故障排查 + +### 启动失败并报 `Vault Transit requires HTTPS outside explicit development mode` + +KMS 地址不是 HTTPS。给 OpenBao 配置 TLS,并通过 `RUSTFS_KMS_VAULT_CA_CERT` 信任其 CA。逃生开关 `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` 仅供开发使用。 + +### 启动失败并报 `Vault token file ... has insecure permissions 0o644` + +令牌文件必须是 `0600` 权限(组和其他位清零),且归 RustFS 服务账号所有: + +```bash +chown rustfs:rustfs /data/rustfs/kms/openbao-token +chmod 600 /data/rustfs/kms/openbao-token +``` + +### OpenBao sealed 期间读取报 `ServiceUnavailable` + +预期行为:加密读取依赖外部 KMS。解封 OpenBao;RustFS 会在下一次 KMS 探测时自动恢复——无需重启 RustFS。 + +### OpenBao transit 用错误的 `context` 参数也能解密 + +对非派生密钥,transit 会忽略 `context`,并把 S3 加密上下文绑定为 `associated_data`。错误的 `associated_data` 会以 `cipher: message authentication failed` 失败。手工通过 `bao` 测试绑定时请传 `associated_data`,而不是 `context`。 + +### 被篡改的加密对象无法读取也无法删除 + +两条路径失败都是设计使然——删除同样会校验存储的元数据。停止 RustFS 后从每块盘删除对象目录,再重启。 + +## 生产建议 + +上面的单节点 OpenBao 部署解封靠手动、存储在本地。生产环境:以集群方式运行 OpenBao(集成存储复制或自动解封机制),把解封凭据和 raft 数据备份独立于 RustFS 备份保护起来,并锁定 OpenBao 版本——每次升级前先验证 vaultrs 客户端。 + +## 下一步 + +- 查阅 [SSE-KMS](./kms.md) 中的后端总览与桶默认加密。 +- 在采用更多 SSE 特性前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。