ENTERPRISE This is a SignServer Enterprise feature.

Overview

Crypto token using PKCS#11 for talking with the HSM but using a different provider than the SunPKCS11 provider used by for instance the regular PKCS11CryptoToken.

CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.JackNJI11CryptoToken

Available Properties

Property	Description
DEFAULTKEY	The key alias. Required.
PIN	Authentication code for activation. Only required for auto-activation, otherwise manual activation can be performed.
SHAREDLIBRARYNAME	Name of pre-defined PKCS11 library to be used. The available libraries can be configured in signserver_deploy.properties. Required.
SLOTLABELTYPE	Indicates how the slot should be identified. Supported values are SLOT_NUMBER, or SLOT_INDEX. 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 Required. SLOT_LABEL is currently not supported.
ATTRIBUTE.x.y.z	Specify a PKCS#11 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". An exception to this is CKA_ALLOWED_MECHANISMS, which currently cannot be specified in decimal or hexadecimal form. Examples: `ATTRIBUTE.PUBLIC.RSA.CKA_ENCRYPT =` `false` `ATTRIBUTE.PUBLIC.RSA.CKA_VERIFY =` `false` `ATTRIBUTE.PUBLIC.RSA.CKA_WRAP =` `false` `ATTRIBUTE.PRIVATE.RSA.CKA_SIGN =` `true` `ATTRIBUTE.PRIVATE.RSA.CKA_PRIVATE =` `true` `ATTRIBUTE.PRIVATE.RSA.CKA_SENSITIVE =` `true` `ATTRIBUTE.PRIVATE.RSA.CKA_EXTRACTABLE =` `false` `ATTRIBUTE.PRIVATE.RSA.CKA_DECRYPT =` `false` `ATTRIBUTE.PRIVATE.RSA.CKA_UNWRAP =` `false` `ATTRIBUTE.PRIVATE.RSA.0X0000010C=FALSE` `ATTRIBUTE.PRIVATE.RSA.CKA_ALLOWED_MECHANISMS=CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS,` `0x00000043, CKM_RSA_PKCS_PSS`
GENERATE_CERTIFICATE_OBJECT	If true, when generating a key pair, creates a certificate object with a self-signed dummy certificate and defaults to not persist the public key object. The default value is 'true' for historical reasons and is the same as when generating a key pair with for instance the PKCS11CryptoToken (or any other Java application using the SunPKCS11 provider). This property can be set either in the crypto worker, on the worker that is going to use the key, or both, which means that different options can be used for different workers. Setting this property in the crypto token makes it the default setting for all workers using that crypto token. If the worker also includes this property, the property value of the worker will override this setting. Be cautious if you also set any of the ATTRIBUTE.PUBLIC.*.CKA_TOKEN property attributes since some combinations like GENERATE_CERTIFICATE_OBJECT=false and CKA_TOKEN=false may not be useful, and setting both properties to true might waste space in the HSM with an unnecessary object. Optional. Default true.
USE_CACHE	Specify if key and certificate search results from the HSM should be cached. This can prevent problems due to too many find object requests under high load with some PKCS#11 implementations. Optional: default true.

Secret Key generation

If generating a secret key through the JackNJI11CryptoToken, the algorithm name can be supplied in the following ways. See also Crypto Token Generate Key Page.

Standard Java Name

Example: AES, DES.

If the specified key algorithm name is not present in the predefined list of known secret key algorithms, the key algorithm name must be specified with the prefix "SEC:", for example: SEC:Blowfish. Currently, the secret key list contains the algorithms AES and DES.

CKM Long value

Example: SEC:4224. Here 4224 represents the long value for the AES_KEY_GEN constant as per the PKCS11 specification. "SEC:" is used as prefix.

CKM Hexadecimal value

Example: SEC:0x00001080. Here 0x00001080 represents a hexadecimal value for the AES_KEY_GEN constant as per the PKCS11 specification. "SEC:" is used as prefix.

HSM Specific Notes

AWS CloudHSM

Configure the worker or crypto token not to generate any certificate by setting GENERATE_CERTIFICATE_OBJECT=false. For details, see the GENERATE_CERTIFICATE_OBJECT property in Available Properties.

Known Limitations

Multiple different CA certificates with the same subject DN cannot be stored in the token (see DSS-1544).
Changes made in an HSM slot from a different process (i.e. outside the application server) might not be visible within SignServer without a restart of the application server. To use new key-pairs directly, it is recommended to generate the keys from within SignServer.
Under normal circumstances, PKCS#11 sessions are being reused and never closed with this crypto token. This means that objects created as session objects (i.e. with CKA_TOKEN=false) are not removed until the application is shut down. For one-time/short-lived/ephemeral keys use cases, where many keys are generated and deleted, this could mean that objects created as session objects are still kept and could eventually lead to a CKR_DEVICE_MEMORY error. We recommend upgrading to SignServer version 5.8.2 or later and making sure to have CKA_TOKEN=true for the objects being created so that they will be removed when deleting the key. See the ATTRIBUTES.x.y.z. property above.