# Thales Luna HSM

Documentation owner: unversioned-area `integrations`; documentation version: unversioned.
Source: `content/integrations/pki/thales-luna-hsm.md` at commit `eaf7a020437971baeee95e87eaf963636040ac71`.

This guide describes the common runtime requirements and configuration form for using a Thales Luna HSM with supported FortifiedID TLS and signing integrations. It applies where the product uses Foss Mono's HSM-aware keystore path; a private key remains in the HSM and is not exported as a PKCS#12 file.

## Quick start

Use this checklist in order. It currently applies to incoming HTTPS/TLS and outgoing HTTP mTLS; product-specific signing support must be added by the consuming product before it can use a Luna key.

1. **Use Foss Mono `2026.116` or later.** This is the first Foss Mono release that contains the Luna keystore, TLS, HTTP mTLS, and generic private-key support.
2. **Prepare the Luna partition.** The customer needs a reachable partition (or HA group), a Crypto User account, a private key with its certificate chain, and the key's alias. Prefer the partition's stable token label over its numeric slot number.
3. **Install the Luna runtime in the application environment.** Use the same Luna Client, `LunaProvider.jar`, and native libraries that work with the customer's validated Luna connection test. Add `LunaProvider.jar` to the application classpath and make the native libraries available to the JVM.
4. **Register the Luna JCA provider.** Add `com.safenetinc.luna.provider.LunaProvider` to the JVM security properties before the application starts. The [Prerequisites](#prerequisites) section shows the required JVM options.
5. **Configure the Luna identity keystore.** Set `type` to `Luna`, provide exactly one of `token_label` or `slot`, and store the Crypto User secret in the product's normal secret mechanism. Then configure the relevant key alias in the TLS or HTTP client integration below.
6. **Keep the truststore outside Luna.** Continue to use PKCS#12 or JKS for trusted certificates. Do not add `key_password` for a Luna key; Luna authenticates the keystore session with the partition secret.
7. **Test with the customer’s HSM.** Start the service, perform a real TLS or mTLS handshake, verify the certificate, and confirm through Luna audit/observability that the HSM carried out the signing operation.

:::caution
Foss Mono's automated tests do not connect to a physical HSM. A customer test in the target Luna environment is required before a deployment is accepted.
:::

## Supported use

The current implementation supports Luna as an identity keystore for:

- incoming HTTPS/TLS listeners
- outbound HTTP mutual TLS (mTLS) clients

The exact configuration property depends on the consumer. A TLS listener uses a `keystore` and `key_alias`; the HTTP Client module uses `ssl_keystore` and `ssl_key_alias`.

## Product signing

Foss Mono also provides a generic private-key retrieval path for products that sign data, such as an eID service signing with an EC key. The same `type: "Luna"` keystore object and key alias are used; Foss Mono preserves an entry password for PKCS#12/JKS while Luna uses the authenticated HSM session and does not use a separate key password.

This is a Foss Mono capability, not a standalone application configuration. A product must use the configurable keystore path before it can use a Luna signing key. The first eID signing integration must still be tested by the customer with the provisioned Luna EC key before it is considered supported.

:::caution
Do not add a `key_password` for a Luna key. The Luna partition secret authenticates the keystore session; an individual key password is neither required nor used.
:::

:::caution
Luna is not supported as a TLS truststore in the current implementation. Configure a normal PKCS#12 or JKS truststore for trusted client or server certificates.
:::

## Prerequisites

- A provisioned Luna partition with a Crypto User account, a private key, certificate chain, and known alias.
- Thales Luna Client installed in the application runtime environment and configured to reach the HSM or HA group.
- `LunaProvider.jar` available on the application classpath.
- Luna Client native libraries available to the JVM, for example through the operating-system library path or `java.library.path`.
- The Luna JCA provider registered before the application opens a `Luna` keystore.

The provider can be registered through the JVM security configuration. The exact provider index is environment-specific; retain the JVM's existing providers and add the Luna provider, for example:

```properties
security.provider.13=com.safenetinc.luna.provider.LunaProvider
```

Start the application with a supplemental security-properties file when appropriate:

```text
-Djava.security.properties=/path/to/luna.security
```

:::note
Use the same Luna Client, `LunaProvider.jar`, and native-library combination that works with the customer's validated Luna connection test.
:::

## Keystore configuration

Use `type: "Luna"` and identify the partition by `token_label`. A numeric `slot` is supported for migration or diagnostics, but token labels are preferred because slot numbers can change.

```json
{
  "type": "Luna",
  "token_label": "fortifiedid-tls",
  "user_type": "CKU_CRYPTO_USER",
  "password": "${secrets.luna_cu_password}"
}
```

| Property | Description |
| --- | --- |
| `type` | Must be `Luna`. |
| `token_label` | Label of the Luna token or partition. Use exactly one of `token_label` and `slot`. |
| `slot` | Non-negative Luna slot number. Use only when a stable token label is not available. |
| `user_type` | Luna user role. Defaults to `CKU_CRYPTO_USER`; `CKU_CRYPTO_OFFICER` is also supported. |
| `password` | Luna partition authentication secret. Store it in the product's established secret mechanism and never log it. |

Luna does not use a separate password for each private-key entry. Configure the consuming integration's key alias, but do not require or invent a `key_password` for Luna.

## Configuration

Use the Luna keystore object as the identity keystore of the supported TLS consumer. The following examples show the complete Luna-specific part of each configuration; retain all other existing listener or client settings.

### Incoming HTTPS/TLS listener

For a dynamically configured HTTPS listener, put the Luna object in `ssl.keystore` and configure the HSM key alias separately:

```json
{
  "ssl": {
    "keystore": {
      "type": "Luna",
      "token_label": "fortifiedid-tls",
      "user_type": "CKU_CRYPTO_USER",
      "password": "${secrets.luna_cu_password}"
    },
    "key_alias": "https-server",
    "hsm_event_loop_pool_size": 1
  }
}
```

`ssl.hsm_event_loop_pool_size` must be at least `1`; the default is `1`. Luna listeners use a dedicated Vert.x instance so a synchronous HSM operation during a TLS handshake does not block ordinary listeners.

### Outgoing HTTP mTLS

```json
{
  "ssl_keystore": {
    "type": "Luna",
    "token_label": "fortifiedid-client-tls",
    "user_type": "CKU_CRYPTO_USER",
    "password": "${secrets.luna_cu_password}"
  },
  "ssl_key_alias": "outbound-mtls-client",
  "ssl_hsm_event_loop_pool_size": 1
}
```

`ssl_hsm_event_loop_pool_size` must be at least `1`; the default is `1`. Luna-backed HTTP clients use a dedicated Vert.x instance so synchronous HSM operations do not block ordinary HTTP client event loops.

### Truststores

Keep `ssl.truststore` and `ssl_truststore` as ordinary PKCS#12 or JKS stores. Luna is supported only for the private identity key in this release, not for a truststore.

## Test the configuration

1. Verify the Luna Client can connect to the intended partition and list the configured alias.
2. Start the application with the Luna runtime dependencies and sanitised configuration.
3. For server TLS, establish a TLS handshake and verify the served certificate.
4. For mTLS, call a server that requires the configured client certificate.
5. Confirm in the customer's Luna audit or observability tooling that the HSM performed the signing operation.
6. Restart the application and repeat the handshake. Test HA/failover according to the customer's Luna operating procedure when applicable.

## Limitations and troubleshooting

- A product path that loads a PKCS#12 file directly does not automatically support Luna. It must first be adapted to use Foss Mono's configurable keystore path.
- Luna support has provider-free automated tests, but all real HSM handshakes and signing operations must be accepted in a provisioned customer environment.
- A missing provider produces guidance to install Luna Client, add `LunaProvider.jar`, and register the provider. A missing native runtime points to the Luna Client and `java.library.path`.
- Do not put partition passwords, token PINs, complete HSM configuration, or unsanitised stack traces in logs or support tickets.

## Related pages

- [Extract alias from keystore](/integrations/pki/extract-alias-from-keystore/)
- [HTTP Client](/modules/http-client/)