enterprise

Overview

Crypto token using PKCS#11 for communication with the HSM but using a new provider instead of the Java SunPKCS11 provider (utilized by the regular PKCS11CryptoToken for example).

Note that the JackNJI11CryptoToken has been renamed P11NGCryptoToken as of SignServer 6.0.

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

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,  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 is the label of the slot

Required.

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, EdDSA 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).

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

(minus) 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 P11NGCryptoToken, 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.

GCP KMS

  • The Google Cloud HSM does not support key generation, key wrapping, or import of certificate chains via SignServer.

  • Keys generated using the Google Cloud Platform (GCP) console must either have the algorithm type _RAW_PKCS1 to work with any hash algorithm in SignServer or you must ensure that the hash algorithm of the generated key corresponds to the hash in the signature algorithm in the SignServer worker configuration. Selecting a signature algorithm that does not match the algorithms used when the key was generated will result in an error like the following: "ExceptionConverter: java.security.SignatureException: org.pkcs11.jacknji11.CKRException: 0x00000020: DATA_INVALID"

Thales TCT

It is required to change the ATTRIBUTE.PUBLIC.RSA.CKA_VERIFY PKCS#11 attribute to true (not a default value) when generating an RSA key pair using the Thales TCT HSM. The reason behind this is currently unknown.

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 P11NGCryptoToken is used and the choice of RSA padding is PSS:

  • Key-pair to be generated with the following worker properties set:

    ATTRIBUTE.PRIVATE.RSA.CKA_ALLOWED_MECHANISMS=CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS
    SELFSIGNED_SIGNATUREALGORITHM=SHA256withRSAandMGF1

  • The following worker property set in order for test signing to work:

    SIGNATUREALGORITHM=SHA256withRSAandMGF1

For keys using the PKCS1_v1.5 padding instead, the CKA_ALLOWED_MECHANISMS should only contain mechanisms like CKM_RSA_PKCS and CKM_SHA256_RSA_PKCS and the algorithm properties should then be for instance SHA256withRSA.

Known Limitations

  • Multiple different CA certificates with the same subject DN cannot be stored in the token (see DSS-1544).
  • Under normal circumstances, PKCS#11 sessions are being reused and never closed by this crypto token unless for some failures. 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.