Store HSM on Hashicorp Vault

MinIO KMS supports using Hashicorp Vault for storing the Hardware Security Module (HSM) key associated with a Root Encryption Key (REK).

The Vault instance stores the HSM such that a user with access to the cluster MinIO KMS has no immediate access to the plaintext key value. You can enable the external HSM MinIO KMS at any time after completing the initial installation.

Configuring an external KMS for HSM storage can help meet compliance requirements around keeping root or master keys on the same system as the encryption database. The total security of the system relies on protections applied to the final key in any such KMS chain. Ultimately basic security measures such as root access protection and systems of least privilege carry the same weight and importance across all encryption related services.

This procedure assumes two MinIO KMS installations:

• The local or cluster MinIO KMS deployment
• The Hashicorp Vault deployment acting as HSM.

The Hashicorp Vault instance must provide support for the transit engine to support external HSM storage. The transit configuration must allow the following set of permissions:

path "transit/encrypt/minkms-sealing-key" {
   capabilities = [ "update" ]
}
path "transit/decrypt/minkms-sealing-key" {
   capabilities = [ "update" ]
}
path "transit/hmac/minkms-sealing-key" {
   capabilities = [ "update" ]
}

Refer to the Vault documentation for guidance on setup and configuration.

See the installation instructions for further guidance on deploying MinIO KMS.

1. Create the necessary tokens for authenticating to Vault

   MinIO KMS supports either the approle or the kubernetes authentication method.

   Prepare the following for this procedure:

   approle

   • A role_id
   • The corresponding secret_id

   The following optional value may be required depending on your configuration:

   • A namespace

   kubernetes

   • The service account role
   • The name or path to a service account JWT

   The following optional values may be required depending on your configuration:

   • The transit engine namespace
   • The auth mount path

2. Modify the configuration file for the cluster MinIO KMS

   Open the configuration file in your preferred text editor and add the hsm.hashicorp.vault section:

   version: v1
   
   # Other configuration settings above this line
   
   hsm:
     vault:
       server: https://vault.example.net:8200
       approle:
         id: UUID # App Role ID
         secret: UUID # App Role Secret
         namespace: ns-1 # Optional namespace for the approle
         path: approle # Optional mount point for the approle
       transit:
         key: aistor-key-manager-hsm
         namespace: ns-1 # Optional namespace for the transit engine
         path: transit # Optional mount point for the transit engine
   

   Make the same changes to all MinIO KMS nodes in the cluster deployment. You can then restart the nodes using systemctl restart minkms.

3. (Optional) Disable the local HSM

   You disable the local HSM used to initialize the cluster MinIO KMS after configuring the external HSM. This prevents using that HSM or its associated Root Encryption Key (REK) for accessing the encryption key database.

   Open the MinIO KMS environment file at /etc/default/minkms in your preferred browser. Remove the MINIO_KMS_HSM_KEY line on all nodes.

4. Restart the MinIO KMS process

   You can then restart all nodes in the deployment using systemctl restart minkms. Monitor the system logs using journalctl -uf minkms to ensure successful startup and resumption of internode and client API operations.