PKCS#11 Crypto Token | Keyfactor Docs

The PKCS#11 Crypto Token allows using an HSM that has a PKCS#11 module, such as Utimaco, nCipher, SafeNet, or AEP KeyPer.

Fully qualified class name: org.signserver.server.cryptotokens.PKCS11CryptoToken

Overview

SignServer uses the same underlying implementation of PKCS#11 Crypto Tokens as EJBCA. Because token labels strings differ, it is important to use the SignServer-specific properties listed in this section. The EJBCA ClientToolbox tool can be used to generate and test PKCS#11 keys to confirm that the keys can be used with SignServer. For more information, refer to the EJBCA documentation on EJBCA Client Toolbox and Hardware Security Modules (HSM).

To download a sample configuration file for this Worker, see Sample Worker Configurations.

Key Aliases and Certificate Objects on the HSM

Key aliases in SignServer map to the CKA_LABEL attribute on the PKCS#11 certificate object stored on the HSM. Private keys are matched to certificate objects through a shared CKA_ID value. For a full explanation of this mechanism, including certificate placement options, caching behavior, externally generated keys, and certificate import, see Crypto Tokens: HSMs & Keystores | Key Aliases, Certificates, and PKCS#11 Objects.

Available Properties

Property	Description
`ATTRIBUTES`	(Optional) Specifies the PKCS#11 attributes used for key generation specified directly in the property value. Cannot be used together with `ATTRIBUTESFILE`. Sample `p11attributes.cfg`: XML `attributes(generate,CKO_PUBLIC_KEY,) = { CKA_TOKEN = false CKA_ENCRYPT = true CKA_VERIFY = true CKA_WRAP = true } attributes(generate, CKO_PRIVATE_KEY,) = { CKA_TOKEN = true CKA_PRIVATE = true CKA_SENSITIVE = true CKA_EXTRACTABLE = false CKA_DECRYPT = true CKA_SIGN = true CKA_UNWRAP = true }` The PKCS#11 attributes configuration is global per shared library. If specified in multiple Workers, only the configuration from the first Worker loaded will be used. Changing the property might not take effect without restarting the application server. For a Thales nCipher module-protected slot (slot index 0), `CKA_PRIVATE` must be `false` for `CKO_PRIVATEKEY` to allow the key to be used without a login. Otherwise, key generation fails with a `CKR_USER_NOT_LOGGED_IN` error.
`ATTRIBUTESFILE`	(Optional) Path to file with PKCS#11 attributes used for key generation. Cannot be used together with `ATTRIBUTES`. From SignServer 7.6, the directory containing the `ATTRIBUTESFILE` must be on the allowlist. See Deploy-time Configuration.
`CACHE_PRIVATEKEY`	If `true`, caches the private key and signer certificate in the Worker so they are not fetched from the HSM on every signature request. This can improve performance with network HSMs or slots containing many keys Default: `true`. Set this property on the Worker where the signing key is specified in `DEFAULTKEY`, which is not necessarily on the Worker holding the Crypto Token configuration, if those are separate. When enabled, the signer certificate is also cached if it is sourced from the token. If the certificate on the token is replaced, the old certificate remains cached until the Worker is reloaded. For details, see Crypto Tokens: HSMs & Keystores \| Key Aliases, Certificates, and PKCS#11 Objects. This property is required in the Signer when using a One-time Crypto Worker.
`DEFAULTKEY`	The key alias used for test-signing when checking whether the Crypto Token is active. See Crypto Tokens: HSMs & Keystores \| Key Aliases, Certificates, and PKCS#11 Objects for how this alias maps to objects on the HSM. If this key does not exist, the Crypto Token/Worker shows as `OFFLINE` even after activation. This is expected when the token has just been set up and no key has been generated yet. Generate a key with the specified alias to resolve this. The `DEFAULTKEY` property is also accepted by a signing Worker referencing this Crypto Token, where it identifies the key to use for actual signing operations.
`NEXTCERTSIGNKEY`	(Optional) Holds the alias of the next key to use for signing. A certificate signing request (CSR) can be generated for this key while the current key (`DEFAULTKEY`) is still active in production. After the new certificate is uploaded, set `DEFAULTKEY` to the value previously held in `NEXTCERTSIGNKEY`.
`PIN`	The authentication code used for activation. Only required for auto-activation. Manual activation can be performed using the `activatecryptotoken` CLI command.
~~SHAREDLIBRARY~~	Deprecated Specifies the full path to the PKCS#11 library. Use `SHAREDLIBRARYNAME` instead. If both properties are defined, they must point to the same library on the file system.
`SHAREDLIBRARYNAME`	The name of the pre-defined PKCS#11 library to use. Available libraries are configured in `signserver_deploy.properties`. Required unless the legacy `SHAREDLIBRARY` property is set.
`SLOT` or `SLOTLISTINDEX`	Legacy properties for identifying the HSM slot. Available for backwards compatibility only. Use `SLOTLABELTYPE` and `SLOTLABELVALUE` instead.
`SLOTLABELTYPE`	Specifies how the slot should be identified. Supported values are `SLOT_NUMBER`, `SLOT_INDEX`, or `SLOT_LABEL`. Required.
`SLOTLABELVALUE`	Specifies the slot to use, according to the type set in `SLOTLABELTYPE`: `SLOT_NUMBER`: the numeric ID of the slot `SLOT_INDEX`: the zero-base index of the slot in the list of available slots as returned by the PKCS#11 provider `SLOT_LABEL`: the label of the slot Required. Cannot be used if the legacy `SLOT` or `SLOTLISTINDEX` properties are set.

