PKCS11CryptoToken

Overview

PKCS11 allows using an HSM that has a PKCS11 module, such as Utimaco, nCipher, SafeNet or AEP KeyPer.

SignServer uses the same underlying implementation of PKCS11 crypto tokens as EJBCA but since the token labels strings differ, it is important to use the properties listed in this section for SignServer. The EJBCA ClientToolbox tool can be used to generate and test PKCS11 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).

CRYPTOTOKEN_IMPLEMENTATION=org.signserver.server.cryptotokens.PKCS11CryptoToken

Available Properties

Property	Description
DEFAULTKEY	The key alias of the private key to be used for testing that this crypto token is working. If this key does not exist, the crypto token/worker will show as OFFLINE even if it has been activated. This is typically the case when the crypto token has been set up for the first time and the key has not yet been generated. To resolve, generate a key with the key alias name. A property with this name is typically also accepted by the worker using this crypto token and will then be the key to use for actual signing.
NEXTCERTSIGNKEY	A property with this name is typically configured in the worker using this crypto token to hold the name of the next key to use. Certificate signing requests (CSR) can be made for this key while the current key (DEFAULTKEY) is still in production. After uploading the new certificate the value of NEXTCERTSIGNKEY can be moved to DEFAULTKEY. Optional.
PIN	Authentication code for activation. Only required for auth-activation, otherwise the activatecryptotoken CLI command can be used.
SHAREDLIBRARYNAME	Name of pre-defined PKCS11 library to be used. The available libraries can be configured in signserver_deploy.properties. If the legacy SHAREDLIBRARY property is also defined, it must point to the same library on the file system. Required, unless the old SHAREDLIBRARY is set.
SHAREDLIBRARY	This property is deprecated. Full path to the library containing the PKCS11 interface. From version 3.7.0 this must point to a file declared in signserver_deploy.properties (or using the built-in values). If this property is defined at the same time as SHAREDLIBRARYNAME they must point to the same library on the file system.
SLOTLABELTYPE	Indicates how the slot should be identified. Supported values are SLOT_NUMBER, SLOT_INDEX or SLOT_LABEL. Required.
SLOTLABELVALUE	The slot to use, identified with the type specified in SLOTLABELTYPE: SLOT_NUMBER is the number (ID) of the slot SLOT_INDEX is the zero-base index of the slot in the list of available slots as returned by the PKCS#11 provider SLOT_LABEL this is the label of the slot Required but not allowed if the legacy properties SLOT or SLOTLISTINDEX are specified.
SLOT or SLOTLISTINDEX	Legacy properties for indicating which slot to use. Only available for backwards compatibility. Instead use the SLOTLABELTYPE and SLOTLABELVALUE properties.
ATTRIBUTESFILE	Path to file with PKCS#11 attributes used for key generation. Optional, not allowed if ATTRIBUTES is specified.
ATTRIBUTES	PKCS#11 attributes used for key generation specified directly in the property value. Optional, not allowed if ATTRIBUTESFILE is specified. Sample p11attributes.cfg: `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 the CKO_PRIVATEKEY to allow the key to be used without a login. Otherwise the key generation will fail with a CKR_USER_NOT_LOGGED_IN PKCS#11 error.
CACHE_PRIVATEKEY	If set to true, the private key and certificate is cached in the worker so that they are not queried for each signature. This could potentially improve performance in some environments, typically where network HSMs or HSM slots with many keys are used. Default: true. This worker property is to be specified in the worker where the key to be used is specified by the DEFAULTKEY property. It is that key that will be cached locally in the worker. It is important to remember this if the crypto token is configured in a separate worker in which case this property should be specified in the worker that will be using the crypto token and not necessarily in the one having the crypto token configuration. When enabled, the signer certificate is also cached if taken from the token and not overridden by specifying it in the configuration. This means that if the certificate in the token is changed, the old certificate will still be used until the worker is reloaded, clearing the cache. This property is needed in the signer when using a OneTimeCryptoWorker.

Default Global Properties

Certain worker properties can instead be specified as default values in the global configuration, to avoid having to repeat the propertied 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:

SHAREDLIBRARYNAME
SHAREDLIBRARY
SLOTLABELTYPE
SLOTLABELVALUE
SLOT
SLOTLISTINDEX
ATTRIBUTES
ATTRIBUTESFILE
PIN

Example Usage

Edit (preferably a copy of) pkcs11-crypto.properties to match your PKCS#11 token.

Run the following command to set up the token:

bin/signserver setproperties pkcs11-crypto-configuragtion.properties

Reload the configuration using the printed ID (in this example 8):

bin/signserver reload 8

Activate the crypto token by specifying the PIN code:

bin/signserver activatecryptotoken 8

Unless your DEFAULTKEY worker property points to an existing key in the HSM, the activation will look like it failed. Continue by creating a key that can be used for testing slot activation:

Generate a keypair in the token to be used as test key:

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

Set the key as test key:

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

Test the keypair:

bin/signserver testkey 8

You also need a certificate for the signer. Generate a certificate request with the command:

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

Add a user in EJBCA with a certificate profile suitable for signing, and enroll for a "Server Certificate" using the public web pages.

Create the certificate chain file with the command:

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

The signer certificate must be first, and the root CA certificate last.

The signer certificate should then be uploaded to the worker which should use it.

Upload the signing certificate chain to the signer using the command:

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, etc.
Where z is the attribute name or ID as decimal number or a hexadecimal number prefixed with "0x".

Known Issues

Certain Java versions are having issues with the RSASSA-PSS signature algorithm (SHAxWithRSAandMGF1).
Previously, the RSASSA-PSS signature algorithm (SHAxWithRSAandMGF1) was not supported with SunPKCS11 but later versions of Java 8 and 11 have added support for them. However, for Java versions before 11.0.7, the algorithm is only working with key sizes >=4096 bits. For details, refer to the OpenJDK bug JDK-8232950.