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 ClientToolbox and Hardware Security Modules (HSM).

CRYPTOTOKEN_IMPLEMENTATION=org.signserver.server.cryptotokens.PKCS11CryptoToken

Available Properties

Property

Description

DEFAULTKEY

The key alias. Required.

NEXTCERTSIGNKEY

The next key to use. This property can be used to hold the name of the next key to use. Certificate signing requests (CSR) can be made for this key while to 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

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg 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
}

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg 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.

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg 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.

ATTRIBUTE.x.y.z

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.
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". An exception to this is CKA_ALLOWED_MECHANISMS, which currently cannot be specified in decimal or hexadecimal form.

Examples:

ATTRIBUTE.PRIVATE.RSA.CKA_SENSITIVE=TRUE
ATTRIBUTE.PRIVATE.RSA.0X0000010C=FALSE
ATTRIBUTE.PRIVATE.RSA.CKA_ALLOWED_MECHANISMS=CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS, 0x00000043, CKM_SHA256_RSA_PKCS_PSS

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg This feature requires a patched Java Runtime Environment.

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.

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg 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.

images/s/en_US/8100/b0984b7297905b7c7bd946458f753ce0130bfc8c/_/images/icons/emoticons/warning.svg 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:

  • 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".

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:

    ATTRIBUTE.PRIVATE.RSA.CKA_ALLOWED_MECHANISMS=CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS
  • The following worker property set in order for test signing to work:

    SIGNATUREALGORITHM=SHA256withRSAandMGF1