Thales Luna HSM¶
HelixIAM works with Thales Luna HSMs through its built-in PKCS#11 backend. With a realm in High assurance:
- the realm's signing keys (ES256, RS256 and PS256) and its key-encryption key are generated inside your Luna partition and never leave it;
- every access token, ID token and SAML assertion of that realm is signed by the HSM;
- the HelixIAM database holds only a reference to each key.
This page covers what is specific to Luna. Key custody (HSM and KMS) explains the assurance profiles, the backend settings and the failure behaviour that apply to every backend.
Tested with Thales Luna Cloud HSM
Thales Luna Cloud HSM on Data Protection on Demand (DPoD), FIPS mode, Luna client 10.9.4. HelixIAM was run on Kubernetes with the Helm chart and with Docker Compose. The tests covered High assurance with ES256, RS256 and PS256, token verification against the realm's JWKS, normal and emergency rotation, restarts, and clean shutdown. A Luna Network HSM uses the same Luna client and PKCS#11 library. Run the checks in Check that it works on yours.
Requirements¶
- HelixIAM 1.1.0-rc.28 or later.
- A Luna partition: a Luna Cloud HSM service on DPoD, or a partition on a Luna Network HSM.
- An initialised partition and Crypto Officer. Initialise both with
lunacmfrom the Luna client. - The Luna client for Linux (64-bit). For a Luna Cloud HSM, it is the client zip you download for the
service. It contains:
- the PKCS#11 library
libs/64/libCryptoki2.so; - the plugin
plugins/libcloud.plugin; Chrystoki.confand the certificates.
- the PKCS#11 library
- The Crypto Officer PIN as a file, mounted read-only from a Secret. Never put the PIN in an environment variable.
- Network egress:
- For a Luna Cloud HSM: TCP 443 to
<region>.hsm.dpondemand.io(EU:eu.hsm.dpondemand.io) and toaccess.dpondemand.io. - For a Luna Network HSM: the port of your appliance.
- For a Luna Cloud HSM: TCP 443 to
The HelixIAM image already contains ca-certificates, which the Luna client needs for its TLS connections.
Treat the client configuration as a secret
Chrystoki.conf holds the service's client credentials. Keep it in a Kubernetes Secret, never in a ConfigMap,
an image or a Git repository. The same applies to the PIN.
Set up on Kubernetes¶
The server runs as uid 10001 with a read-only root file system. The Luna client needs four things inside the container:
| What | Where (example) | How |
|---|---|---|
Chrystoki.conf and the certificates |
/opt/luna/conf |
A Secret, read-only |
The library and the plugin (libs/, plugins/) |
/opt/luna/libs, /opt/luna/plugins |
A read-only volume |
| A writable lock directory | /opt/luna/lock |
An emptyDir |
| The Crypto Officer PIN | /var/run/helix/custody/luna-1/pin |
The chart's pinSecret |
The library and the plugin hold no credentials, but they are too large for a Kubernetes Secret (1 MiB). Put them on a read-only volume that you prepare once:
hostPathon each node: the example below uses this.- A PersistentVolumeClaim or CSI volume with the same two directories also works.
Mount the Luna client at run time
The Luna client is Thales software. Mount it as shown here rather than building it into an image that you push to a registry.
1. Point Chrystoki.conf at the mounts¶
The Luna client reads its configuration from the directory named in the environment variable
ChrystokiConfigurationPath. Every path in Chrystoki.conf must be absolute and match where you mount the files.
Edit a copy of the Chrystoki.conf from the client zip. With the mounts on this page, the entries that name a file or
directory are:
LibUNIX64 = /opt/luna/libs/64/libCryptoki2.so;
MutexFolder = /opt/luna/lock;
PluginModuleDir = /opt/luna/plugins;
SSLConfigFile = /opt/luna/conf/openssl.cnf;
PartitionCAPath = /opt/luna/conf/partition-ca-certificate.pem;
PartitionCertPath00 = /opt/luna/conf/partition-certificate.pem;
SSLClientSideVerifyFile = /opt/luna/conf/server-certificate.pem;
- Already correct: in the DPoD client zip, the first three entries already point at
/opt/luna/.... - Change these: the certificate entries and
SSLConfigFilepoint into the client directory. Change them to/opt/luna/conf/. - Leave unchanged: the credential entries.
2. Create the Secrets¶
# The edited copy of Chrystoki.conf, openssl.cnf and the certificates, from a directory only you can read
kubectl create secret generic luna-client-config \
--from-file=<conf-copy-dir>/Chrystoki.conf \
--from-file=<conf-copy-dir>/openssl.cnf \
--from-file=<conf-copy-dir>/partition-ca-certificate.pem \
--from-file=<conf-copy-dir>/partition-certificate.pem \
--from-file=<conf-copy-dir>/server-certificate.pem
# The Crypto Officer PIN, from a file (not on the command line)
kubectl create secret generic luna-co-pin --from-file=pin=<file-holding-the-pin>
3. Configure the backend in the Helm values¶
config:
extraEnv:
- name: ChrystokiConfigurationPath
value: /opt/luna/conf
custody:
backends:
- id: luna-1
type: pkcs11
library: /opt/luna/libs/64/libCryptoki2.so
tokenLabel: <partition-label>
pinSecret: {name: luna-co-pin, key: pin} # mounted at /var/run/helix/custody/luna-1/pin
connectTimeout: PT30S # see "Settings for a cloud HSM"
opTimeout: PT5S
generateTimeout: PT1M
sessions: 8
networkPolicy:
extraEgressPorts: # keep the ports you already list here
- port: 443
protocol: TCP
extraVolumes:
- name: luna-config
secret: {secretName: luna-client-config, defaultMode: 0440}
- name: luna-libs # the client's libs/ directory on the node
hostPath: {path: /var/lib/luna-client/libs, type: Directory}
- name: luna-plugins # the client's plugins/ directory on the node
hostPath: {path: /var/lib/luna-client/plugins, type: Directory}
- name: luna-lock
emptyDir: {}
extraVolumeMounts:
- {name: luna-config, mountPath: /opt/luna/conf, readOnly: true}
- {name: luna-libs, mountPath: /opt/luna/libs, readOnly: true}
- {name: luna-plugins, mountPath: /opt/luna/plugins, readOnly: true}
- {name: luna-lock, mountPath: /opt/luna/lock}
- With a PersistentVolumeClaim: use one volume
(
persistentVolumeClaim: {claimName: <luna-client-pvc>, readOnly: true}) and mount it twice, withsubPath: libsat/opt/luna/libsandsubPath: pluginsat/opt/luna/plugins. - With a Luna Network HSM: add the port of your appliance to
extraEgressPorts. - More about the chart values: see With the Helm chart.
4. Switch a realm to High assurance¶
In the console, go to Realm keys → Key custody → Change profile. Or use the API:
curl -s -b cookies.txt -X PUT -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"profile":"HIGH","backendId":"luna-1"}' \
"$HELIX_URL/admin/realms/$REALM/key-custody"
The answer is 202, with a list of the planned keys and when each one starts signing.
- What HelixIAM does: it creates the realm's key-encryption key in the partition, then a key per purpose. The new keys are published at once and start signing after the JWKS cache window. The details are in Moving a realm.
- Protected instead of High: use
"profile":"PROTECTED". Only the key-encryption key is then in the partition, and the signing keys sign in the server.
Set up without Kubernetes¶
Run the server container with:
- the client directory mounted read-only at
/opt/luna; - a writable lock directory, owned by uid 10001, at
/opt/luna/lock; ChrystokiConfigurationPath=/opt/luna;- this backend in a file loaded through
SPRING_CONFIG_ADDITIONAL_LOCATION. See Without the chart for how that works.
helix:
custody:
backends:
- id: luna-1
type: pkcs11
settings:
library: /opt/luna/libs/64/libCryptoki2.so
tokenLabel: <partition-label>
pinFile: /var/run/helix/custody/luna-1/pin
connectTimeout: PT30S
opTimeout: PT5S
generateTimeout: PT1M
Check that it works¶
Sign in as a master-realm administrator on the admin host (see Authenticating to the API), then run these checks:
- Backend health:
GET /admin/key-custody/backendslistsluna-1as healthy, with the algorithms the partition signs. A partition in FIPS mode signs RS256, PS256, ES256 and ES384. At start-up the server log showsPKCS#11 key custody backend 'luna-1' ready. - Realm keys:
GET /admin/realms/$REALM/key-custodyshows the realm's keys with custody onluna-1. - Tokens: a token from the realm verifies against
/realms/$REALM/oauth2/jwks. - Restart: after you restart one pod, the same
kidkeeps signing.
Scripted checks
The chart enables MFA by default, so the bootstrap admin signs in with a second factor. For scripts, set
secrets.bootstrapClientId and use that client's client_credentials token.
FIPS mode¶
Luna Cloud HSM partitions run in FIPS mode by default. HelixIAM detects this and adapts, so there is nothing to configure. Two things to know:
- No EdDSA. A partition in FIPS mode has no EdDSA, so HelixIAM does not offer it on this backend. Use ES256, RS256
or PS256. A request for EdDSA answers
400and changes nothing. - Mechanism restrictions belong in the partition policy. Luna does not accept per-key mechanism lists in FIPS mode. HelixIAM uses only each key's own mechanisms. To restrict mechanisms on the HSM side, use a Luna partition policy.
Settings for a cloud HSM¶
A cloud HSM is a network round trip away. The default timeouts suit an HSM in the same data centre. For a Luna Cloud HSM, use the values below, as in the example above:
| Setting | Default | For a Luna Cloud HSM | Why |
|---|---|---|---|
connectTimeout |
PT5S |
PT30S |
The first connection to the service can take 10–20 s. |
opTimeout |
PT2S |
PT5S |
The time allowed for one signature, including a network round trip. |
generateTimeout |
the larger of PT30S and opTimeout |
PT1M |
RSA key generation on a cloud HSM can take several seconds. At most PT5M. |
sessions |
8 | your expected concurrent signatures per pod | A pod signs at most this many tokens at once on this backend (1–256). |
Plan capacity:
- Sessions and replicas. Each signature is a network round trip to the HSM. For more tokens per second, raise
sessionsand the number of replicas, within the partition's session limit (sessions× replicas). - Objects. Each realm in High assurance holds about 13 objects in the partition: six key pairs and the
key-encryption key. Each rotation adds new keys until the retention job destroys the retired ones. If the partition
is full, a rotation is refused with
400 backendNoSpaceand the existing keys keep signing. Choose a partition size that fits your realms and rotations. - Load test. Run one against your own partition and network before you go live (see Sizing).
Rotation¶
Rotation works the same way as for every backend (see Day-to-day key work):
- Normal rotation: the new key is published first and starts signing after the cache window.
- Emergency rotation: the new key signs at once, and the old key is disabled in the partition.
# Emergency rotation of the realm's RSA keys (RS256 and PS256); add "algorithm":"ES256" for the EC keys
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"emergency": true}' \
"$HELIX_URL/admin/realms/$REALM/keys/rotate"
On a cloud HSM, an RSA rotation takes a few seconds, because the new keys are generated in the partition. After an emergency rotation, purge cached JWKS copies, as described in Emergency rotation and caches.
Retired keys are disabled in the partition, then destroyed by the retention job after custody.destroyAfter (default
P30D). custody.retentionCheckInterval sets how often the job runs (default PT1H).
Restart and shutdown¶
- Restart: the keys stay in the partition and the database keeps their references, so after a restart the same
kidsigns. - Shutdown: the server releases the Luna library and exits within about a second.
- HSM unreachable at start-up: the pod starts with the backend disconnected and connects as soon as the HSM
answers. Until then:
- High-assurance realms answer
503for what they must sign; - Standard realms keep working.
- High-assurance realms answer
See Failure behaviour.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
| Backend DOWN with "No HSM token carries the configured label" | The Luna client finds no partition. Check that: ChrystokiConfigurationPath names the directory with Chrystoki.conf; every path in Chrystoki.conf is absolute and matches the mounts; egress on 443 to the DPoD hosts is allowed; tokenLabel is the partition label. |
| "Two HSM tokens carry the configured label" | Two partitions have the same label. Give each its own label. |
| Backend DOWN for the first seconds after start-up | The first connection is slower than connectTimeout. Set connectTimeout: PT30S. |
| "The PIN file of the PKCS#11 backend cannot be read" or "is empty or missing" | The PIN Secret is not mounted, not readable by uid 10001, or empty. |
| "The PKCS#11 library of the backend does not exist" | library does not match where libs/64/libCryptoki2.so is mounted. |
400 backendNoSpace on a rotation or a switch to High assurance |
The partition is full. Free objects (lower custody.destroyAfter, or delete unused objects with lunacm) and retry. Existing keys keep signing. |
Occasional 503 on the token endpoint under load |
Signatures take longer than opTimeout, or there are more concurrent signatures than sessions. Set opTimeout: PT5S and size sessions. |
A request for EdDSA answers 400 |
Expected in FIPS mode. Use ES256. |
| Warning "the token refused CKA_ALLOWED_MECHANISMS" | Expected on Luna in FIPS mode. See FIPS mode. |
Objects labelled helix:<realm>:… that HelixIAM does not list |
Keys left on the partition by interrupted attempts. HelixIAM disables them but does not destroy keys it does not track. Delete them with lunacm, logged in as Crypto Officer. |