Skip to main content
Skip table of contents

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.

(warning) 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.

PINAuthentication code for activation. Only required for auth-activation, otherwise the activatecryptotoken CLI command can be used.
SHAREDLIBRARYNAMEName 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 

(warning) 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 SLOTLISTINDEXLegacy 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:

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
}

 (warning) 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.

 (warning) 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.

(warning) 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.

(warning) 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:

CODE 
bin/signserver setproperties pkcs11-crypto-configuragtion.properties

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

CODE 
bin/signserver reload 8

Activate the crypto token by specifying the PIN code:

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:

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

Set the key as test key:

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

Test the keypair:

CODE 
bin/signserver testkey 8

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

CODE 
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:

CODE 
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:

CODE 
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.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close