Skip to content

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 lunacm from 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.conf and the certificates.
  • 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 to access.dpondemand.io.
    • For a Luna Network HSM: the port of your appliance.

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:

  • hostPath on 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 SSLConfigFile point 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, with subPath: libs at /opt/luna/libs and subPath: plugins at /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/backends lists luna-1 as healthy, with the algorithms the partition signs. A partition in FIPS mode signs RS256, PS256, ES256 and ES384. At start-up the server log shows PKCS#11 key custody backend 'luna-1' ready.
  • Realm keys: GET /admin/realms/$REALM/key-custody shows the realm's keys with custody on luna-1.
  • Tokens: a token from the realm verifies against /realms/$REALM/oauth2/jwks.
  • Restart: after you restart one pod, the same kid keeps 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 400 and 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 sessions and 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 backendNoSpace and 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 kid signs.
  • 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 503 for what they must sign;
    • Standard realms keep working.

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.

See also