Store HSM on MinIO KMS

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

K e y D a t a b a s e R D e e a c d r y e p n t c r D y B p t w e i d t h R o R o o t o t K e K y e y M i n I O K M S P D l e a c i r n y t p e t x t u s R i o n o g t H K S e M y E x t e r n a l H S M M i n I O K M S

The independent MinIO KMS 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.

Prerequisites

  • The local or cluster MinIO KMS deployment for supporting AIStor Object Store Server Side Encryption
  • The external MinIO KMS deployment for storing the HSM.
  • MinKMS Operator chart 1.1.2 or later
  • MinKMS chart 2.0.2 or later

See the installation instructions for further guidance on deploying MinIO KMS. For existing installations, see the upgrade instructions.

Procedure

  1. Create an enclave and identity for cluster MinIO KMS

    The cluster MinIO KMS requires an enclave and identity for storing and retrieving the HSM key on the external MinIO KMS.

    Use the following commands to generate the necessary resources. Change minkms to reflect the name or label you want to associate with the cluster MinIO KMS. Modify the example values to reflect the hostnames, API keys, and resource names of your deployment and infrastructure.

    export MINIO_KMS_SERVER=https://hsm-cluster.example.net:7373

minkms add-enclave -k -a k1:`root` or superadmin_API_KEY minkms

minkms add-identity -k -a k1:`root` or superadmin_API_KEY --enclave minkms --admin

    Previous versions of MinIO KMS (prior to RELEASE.2025-11-12T19-14-51Z) require the MINIO_LICENSE environment variable to be set before running minkms commands.

    For license configuration instructions for previous versions, see the Legacy License Installation Guide.

    The command returns the API key and identity for use with the cluster MinIO KMS. Copy the k1: prefixed value for use with the HSM storage configuration.

  2. Create an encryption key for use with seal/unseal operations

    Use the minkms add-key command to create a new encryption key for use by the cluster MinIO KMS:

    minkms add-key --enclave minkms minkms-hsm

    You must specify the key name in the next step.

  3. Modify the values file for the cluster MinIO KMS

    Open the chart values file in your preferred text editor and add the minkms.configuration.hsm.minio.minkms section:

    # minkms-values.yaml

# Other configuration settings above this line
minkms:
   configuration:
      hsm:
         minio:
            minkms:
               server:
               - kms0.hsm-cluster.example.net:7373
               - kms1.hsm-cluster.example.net:7373
               - kms2.hsm-cluster.example.net:7373
               enclave: minkms
               key: minkms-hsm
               auth:
                 key: k1:`root` or superadmin_API_KEY

  4. (Optional) Disable the local HSM

    You can 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.

    To disable the local HSM, comment out or remove the minkms.configuration.hsm.key value from the values.yaml file.

  5. Update the chart with the new values.yaml:

    Use the helm upgrade command to upgrade the chart with the new values.yaml:

    helm upgrade minkms minio/minkms \
  -n minkms \
  -f minkms-values.yaml