Configure an External HSM | Keyfactor Docs

Using an external HSM, you can bring your own key (BYOK) to Signum. BYOK allows you to generate and manage encryption keys on your own infrastructure and make them available to Signum through SignServer, which acts as the cryptographic backend. This architecture allows for shared keys between both Signum and SignServer.

By default, Signum uses a Keyfactor-managed HSM that is configured and ready without any additional setup. The following steps only apply if you want to use your own external network HSM integrated with a REST API.

Signum only works with HSMs validated against Federal Information Processing Standards (FIPS). Software keystores (.p12) are not supported.

Overview

The cryptographic operations performed during signing in Signum are executed entirely within the HSM. The available key algorithms and key sizes for any given deployment are therefore dependent on the capabilities of the underlying HSM.

When an external HSM is configured, SignServer replaces Signum's direct HSM connection. The Signum Agent forwards signing requests to SignServer, which performs the cryptographic operations using the keys stored in your external HSM.

For a conceptual overview of this architecture, see Signum Architecture & Concepts.

Supported HSMs

The following external HSMs are supported:

Fortanix Data Security Manager (DSM)
Azure Key Vault

Prerequisites

SignServer Admin permissions
An external network HSM provisioned and accessible from your Signum environment
Access to the SignServer Admin Web (available from Portal Dashboard)

Configure a SignServer Crypto Token

SignServer Crypto Workers serve as a link between the external network HSM and Signum. The SignServer Crypto Worker holds a Crypto Token, providing the functionality for advanced configuration and signing operations. A managed Crypto Worker in SignServer is a Crypto Token in Signum.

The functions of a Crypto Token include:

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

Keyfactor provides pre-configured “managed” Crypto Tokens, designed to work out-of-the-box with Signum and SignServer.

To set up your own Crypto Worker to hold a HSM Crypto Token, use the SignServer Admin Web or the REST API.

Ensure the Crypto Worker is configured with the property MANAGED_VISIBLE=true to be visible in Signum.

The full reference for SignServer is found in the SignServer Documentation.

Crypto Worker Configuration Properties

In addition to the properties pre-configured in the managed Crypto Worker, the following properties can be set:

Property	Value	Description
`NAME`	`CryptoTokenAzureKeyVault`	Provide a unique name to reference this Crypto Worker.
`MANAGED_VISIBLE`	`true`	(Required) Set to `true` to make the Crypto Worker visible in Signum.
`CLIENTSIDEHASHING`	`true`	If the Crypto Worker should use client-side hashing (the request data to the signer is implied to be the pre-computed digest). Requires the `ACCEPTED_HASH_DIGEST_ALGORITHMS` property to be set.
`ALLOW_CLIENTSIDEHASHING_OVERRIDE`	`true`	If the Crypto Worker should allow overriding whether the request is using a client-side digest or not.
`ACCEPTED_HASH_DIGEST_ALGORITHMS`	`SHA-256,SHA-384,SHA-512`	Accepted digest hash algorithms used when the request is using a client-side hash. Required if either `CLIENTSIDEHASHING` or `ALLOW_CLIENTSIDEHASHING_OVERRIDE` is set to `true`.
`KEY_VAULT_NAME`	`kv-{app}-{env}-{region}`	(Required) Name of the Vault instance to use.
`KEY_VAULT_CLIENT_ID`	`c7dd251f-811f-4ba2-a905-acd4d3f8f08b`	(Required) The Application (client) ID provided when you register your service principal or app in Microsoft Entra ID to grant it access rights to the vault
`KEY_VAULT_TYPE`	`standard` or `premium`	The `standard` tier uses software-protected keys (FIPS 140 Level 1), while the `premium` tier adds Hardware Security Module (HSM) protected keys (FIPS 140 Level 3) for high-assurance compliance.
`PIN`	`test123`	Optional password (client credentials) for the key vault. When the `PIN` (HSM) property is set in the configuration, the Crypto Token is auto-activated and no manual activation is needed.
`DEFAULTKEY`	`testkey0`	Configure property to test activation using the default key. If `DEFAULTKEY` is not configured, the activation is tested by a test connection to the Azure Key Vault instance.

Using Admin Web

Access the SignServer Admin Web from the Portal Dashboard.
On the Workers page, click Add… and select From Template.
Select the relevant managed Crypto Worker and click Next.
In the configuration text area, adjust the Crypto Worker properties for your HSM.
Click Apply.
Select the new Crypto Worker in the Workers list and click the Status Summary tab to check for any errors.
Enter the slot/partition password if required and click Activate. The Crypto Token must be activated before keys can be generated on it.

For a full configuration guide, see Set Up a Crypto Worker Using the Admin Web in the SignServer documentation.

Using REST API

The pre-configured Crypto Token templates can be found in the SignServer repository under files/doc/sample-configs/ with managed in the name.

Send a POST request to the /workers endpoint with the Crypto Worker properties in the request body:
```
POST /signserver/rest-managed/v1/workers
```

Example request body

JSON

{
  "properties": {
    "TYPE": "PROCESSABLE",
    "IMPLEMENTATION_CLASS": "org.signserver.module.signumsigner.SignumSigner",
    "CRYPTOTOKEN_IMPLEMENTATION_CLASS": "org.signserver.server.cryptotokens.AzureKeyVaultCryptoToken",
    "NAME": "CryptoTokenAzureKeyVault",
    "AUTHTYPE": "org.signserver.server.managed.ManagedAuthorizer",
    "ACCEPTED_HASH_DIGEST_ALGORITHMS": "SHA-256,SHA-384,SHA-512",
    "MANAGED_VISIBLE": "true",
    "KEY_VAULT_TYPE": "standard",
    "KEY_VAULT_NAME": "<replace-with-your-vault-name>",
    "KEY_VAULT_CLIENT_ID": "<replace-with-your-client-id>",
    "PIN": "<replace-with-your-client-credentials>"
  }
}

Send a GET request to /workers/{id} to confirm the Crypto Worker configuration:

GET /signserver/rest-managed/v1/workers/100

For a full configuration guide, see Set Up a Crypto Worker Using REST in the SignServer documentation.

Once a Crypto Worker is configured in SignServer, it becomes available to Signum as a key source. Rather than connecting to the external HSM directly, Signum uses SignServer. To make keys from SignServer available to Signum, create the connection through Signum's Certificate Signing Request (CSR) flow.

Only keys created through Signum are visible to Signum. Any previous keys in a HSM or keys created by SignServer are visible to SignServer.

When you generate a CSR in Signum, select the SignServer Crypto Worker to use for the key pair.

Generate a CSR using your Crypto Token

Generating a CSR in Signum creates a public and private key pair on the selected Crypto Token, where the private key is non-exportable from the HSM. The CSR captures the identifying information for the X.509 certificate being requested.

In the Signum Admin Web Console, navigate to Requests.
Select Generate CSR.
In the Crypto Token dropdown, select your token.

Signum's default Keyfactor-managed HSM appears as HSM. Any Crypto Token you have configured in SignServer appears in the same list, by the name you gave it in SignServer.
Complete the request. The key pair is generated on the selected token. The private key remains in your HSM and is not exportable.

Once the CSR is submitted and a certificate is issued against it, that key is active for Signum signing operations routed through SignServer.