P11NG Crypto Token | Keyfactor Docs

Enterprise

The P11NG Crypto Token uses PKCS#11 for communication with the HSM through the Keyfactor P11NG provider, in place of the Java SunPKCS11 provider used by the standard PKCS#11 Crypto Token. P11NG is the recommended token type for production HSM deployments and is required for features such as key wrapping and composite certificates.

Fully qualified class name: 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.

Key Aliases and Certificate Objects on the HSM

Key aliases in SignServer map to the CKA_LABEL attribute on the PKCS#11 certificate object stored on the HSM. Private keys are matched to certificate objects through a shared CKA_ID value. For a full explanation of this mechanism, including certificate placement options, caching behavior, externally generated keys, and certificate import, see Crypto Tokens: HSMs & Keystores | Key Aliases, Certificates, and PKCS#11 Objects.

Available Properties

Required Property	Description
`SHAREDLIBRARYNAME`	The name of pre-defined PKCS#11 library to use. Available libraries are configured in `signserver_deploy.properties`.
`SLOTLABELTYPE`	Specifies how the slot is identified. Supported values: `SLOT_NUMBER`, `SLOT_INDEX`, or `SLOT_LABEL`.
`SLOTLABELVALUE`	Specifies which slot to use, according to the type set in `SLOTLABELTYPE`: `SLOT_NUMBER`: the numeric ID of the slot `SLOT_INDEX`: the zero-base index of the slot in the list of available slots as returned by the PKCS#11 provider `SLOT_LABEL`: the label of the slot
Optional Property	Description
`ATTRIBUTE.x.y.z`	Specifies a PKCS#11 attribute to use when generating a key. - `x` is the object class: `PUBLIC` or `PRIVATE` - `y` is the key algorithm: `RSA`, `ECDSA`, `EdDSA`, and so on - `z` is the attribute name, a decimal attribute ID, or a hexadecimal ID prefixed with `0x`. Exception: `CKA_ALLOWED_MECHANISMS` 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
`DEFAULTKEY`	The key alias used to verify that the Crypto Token is active. See Crypto Tokens: HSMs & Keystores \| Key Aliases, Certificates, and PKCS#11 Objects for how this alias maps to objects on the HSM. Since SignServer 7.4.0, the `DEFAULTKEY` property is no longer required: If not set, the Worker checks connectivity to the HSM to determine ACTIVE/OFFLINE status. If set, a test signing is performed to determine status.
`GENERATE_CERTIFICATE_OBJECT`	(Optional) If `true`, generating a key pair also creates a PKCS#11 certificate object on the HSM containing a self-signed placeholder certificate. The public key object is not persisted by default when this is enabled. The placeholder is not a valid signing certificate. A real certificate must be imported before signing. See Crypto Tokens: HSMs & Keystores \| Key Aliases, Certificates, and PKCS#11 Objects for details. This property can be set on the Crypto Worker (as a default for all workers using it), on an individual signing Worker (to override the Crypto Worker default), or both. Default: `true` (for compatibility with the SunPKCS11-based PKCS#11 Crypto Token and other Java PKCS#11 applications). Be careful when also setting `ATTRIBUTE.PUBLIC.*.CKA_TOKEN`. Setting `GENERATE_CERTIFICATE_OBJECT=false` with `CKA_TOKEN=false` produces no persistent objects, which is unlikely to be useful. Setting both to `true` creates an unnecessary public key object that consumes HSM storage.
`PIN`	Specifies the authentication code used for activation. Only required for auto-activation. Manual activation can be performed without it.
`SET_CKA_START_DATE`	If `true`, newly generated keys will have the `CKA_START_DATE` attribute set on the public key. The value is the date at the time of key generation, and can be used when generating a CSR or performing PGP signing.
`USE_CACHE`	(Optional) If `true`, caches key and certificate search results from the HSM. This reduces the number of find-object calls and can prevent performance issues under high load with some PKCS#11 implementations. If a certificate on the HSM is replaced, reload the Worker to pick up the updated value. See Crypto Tokens: HSMs & Keystores \| Key Aliases, Certificates, and PKCS#11 Objects for details. Default: `true`.

Secret Key Generation