Default Global Worker Properties

Certain Worker properties can instead be specified as default values in the global configuration, to avoid having to repeat the properties in every Worker. Individual Workers can override the default global values (if any), by specifying the property as usual.

Global default values are specified as global values in the global configuration with the name prefixed with DEFAULT.. The following properties can currently be specified in the global configuration:

Property	Description
`GLOB.DEFAULT.SHAREDLIBRARYNAME`	The name of the pre-defined PKCS#11 library.
`GLOB.DEFAULT.SLOTLABELTYPE`	How to identify the slot (`SLOT_NUMBER`, `SLOT_INDEX`, or `SLOT_LABEL`).
`GLOB.DEFAULT.SLOTLABELVALUE`	Which slot to use.
`GLOB.DEFAULT.ATTRIBUTES`	PKCS#11 key generation attributes (inline).
`GLOB.DEFAULT.ATTRIBUTESFILE`	Path to a PKCS#11 attributes file.
`GLOB.DEFAULT.PIN`	HSM activation PIN.

For more information on global properties, see Global Configuration Properties.

Example Usage

Copy pkcs11-crypto.properties and edit to match your PKCS#11 token.
Load the configuration:

bin/signserver setproperties pkcs11-crypto-configuragtion.properties

Reload the Worker using the ID printed by the previous command (in this example, 8):

bin/signserver reload 8

Activate the Crypto Token:

bin/signserver activatecryptotoken 8

If the key alias set in DEFAULTKEY does not yet exist on the HSM, activation appears to fail. Continue to the next step to create the test key.

Generate a key pair to use as the test key:

bin/signserver generatekey 8 -alias testkey1 -keyalg RSA -keyspec 2048

Set the new key as the DEFAULTKEY and reload:

bin/signserver setproperty 8 DEFAULTKEY testkey1
bin/signserver reload 8
bin/signserver activatecryptotoken 8

Test the key pair:

bin/signserver testkey 8

Generate a certificate signing request (CSR):

bin/signserver generatecertreq 8 "CN=PKCS11 Signer token" SHA1WithRSA /tmp/certreq.pem

Submit the CSR to a CA (for example, via EJBCA) to obtain a signed certificate.
Assemble the certificate chain, with the signer certificate first and root CA last:

cat /tmp/cert.pem /tmp/AdminCA1.pem > /tmp/certchain.pem

Upload the certificate chain to the signing Worker

bin/signserver uploadsignercertificatechain 9 GLOB /tmp/certchain.pem bin/signserver reload 9

Specify a PKCS#11 attribute to override the statically configured attribute to use when generating a key.
Where x is the object class: PUBLIC or PRIVATE.
Where y is the key type: RSA, ECDSA, and so on.
Where z is the attribute name or ID as decimal number or a hexadecimal number prefixed with "0x".

Known Issues

RSASSA-PSS (SHAxWithRSAandMGF1) compatibility with certain Java versions

The RSASSA-PSS signature algorithm was not supported with SunPKCS11 in older Java releases. Later versions of Java 8 and 11 added support, but for Java versions earlier than 11.0.7 the algorithm only works with key sizes of 4096 bits or larger.