Skip to main content
Skip table of contents

P11NG Crypto Token

ENTERPRISE

The P11NG Crypto Token uses PKCS#11 for communication with the HSM by using a new provider instead of the Java SunPKCS11 provider, which is used by the regular PKCS11 Crypto Token for example.

Fully qualified class name: CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.P11NGCryptoToken

Overview

As of SignServer 6.0, JackNJI11CryptoToken has been renamed P11NGCryptoToken.

To download a sample configuration file for this Worker, see Sample Worker Configurations.

Available Properties

Required Property

Description

PIN

Specifies the authentication code for activation.

Only required for auto-activation, otherwise manual activation can be performed.

SHAREDLIBRARYNAME

Specifies the name of pre-defined PKCS11 library to be used. The available libraries can be configured in signserver_deploy.properties.

SLOTLABELTYPE

Indicates how the slot should be identified. Supported values are SLOT_NUMBER,  SLOT_INDEX, or SLOT_LABEL.

SLOTLABELVALUE

Specifies 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

Property

Description

ATTRIBUTE.x.y.z

Specifies 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, and so on.
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:

CODE 
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

DEFAULTKEY

Specifies the key alias.

Since SignServer 7.4.0, the DEFAULTKEY property is no longer a required property for this worker.

If no default key is set, the connection between this worker and the HSM will be performed to determine if the Worker is ACTIVE or OFFLINE.

If a default key is set, a test signing will be performed to determine if the Worker is ACTIVE or OFFLINE.

GENERATE_CERTIFICATE_OBJECT

(Optional) 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 careful 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. Setting both properties to true might waste space in the HSM with an unnecessary object.

Default: True.

USE_CACHE

(Optional) Specifies if the 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.

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.

Composite Certificates

The P11NGCryptoToken can be used to create a composite key. For more information, see SignServer Composite Certificates.

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.

For asymmetric keys generated outside of SignServer to become available in SignServer, the keys need to have the CKA_ID attributes set correctly. SignServer uses the CKA_ID value to match private and public keys and as the source of the key name in the user interface. The cloudhsm-cli tool from AWS can be used to set id attributes on public and private keys.

  1. Follow the AWS instructions to install and configure cloudhsm-cli.

  2. Determine the value to use for the id attribute. SignServer expects the public and private keys id to be a hex encoding of the utf8 encoded key name. For example, “sample-key” would be encoded as 0x73616d706c652d6b6579. The od utility can be used to generate a key name like echo "sample-key" -n | od -t x1 -A n | tr -d ' '. Or python can be used like python -c "print('sample-key'.encode('utf8').hex())"

  3. Start the cloudhsm-cli utility:

    CODE 
    cloud-hsm interactive

  4. Log into your cloud hsm:

    CODE 
    aws-cloudhsm > login --username USERNAME --role crypto-user.

  5. Enter the password when prompted.

  6. Find the key-reference of the key you want to change. The key list command can be used to list keys and their attributes on your HSM.

  7. Set the private key id attribute. For example:

    CODE 
    key set-attribute --key-reference 0x0000000000000001 --name id --value 0x73616d706c652d6b6579

  8. Set the public key id attribute to the same value:

    CODE 
    key set-attribute --key-reference 0x0000000000000002 --name id --value 0x73616d706c652d6b6579

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:

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

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

  • 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 (such as, 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.

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close