PKCS#11 HSMs

MinIO KMS supports using any PKCS#11-compatible Hardware Security Module (HSM) to seal and unseal the encryption key database. This includes physical devices such as a Thales Luna, Entrust nShield, or Utimaco HSM, a smartcard or USB token, and software emulators such as SoftHSM2 for evaluation.

About HSMs and PKCS#11

An HSM is a dedicated, tamper-resistant component that safeguards cryptographic keys and performs cryptographic operations on behalf of an application. The defining property of an HSM is that keys never leave the device: the application asks the HSM to encrypt or decrypt data with a key, but it can never read the key material itself.

MinIO KMS uses an HSM as its unseal mechanism. Each MinIO KMS node stores its encryption key database on disk in encrypted form, protected by a Root Encryption Key (REK). The REK itself is stored encrypted, and only the HSM can decrypt it. On startup, a node asks the HSM to decrypt the REK; without access to the HSM, the node cannot unseal its database. This breaks the otherwise infinite chain of keys protecting keys: the HSM protects the last key in the chain.

PKCS#11 is a standardized C API for talking to cryptographic devices. Unlike the network-attached providers such as Hashicorp Vault or Entrust KeyControl, a PKCS#11 HSM is not accessed over a network API. Instead, the HSM vendor ships a shared library — the PKCS#11 module, for example libCryptoki2_64.so — that implements the API. The application loads this module into its own process and calls its functions, and the module acts as a driver that communicates with the actual device, whether that is a PCIe card, a network-attached appliance, a USB token, or files on disk in the case of SoftHSM2.

The PKCS#11 API models the hardware as slots and tokens: a slot is a connector, and a token is the device — or a partition of a device — plugged into it. An application selects a token by its label or slot ID, logs in as a user with a PIN, and then references keys stored on the token by attributes such as their label.

Prerequisites

This procedure assumes the following:

A local or cluster MinIO KMS deployment
A PKCS#11-compatible HSM reachable from every MinIO KMS node, along with its PKCS#11 module (shared library) installed on each node
An initialized token on the HSM containing an AES key (AES-256 recommended) that permits the encrypt and decrypt operations

All MinIO KMS nodes in a cluster must have access to the same AES key, because they derive their shared internode API key from it. For a physical device, use a network-attached HSM or your vendor’s token-replication mechanism so that each node reaches the same key.

Refer to your HSM vendor’s documentation for the path of the PKCS#11 module and for instructions on initializing a token and generating an AES key.

Losing the token key causes permanent data loss

The AES key on the token protects the entire MinIO KMS on-disk state. If the token or the key is lost — for example, due to a hardware failure — the MinIO KMS state, including any backups, becomes permanently unreadable. Because MinIO KMS stores the master keys used to encrypt large amounts of data, this can cause catastrophic data loss. Follow your vendor’s guidance on backing up the token or replicating it across devices, and consider configuring multiple HSMs to mitigate the risk.

Procedure

Initialize a token and generate an AES key

Refer to your HSM vendor’s documentation for the exact steps. The following example uses SoftHSM2 and the generic pkcs11-tool from OpenSC to create a token named minkms with an AES-256 key labeled minkms-root:
```
softhsm2-util --init-token --free --label minkms --pin 1234 --so-pin 12345678
```
```
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --token-label minkms \
    --login --pin 1234 --keygen --key-type AES:32 --label minkms-root
```
Note the module path, the token label (or slot ID), the user PIN, and the key label for the next step.

Modify the configuration file for the MinIO KMS cluster

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

version: v1

# Other configuration settings above this line

hsm:
  pkcs11:
    softhsm:                                  # Config name - becomes part of the HSM name 'hsm:pkcs11:softhsm'
      module: /usr/lib/softhsm/libsofthsm2.so # Path of the PKCS#11 module (shared library)
      token: minkms                           # Label of the token containing the key
      # slot: 549790586                       # Alternatively, select the token by its slot ID
      pin: "1234"                             # CKU_USER PIN used to log in to the token
      key: minkms-root                        # Label of the AES key on the token

token vs slot

Set exactly one of token and slot. MinIO KMS rejects the configuration if both or neither are specified.

The config name (softhsm in this example) becomes part of the HSM name, hsm:pkcs11:softhsm. Renaming it changes the HSM name and orphans previously sealed data, so the node can no longer find its sealed Root Encryption Key entry.

Make the same changes to all MinIO KMS nodes in the cluster deployment.

(Optional) Disable the local HSM

You can disable the local HSM used to initialize the cluster MinIO KMS after configuring the PKCS#11 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 text editor. Remove the MINIO_KMS_HSM_KEY line on all nodes.
Restart the MinIO KMS process

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.

On startup, each node prints its HSM type. The value hsm:pkcs11:softhsm confirms that the node uses the PKCS#11 token as its HSM:
```
HSM            hsm:pkcs11:softhsm
```