Crypto Tokens: HSMs & Keystores

Crypto Tokens provide access to the keys and cryptography operations.

The functions of a Crypto Token include:

Key storage and protection
Authenticated key access
Login/logout handling
Algorithm support

Overview

A Crypto Token can use:

HSMs (PKCS#11 using Keyfactor P11NG interface)
SoftHSM
REST-based HSMs (Fortanix, Azure, and so on)

Keystore files (PKCS#12, JKS) can be used for testing but are not recommended for production use.

A Crypto Token using a software keystore is the Keystore Crypto Token and one using a Hardware Security Module (HSM) is the PKCS#11 Crypto Token.

Crypto Token Architecture

The following diagram shows how the Crypto Token is used:

Using Crypto Tokens

A Worker can either host its own Crypto Token, or reference a Crypto Token configured on a separate Crypto Worker.

A Worker contains a Crypto Token by defining which implementation to use with the CRYPTOTOKEN_IMPLEMENTATION_CLASS property, adding any properties required by that implementation.

Each Signer is typically configured to reference a dedicated Crypto Worker that holds the Crypto Token.

Crypto Workers Hosting Crypto Tokens

The Crypto Worker is a Worker that performs no operations of its own. Its sole purpose is to host a Crypto Token that other Workers can reference.

Fully-qualified class name: org.signserver.server.signers.CryptoWorker.

Use the CRYPTOTOKEN_IMPLEMENTATION_CLASS property to define the Crypto Token implementation:

CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.server.cryptotokens.KeystoreCryptoToken

For setup information, see Set Up a Crypto Worker.

Using the Crypto Worker of Another Worker

A Worker can reference a Crypto Worker configured on a separate Worker by specifying the Crypto Worker name in a CRYPTOTOKEN property:

CRYPTOTOKEN=SoftCryptoToken

Key Aliases, Certificates, and PKCS#11 Objects

When using an HSM through PKCS#11, SignServer stores and references cryptographic material as a set of related objects on the token. Understanding how these objects are linked is useful when configuring Workers, importing certificates, and troubleshooting.

How a Key Alias Maps to the HSM

The key alias you set in SignServer (for example, in the DEFAULTKEY property) maps to the CKA_LABEL attribute on the PKCS#11 certificate object stored on the HSM. When SignServer needs to sign using that alias, it locates the corresponding private key by searching for a PKCS#11 private key object that shares the same CKA_ID value as the certificate object.

This CKA_LABEL to CKA_ID pairing is how SignServer reliably resolves the correct key material at signing time.

Placeholder Certificate Object

When a key pair is generated through SignServer, a self-signed placeholder certificate object is automatically created on the HSM alongside the key pair. This behavior is controlled by the GENERATE_CERTIFICATE_OBJECT=true property, available on the P11NG Crypto Token.

The placeholder establishes the CKA_LABEL association needed for key resolution, but it is not a valid signing certificate. A real certificate must be imported to replace it before signing operations can succeed.

Certificate Location: Token vs. Worker Configuration

A signing Worker needs to present a certificate alongside each signature. There are two places this certificate can come from:

From the HSM token: The certificate object stored on the HSM alongside the private key. This is the standard approach when using a Crypto Worker and an HSM. All signing Workers referencing the same Crypto Worker pick up the same certificate automatically. Certificate renewals take effect across all workers once the new certificate is imported to the token.
From the Worker configuration: The certificate can be explicitly set in the signing Worker properties. This overrides any certificate on the HSM for that Worker. This is useful when different Workers using the same key need to present different certificates, or when the HSM does not support certificate objects (for example, some cloud KMS providers).

Certificate Caching and Renewals

When CACHE_PRIVATEKEY (PKCS#11 Crypto Token) or USE_CACHE (P11NG Crypto Token) is enabled, key and certificate lookups from the HSM are cached in the Worker. If a certificate on the HSM is replaced, for example after renewal, the cached value remains in use until the Worker is reloaded. Always reload the Worker after importing a new certificate to the token.

Externally Generated Keys and `CKA_ID`

If keys are created outside SignServer, the CKA_ID attribute must be set on both the public and private key objects before SignServer can use them. Without a correct CKA_ID, SignServer cannot pair the private key with its certificate object and the Worker will not activate.

For HSM-specific instructions on setting CKA_ID, see P11NG Crypto Token.