Set up a Crypto Worker

A Crypto Worker is a Worker that performs no signing operations of its own. Its sole purpose is to host a Crypto Token, the component that provides access to keys and cryptographic operations, so that other Workers can reference it using the CRYPTOTOKEN property.

This page describes how the Crypto Token is configured within the Crypto Worker, and how to set up a Crypto Worker using the Admin Web or the REST Interface.

For conceptual background on Crypto Tokens, key aliases, and PKCS#11 objects, see Crypto Tokens: HSMs & Keystores.

Crypto Token Configuration

The Crypto Worker itself only requires the mandatory Worker properties. The actual configuration lives in the Crypto Token, defined by two things:

1. The Crypto Token implementation, set with the CRYPTOTOKEN_IMPLEMENTATION_CLASS property. This determines whether keys are stored in an HSM or a software keystore.

2. The implementation-specific properties, such as HSM slot details or the keystore path.

The following properties define the Worker and its Crypto Token:

PKCS#11 Crypto Token properties (HSM)

For all available properties, see PKCS#11 Crypto Token.

Keystore Crypto Token properties (soft keystore)

For all available properties, see Keystore Crypto Token.

The following shows a complete example configuration for a Crypto Worker hosting a PKCS#11 Crypto Token:

WORKERGENID1.TYPE=CRYPTO_WORKER
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.server.signers.CryptoWorker
WORKERGENID1.CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.server.cryptotokens.PKCS11CryptoToken

# Name for other Workers to reference this Crypto Token:
WORKERGENID1.NAME=HSMCryptoToken1

# PKCS#11 shared library and HSM slot details:
WORKERGENID1.SHAREDLIBRARYNAME=Utimaco
WORKERGENID1.SLOTLABELTYPE=SLOT_NUMBER
WORKERGENID1.SLOTLABELVALUE=1
WORKERGENID1.PIN=foo123

# One key to test activation with is required. If this key does not
# already exist, generate it after the Worker has been created.
WORKERGENID1.DEFAULTKEY=testkey0

Set Up a Crypto Worker Using the Administration Web

Using an HSM

To set up a Crypto Worker with a PKCS#11 Crypto Token, do the following:

1. Access the SignServer Admin Web.

2. On the Workers page, click Add and select From Template.

3. Select pkcs11-crypto.properties and click Next.

4. In the configuration text area, adjust the Crypto Token properties for your HSM:

   • NAME: Specify a name for the Worker, for example HSMCryptoToken1.

   • SHAREDLIBRARYNAME: The PKCS#11 shared library name for your HSM.

   • SLOTLABELTYPE and SLOTLABELVALUE: The slot identification for your HSM.

   • DEFAULTKEY: The alias of an existing key, or the alias of a test key to generate in the next step.

5. Click Apply.

6. Select the new Worker in the Workers list and click the Status Summary tab to check for any errors.

7. Enter the slot/partition password (if required by the HSM/keystore) and click Activate.

8. Select the new Worker in the Workers list and click the Status Summary tab to check for any errors.

9. If the Crypto Token is not already activated, click Activate, enter the slot/partition password (if any), and click Activate. The Crypto Token must be activated before keys can be generated on it.

10. If the DEFAULTKEY key does not yet exist, click the Crypto Token tab, select Generate Key, and specify the following:

    • Key Alias: The same alias as configured in DEFAULTKEY, for example testkey0.

    • Key Algorithm: For example RSA.

    • Key Specification: For example 2048.

11. Click Generate.

12. Click the Status Summary tab and confirm that the Worker status and Token status are both ACTIVE.

If the Worker is not in the state ACTIVE, check for errors on the Status Summary tab and then in the server log if needed.

Using a Soft Keystore

To set up a Crypto Worker with a Keystore Crypto Token, do the following:

1. Access the SignServer Admin Web.

2. On the Workers page, click Add and select From Template.

3. Select keystore-crypto.properties and click Next.

4. In the configuration text area, adjust the Crypto Token properties:

   • NAME: Specify a name for the Worker, for example SoftCryptoToken1.

   • KEYSTORETYPE: INTERNAL to store the keystore in the SignServer database.

   • KEYSTOREPATH: Clear this property since the internal keystore type is used.

5. Click Apply.

6. Select the new Worker in the Workers list and click the Status Summary tab to check for any errors.

7. Click Activate and specify a password, then click Activate. When using the internal keystore type, the password is set the first time the token is activated. The Crypto Token must be activated before keys can be generated on it.

