# 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)](key-custody.md) explains the assurance
profiles, the backend settings and the failure behaviour that apply to every backend.

!!! info "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](#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.

!!! warning "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.

!!! note "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

```bash
# 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

```yaml
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](key-custody.md#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:

```bash
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](key-custody.md#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](key-custody.md#without-the-chart) for how that works.

```yaml
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](../getting-started/api-authentication.md)), 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.

!!! tip "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](key-custody.md#sizing)).

## Rotation

Rotation works the same way as for every backend (see [Day-to-day key work](key-custody.md#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.

```bash
# 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](key-custody.md#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](key-custody.md#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](#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

- [Key custody (HSM and KMS)](key-custody.md)
- [Realm keys](realm-keys.md)
- [Install: key custody values](../getting-started/install.md#key-custody-hsm-and-kms)
- [API reference: key custody](../integration/api-reference.md#key-custody-hsm-kms)
