Thales Luna HSM

Configure Thales Luna HSM for supported FortifiedID TLS and signing key stores.

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.

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.
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.
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.
Register the Luna JCA provider. Add com.safenetinc.luna.provider.LunaProvider to the JVM security properties before the application starts. The Prerequisites section shows the required JVM options.
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.
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.
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.

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.

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:

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

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

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

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.

{
  "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:

{
  "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

{
  "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

Verify the Luna Client can connect to the intended partition and list the configured alias.
Start the application with the Luna runtime dependencies and sanitised configuration.
For server TLS, establish a TLS handshake and verify the served certificate.
For mTLS, call a server that requires the configured client certificate.
Confirm in the customer's Luna audit or observability tooling that the HSM performed the signing operation.
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.