8. Since the internal keystore starts out empty, generate the DEFAULTKEY key: click the Crypto Token tab, select Generate Key, and specify the following:

   • New Key Alias: The same alias as configured in DEFAULTKEY, for example testkey0.

   • Key Algorithm: For example RSA.

   • Key Specification: For example 2048.

9. Click Generate.

10. Click Activate again and enter the keystore password.

The Crypto Worker should now be in state ACTIVE. If not, check for errors on the Status Summary tab.

Set Up a Crypto Worker Using REST

The SignServer REST Interface allows you to create and configure the Crypto Worker programmatically. For general information on the REST Interface, including authentication and the OpenAPI specification, see REST API Interface.

Administrative REST operations require:

• A client TLS certificate for an authorized administrator, provided with the request.

• The X-Keyfactor-Requested-With header, which protects the endpoints against CSRF and clickjacking.

The following examples show the endpoints and request/response bodies independently of any specific HTTP client. For complete, ready-to-run examples with authentication included, see Admin REST Endpoints and Client REST Endpoints.

Step 1: Create the Crypto Worker

Send a POST request to the /workers endpoint with the Worker properties in the request body. Note that the properties are the same as in the properties file example above, but without the WORKERGENID1 prefix:

Request

POST /signserver/rest/v1/workers

Request Body

{
  "properties": {
    "TYPE": "CRYPTO_WORKER",
    "IMPLEMENTATION_CLASS": "org.signserver.server.signers.CryptoWorker",
    "CRYPTOTOKEN_IMPLEMENTATION_CLASS": "org.signserver.server.cryptotokens.PKCS11CryptoToken",
    "NAME": "HSMCryptoToken1",
    "SHAREDLIBRARYNAME": "Utimaco",
    "SLOTLABELTYPE": "SLOT_NUMBER",
    "SLOTLABELVALUE": "1",
    "PIN": "foo123",
    "DEFAULTKEY": "testkey0"
  }
}

curl --location --request POST 'https://localhost:8443/signserver/rest/v1/workers' \
  --cert dss10_admin1.p12 --cert-type p12 --pass foo123 \
  --header 'X-Keyfactor-Requested-With: X' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "properties": {
      "TYPE": "CRYPTO_WORKER",
      "IMPLEMENTATION_CLASS": "org.signserver.server.signers.CryptoWorker",
      "CRYPTOTOKEN_IMPLEMENTATION_CLASS": "org.signserver.server.cryptotokens.PKCS11CryptoToken",
      "NAME": "HSMCryptoToken1",
      "SHAREDLIBRARYNAME": "Utimaco",
      "SLOTLABELTYPE": "SLOT_NUMBER",
      "SLOTLABELVALUE": "1",
      "PIN": "foo123",
      "DEFAULTKEY": "testkey0"
    }
  }'

If the request is successful, SignServer returns status 201 Created and assigns a Worker ID. To create the Worker with a specific ID instead, send the request to POST /workers/{id}.

To use a soft keystore instead of an HSM, replace the Crypto Token properties accordingly:

{
  "properties": {
    "TYPE": "CRYPTO_WORKER",
    "IMPLEMENTATION_CLASS": "org.signserver.server.signers.CryptoWorker",
    "CRYPTOTOKEN_IMPLEMENTATION_CLASS": "org.signserver.server.cryptotokens.KeystoreCryptoToken",
    "NAME": "SoftCryptoToken1",
    "KEYSTORETYPE": "INTERNAL",
    "DEFAULTKEY": "testkey0"
  }
}

Step 2: Verify Configuration

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

Request

GET /signserver/rest/v1/workers/100

The response contains the full set of configured Worker properties.

Step 3: Update Properties

To change or add individual Crypto Token properties without affecting the rest of the configuration, send a PATCH request to /workers/{id}.

Request

PATCH /signserver/rest/v1/workers/100

Request Body

The body only needs to contain the properties to add or change:

{
  "properties": {
    "SLOTLABELVALUE": "2"
  }
}

Response

{ 
"responseMessage": "Worker properties successfully updated" 
}

Step 4: Reload the Worker

Configuration changes become active after a reload. Send a POST request to /workers/reload with the Worker ID in the request body:

Request

POST /signserver/rest/v1/workers/reload

Request Body

{
  "workerIDs": [ 100 ]
}

If the request body is left empty, all Workers are reloaded.

Response

{
  "responseMessage": "All requested workers successfully reloaded"
}

Next Steps

With the Crypto Worker in state ACTIVE, other Workers can now use its Crypto Token by referencing the Worker name:

CRYPTOTOKEN=HSMCryptoToken1

For guidance on where to install signing certificates and how key aliases are resolved on the token, see Crypto Tokens: HSMs & Keystores.