If generating a secret key through the P11NGCryptoToken, the algorithm name can be specified in any of the following ways. See also Crypto Token Generate Key Page.

Standard Java Name

Example: AES or DES. If the algorithm name is not in the predefined list of known secret key algorithms, prefix it with SEC:, for example: SEC:Blowfish. The predefined list currently contains AES and DES.

CKM Long value

Example: SEC:4224. Here 4224 represents the long value for the AES_KEY_GEN as defined in the PKCS#11 specification. SEC: is used as prefix.

CKM Hexadecimal value

Example: SEC:0x00001080, where 0x00001080 is the hexadecimal representation of AES_KEY_GEN. 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

AWS CloudHSM does not support PKCS#11 certificate objects on the token. Set GENERATE_CERTIFICATE_OBJECT=false on the Worker or Crypto Token to prevent SignServer from attempting to create one.

For keys generated outside SignServer (for example, in the AWS console or via the AWS CLI), the CKA_ID attribute must be set on both the public and private key objects before SignServer can use them. See Crypto Tokens: HSMs & Keystores | Key Aliases, Certificates, and PKCS#11 Objects for an explanation of why CKA_ID matters.

To set CKA_ID using the cloudhsm-cli tool from AWS:

Install and configure cloudhsm-cli following the AWS instructions.
Determine the id attribute to use. SignServer expects the public and private keys id to be a hex encoding of the UTF-8 encoded key name. For example, the key name sample-key encodes to 0x73616d706c652d6b6579. You can generate this with the od utility:
```
 echo "sample-key" -n | od -t x1 -A n | tr -d ' '
```
Or with Python:
```
python -c "print('sample-key'.encode('utf8').hex())"
```
Start cloudhsm-cli:
```
cloud-hsm interactive
```

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

List keys to find the key-reference values for the key pair you want to update:
```
key list
```

Set the id attribute in the private key:

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

Set the same id attribute on the public key:

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

Key Creation Date for PGP Signing

Since AWS CloudHSM cannot store PKCS#11 certificate objects, PGP signing and CSR generation cannot rely on certificate metadata from the HSM to determine the key creation date.

To solve this issue, configure the OpenPGP Signer with a fixed key creation date using the following property:

KEY_START_DATE.keyalias=YYYYMMDD

The configured date is used as the key creation date.

GCP KMS

The Google Cloud HSM does not support key generation, key wrapping, or import of certificate chains via SignServer.
Keys generated in the GCP console must use the algorithm type *_RAW_PKCS1 to work with any hash algorithm in SignServer. Alternatively, ensure the hash algorithm of the key matches the signature algorithm configured in the SignServer Worker. A mismatch produces an error similar to:
```
ExceptionConverter: java.security.SignatureException: org.pkcs11.jacknji11.CKRException: 0x00000020: DATA_INVALID
```

Thales TCT

When generating an RSA key pair using the Thales TCT HSM, the ATTRIBUTE.PUBLIC.RSA.CKA_VERIFY attribute must be explicitly set to true (it is not enabled by default). Failure to do so will cause key generation to fail.

FIPS Mode

Some HSM vendors enforce stricter key constraints when operating in FIPS mode. For example, with Utimaco SecurityServer V4.10.0 and PSS padding, the following configuration is required:

When generating the key pair:

XML

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

For test signing to work after activation:
XML
```
SIGNATUREALGORITHM=SHA256withRSAandMGF1
```

For keys using PKCS#1 v1.5 padding, CKA_ALLOWED_MECHANISMS should contain only mechanisms such as CKM_RSA_PKCS and CKM_SHA256_RSA_PKCS, and the signature algorithm properties should use SHA256withRSA.

Known Limitations

Multiple CA certificates with the same subject DN cannot be stored in the same token slot.
PKCS#11 sessions are reused and never explicitly closed by this Crypto Token under normal conditions. Objects created as session objects (CKA_TOKEN=false) are therefore not removed until the application server is shut down. In deployments that generate and delete many short-lived keys, this can eventually cause a CKR_DEVICE_MEMORY error as session objects accumulate. To avoid this, upgrade to SignServer 5.8.2 or later and set CKA_TOKEN=true for key objects so that they are correctly removed when a key is deleted. See the ATTRIBUTE.x.y.z property above.