=========================== HashiCorp Vault Integration =========================== HashiCorp `Vault`_ can be used as a secure key management service for `Server-Side Encryption`_ (SSE-KMS). .. ditaa:: +---------+ +---------+ +-------+ +-------+ | Client | | RadosGW | | Vault | | OSD | +---------+ +---------+ +-------+ +-------+ | create secret | | | | key for key ID | | | |-----------------+---------------->| | | | | | | upload object | | | | with key ID | | | |---------------->| request secret | | | | key for key ID | | | |---------------->| | | |<----------------| | | | return secret | | | | key | | | | | | | | encrypt object | | | | with secret key | | | |--------------+ | | | | | | | | |<-------------+ | | | | | | | | store encrypted | | | | object | | | |------------------------------>| #. `Vault secrets engines`_ #. `Vault authentication`_ #. `Vault namespaces`_ #. `Create a key in Vault`_ #. `Configure the Ceph Object Gateway`_ #. `Upload object`_ Some examples below use the Vault command line utility to interact with Vault. You may need to set the following environment variable with the correct address of your Vault server to use this utility:: export VAULT_ADDR='http://vault-server:8200' Vault secrets engines ===================== Vault provides several secrets engines, which can store, generate, and encrypt data. Currently, the Object Gateway supports: - `KV secrets engine`_ version 2 - `Transit engine`_ KV secrets engine ----------------- The KV secrets engine is used to store arbitrary key/value secrets in Vault. To enable the KV engine version 2 in Vault, use the following command:: vault secrets enable -path secret kv-v2 The Object Gateway can be configured to use the KV engine version 2 with the following setting:: rgw crypt vault secret engine = kv Transit secrets engine ---------------------- The transit engine handles cryptographic functions on data in-transit. To enable it in Vault, use the following command:: vault secrets enable transit The Object Gateway can be configured to use the transit engine with the following setting:: rgw crypt vault secret engine = transit Vault authentication ==================== Vault supports several authentication mechanisms. Currently, the Object Gateway can be configured to authenticate to Vault using the `Token authentication method`_ or a `Vault agent`_. Token authentication -------------------- .. note:: Token authentication is not recommended for production environments. The token authentication method expects a Vault token to be present in a plaintext file. The Object Gateway can be configured to use token authentication with the following settings:: rgw crypt vault auth = token rgw crypt vault token file = /etc/ceph/vault.token rgw crypt vault addr = http://vault-server:8200 For security reasons, the token file must be readable by the Object Gateway only. Also, the Object Gateway should be given a Vault token with a restricted policy that allows it to fetch keyrings from a specific path only. Such a policy can be created in Vault using the command line utility as in the following examples:: vault policy write rgw-kv-policy -<``. Using the Transit engine ------------------------ Keys created with the Transit engine must be exportable in order to be used for server-side encryption with the Object Gateway. An exportable key can be created with the command line utility as follows:: vault write -f transit/keys/mybucketkey exportable=true The command above creates a keyring, which contains a key of type ``aes256-gcm96`` by default. To verify that the key was correctly created, use the following command:: vault read transit/export/encryption-key/mybucketkey/1 Sample output:: Key Value --- ----- keys map[1:-gbTI9lNpqv/V/2lDcmH2Nq1xKn6FPDWarCmFM2aNsQ=] name mybucketkey type aes256-gcm96 Note that in order to read the key created with the Transit engine, the full path must be provided including the key version. Configure the Ceph Object Gateway ================================= Edit the Ceph configuration file to enable Vault as a KMS backend for server-side encryption:: rgw crypt s3 kms backend = vault Choose the Vault authentication method, e.g.:: rgw crypt vault auth = token rgw crypt vault token file = /etc/ceph/vault.token rgw crypt vault addr = http://vault-server:8200 Or:: rgw crypt vault auth = agent rgw crypt vault addr = http://localhost:8100 Choose the secrets engine:: rgw crypt vault secret engine = kv Or:: rgw crypt vault secret engine = transit Optionally, set the Vault namespace where encryption keys will be fetched from:: rgw crypt vault namespace = tenant1 Finally, the URLs where the Gateway will retrieve encryption keys from Vault can be restricted by setting a path prefix. For instance, the Gateway can be restricted to fetch KV keys as follows:: rgw crypt vault prefix = /v1/secret/data Or, in the case of exportable transit keys:: rgw crypt vault prefix = /v1/transit/export/encryption-key In the example above, the Gateway would only fetch transit encryption keys under ``http://vault-server:8200/v1/transit/export/encryption-key``. Upload object ============= When uploading an object to the Gateway, provide the SSE key ID in the request. As an example, for the kv engine, using the AWS command-line client:: aws --endpoint=http://radosgw:8000 s3 cp plaintext.txt s3://mybucket/encrypted.txt --sse=aws:kms --sse-kms-key-id myproject/mybucketkey As an example, for the transit engine, using the AWS command-line client:: aws --endpoint=http://radosgw:8000 s3 cp plaintext.txt s3://mybucket/encrypted.txt --sse=aws:kms --sse-kms-key-id mybucketkey/1 The Object Gateway will fetch the key from Vault, encrypt the object and store it in the bucket. Any request to download the object will make the Gateway automatically retrieve the correspondent key from Vault and decrypt the object. Note that the secret will be fetched from Vault using a URL constructed by concatenating the base address (``rgw crypt vault addr``), the (optional) URL prefix (``rgw crypt vault prefix``), and finally the key ID. In the kv engine example above, the Gateway would fetch the secret from:: http://vaultserver:8200/v1/secret/data/myproject/mybucketkey In the transit engine example above, the Gateway would fetch the secret from:: http://vaultserver:8200/v1/transit/export/encryption-key/mybucketkey/1 .. _Server-Side Encryption: ../encryption .. _Vault: https://www.vaultproject.io/docs/ .. _Token authentication method: https://www.vaultproject.io/docs/auth/token.html .. _Vault agent: https://www.vaultproject.io/docs/agent/index.html .. _KV Secrets engine: https://www.vaultproject.io/docs/secrets/kv/ .. _Transit engine: https://www.vaultproject.io/docs/secrets/transit .. _namespaces: https://www.vaultproject.io/docs/enterprise/namespaces/index.html