Store HSM on Thales CipherTrust Manager

MinIO KMS supports using a symmetric key in Thales CipherTrust Manager, formerly Gemalto KeySecure, as the Hardware Security Module (HSM) that protects the Root Encryption Key (REK). MinIO KMS calls this backend hsm:thales:ciphertrust.

CipherTrust Manager holds the key material, so a user with access to a MinIO KMS pod has no immediate access to the plaintext value of that key. You can enable an external HSM for MinIO KMS at any time after completing the initial installation.

This deployment does not give CipherTrust-only key isolation

The minkms Helm chart requires a static HSM key in addition to CipherTrust Manager, and the Operator injects that key into every pod as the MINIO_KMS_HSM_KEY environment variable. A user with pod access, or with read access to the HSM Secret, can therefore read a key that unseals the deployment without ever reaching CipherTrust Manager.

Moving the key material out of the cluster is the usual reason to adopt an external HSM, and this deployment does not achieve that on its own. A CipherTrust-only deployment requires chart support for omitting the static key, which the chart does not have today. Until then, protect the static key and its Secret as carefully as the CipherTrust key, or use the Linux procedure, where the local HSM can be removed.

The CipherTrust key performs two jobs for the cluster:

It seals and unseals the Root Encryption Key. On startup, each pod asks CipherTrust Manager to unwrap the REK, and only then can it decrypt its enclaves and the keys they hold.
It derives the internode TLS identity. Each pod derives its private key from the same CipherTrust key, so pods that share the key derive matching identities and trust each other.

Because the second job depends on the key material, every pod in the cluster must use the same endpoint, domain, and key name. A single server configuration Secret, shared by the whole StatefulSet, satisfies this requirement.

Prerequisites

This procedure assumes the following installations:

The MinIO KMS deployment on Kubernetes
A CipherTrust Manager deployment reachable from the MinIO KMS namespace

You also need permission to create a user and a key in the CipherTrust Manager domain you intend to use, and the CA certificate that issued the CipherTrust Manager TLS certificate unless a public CA issued it.

Refer to the Thales CipherTrust Manager administrator guide for guidance on installing CipherTrust Manager and on creating users, keys, and key policies.

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

Losing the CipherTrust key causes permanent data loss

The CipherTrust key protects the entire MinIO KMS deployment. If the key is deleted or destroyed, no pod can unseal the REK through CipherTrust Manager. Unless another HSM entry or a usable backup can still unseal the REK, every pod and every backup becomes permanently unreadable, along with all data encrypted under the keys MinIO KMS manages. Back up the key according to your Thales operational procedures, and consider configuring multiple HSMs to mitigate the risk.

Procedure

Select the CipherTrust Manager domain

Sign in to the CipherTrust Manager console. If your deployment is split into domains, switch to the domain that holds the MinIO KMS user and key, and note the domain name for the domain field in the configuration. Leave that field empty to use the root domain.
Create a user for MinIO KMS

Create a local user, for example minkms, or reuse an existing one. Sign in as that user once, because CipherTrust Manager requires a password change on first login and MinIO KMS cannot complete that exchange. Record the final password.

Give MinIO KMS its own user rather than sharing an operator account. You can then rotate its password, audit its requests, and revoke its access on its own.
Create the encryption key

Create a symmetric key for MinIO KMS. MinIO recommends an AES 256 key.

The key must allow the Encrypt and Decrypt operations, and the MinIO KMS user must be permitted to use it, either as the key owner or through a key policy. Grant the user those two operations on this key only, because MinIO KMS needs no other permission in CipherTrust Manager.

Note the key name, not its UUID. It goes into the key field of the configuration.
Write the MinIO KMS server configuration with the hsm.thales.ciphertrust_manager section

The minkms Helm chart does not generate this section, so write the server configuration yourself:
```
version: v1

# Other configuration settings above this line

hsm:
  thales:
    ciphertrust_manager:
      server:   https://ciphertrust.example.net # CipherTrust Manager endpoint
      key:      minkms-sealing-key              # Name of the symmetric key created above
      username: minkms                          # User account for accessing CipherTrust Manager
      password: "Nh[a7*J)oRbXR$wi74"            # Password for the user account
      domain:   ""                              # Optional. Empty selects the root domain
```
Do not add a tls: section. The Operator replaces it with its own TLS settings when it merges your configuration, so anything you write there is discarded.

MinIO KMS verifies the CipherTrust Manager TLS certificate and requires TLS 1.2 or later. If a private certificate authority (CA) issued that certificate, put the CA in a Secret and reference it under minkms.certificates.externalCaCertSecret in the chart values. The Operator copies that CA to every pod and points the generated TLS configuration at it, so MinIO KMS trusts CipherTrust Manager. An untrusted certificate produces a login failure at startup.

