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 ClientToolbox and Hardware Security Modules (HSM).
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.
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.|
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.|
The slot to use, identified with the type specified in SLOTLABELTYPE:
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.|
PKCS#11 attributes used for key generation specified directly in the property value. Optional, not allowed if ATTRIBUTESFILE is specified.
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.
Specify a PKCS#11 attribute to override the statically configured attribute to use when generating a key. Unlike the ATTRIBUTES and ATTRIBUTESFILE properties, this value can be changed without restarting the application server.
Where x is the object class: PUBLIC or PRIVATE.
This feature requires a patched Java Runtime Environment.
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.
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:
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".
Note on FIPS Mode
Some HSM vendors have started to enforce stricter rules on keys when the HSM is in FIPS mode. For instance, with Utimaco SecurityServer V4.10.0, the following is needed in order to generate key-pairs and activate the crypto token when the PKCS11CryptoToken is used:
Patched Java/SunPKCS11 (i.e. for RSASSA-PSS signature support and for setting allowed mechanisms).
- Key-pair to be generated with the following worker property set:
- The following worker property set in order for test signing to work: