Skip to main content

PKCS#11 Cryptography Provider

The PKCS#11 Cryptography Provider connects the platform to hardware security modules (HSMs) through their PKCS#11 interface, so that keys are generated and used on the HSM while the platform manages them. One connector can serve several HSMs, including HSMs from different vendors.

The connector implements the Cryptography Provider v2 interface and supports the following operations:

OperationSupported
Key pair generationRSA (2048, 3072 and 4096 bits), ECDSA (P-256, P-384 and P-521), ML-DSA (ML-DSA-44, ML-DSA-65 and ML-DSA-87), SLH-DSA (SHA2 at security categories 1, 3 and 5, for small signatures or fast signing)
Signing and verificationRSA PKCS#1 v1.5, RSA-PSS and ECDSA with SHA-256, SHA-384 or SHA-512, ML-DSA, SLH-DSA
Encryption and decryptionRSA only: PKCS#1 v1.5, and OAEP with SHA-1, SHA-256, SHA-384 or SHA-512
Random dataUp to 1 MiB per request
Key destructionRemoves the key from the HSM

The connector offers only what the HSM reports: an algorithm, key size or signature scheme appears when the token provides the mechanisms it needs, so the choices depend on the HSM and its firmware. Keys cannot be imported or exported through the platform, and every operation runs synchronously.

How it works​

How it works diagram

How it works diagram

100%Scroll to explore · Esc to close
How it works diagram
How it works diagram
Open full diagram ↗

The connector loads no PKCS#11 library itself. Each vendor's library runs with a PKCS#11 proxy in its own sidecar container, in the same pod as the connector, and only that sidecar connects to the vendor's HSM. Commercial libraries are licensed separately, so you build each vendor's sidecar image yourself; see Deploy the PKCS#11 Cryptography Provider.

A Config Profile names one sidecar. Each Token in the platform selects a Config Profile and one token that the HSM behind it presents.

The connector is validated with the following HSMs:

HSMNotes
SoftHSMA software token for evaluation and testing. Its sidecar image is published complete.
Utimaco CryptoServerStandard and QuantumProtect firmware.
Securosys PrimusPrimus HSMs and Securosys CloudHSM.
Entrust nShieldNetwork-attached HSMs. Keys are kept as wrapped key blobs on a persistent volume.

Prerequisites​

Before you start, make sure that:

  • The connector is deployed with the Config Profiles for your HSMs, and registered in the platform. See Deploy the PKCS#11 Cryptography Provider.
  • You know the user PIN of each HSM token that the platform will use.
  • A Vault Profile is available in the platform to store the PINs.

Configuration in the platform​

Store the PIN​

The user PIN of the token is supplied to the connector as a Secret. Create a Secret of type Generic through a Vault Profile, with the PIN as its content.

The User PIN attribute of the Token lists only secrets of this type. The platform resolves the PIN for each request, and the connector does not store it.

Create the Token​

Create a Token that uses the connector. The connector defines the following attributes:

AttributeRequiredDescription
Config profileYesThe Config Profile, and so the sidecar and HSM, that serves the token
TokenYesOne of the initialized tokens that the selected Config Profile reports. It is stored as a PKCS#11 URI, such as pkcs11:token=my-token;serial=0123456789abcdef;slot-id=1
User PINYesThe Generic secret holding the user PIN of the token

The status of the Token shows whether the connector reaches it: Connected, Disconnected when the sidecar or the token cannot be reached, Warning when the token answers but needs attention, such as a locked PIN, and Unknown when it cannot be determined, such as when the HSM has no free session. The status check sends no PIN, so a Connected token does not confirm the PIN; the first key operation does.

Create the Token Profile​

Create a Token Profile on the Token, with the key usages its keys may have, such as signing and verification for a signing key. For a token that supports ML-DSA, the connector adds one attribute:

AttributeRequiredDescription
ML-DSA signing modeNopure, the default, sends the whole message to the HSM. external-mu, offered when the token supports it, sends only a 64-byte digest of the message (μ, as defined by FIPS 204), so that messages above the input limit of the HSM can be signed. Both produce standard ML-DSA signatures. Keys of other algorithms ignore the setting

Create a test key​

Create a Key in the Token Profile. The connector defines the following attributes:

AttributeRequiredDescription
Key LabelNoLabel of both halves of the key pair on the HSM. Left empty, the label is the UUID of the key
Cryptographic Key AlgorithmYesRSA, ECDSA, ML-DSA or SLH-DSA, as far as the token supports them. The required parameters of the selected algorithm follow: RSA Key Size, Named Curve, or NIST Security Category, and for SLH-DSA also Hash Function and Signature Generation Mode
SensitiveNoWhether the value of the private key can never be read from the HSM in plaintext. Default: enabled
ExtractableNoWhether the HSM lets the private key be exported, wrapped by another key. Default: disabled

Sensitive and Extractable apply to the private key and cannot be changed after the key is created.

A created key confirms the whole path: the connector reaches the HSM, the token accepts the PIN, and the HSM generates the selected algorithm. To test an operation, sign data with the key through the Cryptographic Operations API.

If a step fails, see Troubleshooting.