MinIO KMS sends every request over TLS unless the server value starts with http://, which sends the username and password in the clear. Use plain HTTP only in a throwaway lab.
Store the configuration in a Secret

Create a Secret in the MinIO KMS namespace with a server-config.yaml key holding the configuration from the previous step:
```
kubectl create secret generic minkms-server-config \
  --namespace minkms \
  --from-file=server-config.yaml=server-config.yaml
```
The key must be named server-config.yaml, because the Operator reads that key and no other. The Secret name must be lowercase and use hyphens rather than underscores, because Kubernetes object names follow RFC 1123.

The Secret holds the CipherTrust Manager password. Restrict access to it with RBAC, and keep the local copy of the configuration file out of version control.
Point the chart at that Secret

Open the chart values file in your preferred text editor. Set minkms.configuration.existingSecret to true and set minkms.configuration.name to the name of the Secret you created.

Leave minkms.hsm.key in place. The chart requires either that static HSM key or an external HSM it can generate configuration for, which at present means another MinIO KMS cluster or HashiCorp Vault. The chart does not generate Thales CipherTrust Manager configuration, so removing the key makes helm upgrade fail with At least one HSM must be defined.

Keeping the key leaves the static HSM active alongside CipherTrust Manager. The chart still creates the HSM Secret and sets hsmSecret on the MinKMS object, so the Operator injects MINIO_KMS_HSM_KEY into every pod, and the result is a dual-HSM deployment. The chart supports this combination for redundancy: either HSM can unseal the REK.

Treat the static key as a second copy of equal power, not as a leftover. Back it up, and restrict access to its Secret as you would for the CipherTrust key. A CipherTrust-only deployment through this chart requires a change to the chart’s HSM validation, so use the Linux procedure as the reference for what a single-backend configuration looks like.
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
```
Verify that the pods use CipherTrust Manager

Each pod prints its HSM type on startup. Check every pod, not just the first one, because a pod that still mounts an older configuration keeps using its previous HSM until it restarts. The value hsm:thales:ciphertrust confirms that the pod sealed its state with CipherTrust Manager:
```
kubectl logs -n minkms -l minkms.min.io/MinKMS=minkms -c key-manager --prefix --tail=-1 | grep HSM
```
```
[pod/minkms-0/key-manager] HSM            hsm:thales:ciphertrust
[pod/minkms-1/key-manager] HSM            hsm:thales:ciphertrust
```
Replace minkms in the selector with the name of the MinKMS object if you changed minkms.name. The --tail=-1 flag is required, because kubectl logs returns only the last 10 lines per pod when given a label selector, which usually excludes the startup message. Expect one line per pod, and compare the count against the same selector:
```
kubectl get pods -n minkms -l minkms.min.io/MinKMS=minkms
```
These lines confirm only that each pod loaded the CipherTrust configuration. They do not mean CipherTrust Manager holds a sealed copy of the REK.

Use the minkms ls-hsm command to list the HSMs the cluster knows about and which of them hold a sealed copy of the REK. If CipherTrust Manager appears as configured but without an entry, for example because you added it to an existing cluster, create the entry with minkms add-hsm hsm:thales:ciphertrust. That command requires SysAdmin privileges, and the backend must be configured on all pods first.

Treat the deployment as relying on the static HSM key until minkms ls-hsm shows a sealed REK entry for hsm:thales:ciphertrust.

Troubleshooting

The server logs the underlying CipherTrust Manager error message. Read the log of the pod that fails to start before you change the configuration.

Symptom	Likely cause	What to do
`thales: failed to login`	Wrong credentials, wrong domain, or an unchanged initial password.	Sign in to the console as the MinIO KMS user to confirm the password is final, and check the `domain` field.
A TLS or certificate error at startup	MinIO KMS does not trust the CipherTrust Manager CA, or the endpoint host name does not match the certificate.	Put the CA in a Secret, reference it under `minkms.certificates.externalCaCertSecret`, and use the host name from the certificate in `server`.
`thales: missing CipherTrust Manager key name`	The `key` field is empty or missing.	Set `key` to the name of the symmetric key.
`failed to encrypt plaintext` or `failed to decrypt ciphertext`	The user lacks `Encrypt` or `Decrypt` on the key, or the key is deactivated.	Check the key policy and the key state in the console.
Pods start but do not form a cluster	Pods use different server configurations, so they derive different identities.	Confirm that every pod mounts the same `server-config.yaml` Secret.