Craton HSM

PKCS#11 Integrations

PKCS#11 Integrations

Craton HSM is loaded by any PKCS#11 v2.40 or v3.0 consumer as a standard shared library. This page collects configuration snippets for the integrations that are most commonly deployed against Craton HSM, along with minimum versions and known limitations.

Paths below assume the library has been installed to /opt/craton_hsm/libcraton_hsm.so on Linux or C:\Program Files\Craton HSM\craton_hsm.dll on Windows. Adjust as appropriate.

OpenSSL 3 (pkcs11-provider)

OpenSSL 3's preferred PKCS#11 integration is the pkcs11-provider OSSL 3 provider maintained by the Fedora crypto team.

  • Minimum OpenSSL: 3.0.8
  • Minimum pkcs11-provider: 0.5
  • Status: Works with all classical mechanisms. PQC mechanisms are not yet reachable through the provider's mechanism aliases.
# /etc/pki/tls/openssl.cnf
openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect

[default_sect]
activate = 1

[pkcs11_sect]
module = /usr/lib64/ossl-modules/pkcs11.so
pkcs11-module-path = /opt/craton_hsm/libcraton_hsm.so
pkcs11-module-token-pin = file:/etc/craton_hsm/user.pin
activate = 1

Smoke test:

openssl list -providers
openssl storeutl -text 'pkcs11:token=ProdToken'

Legacy engine_pkcs11 (OpenSSL 1.1)

For OpenSSL 1.1.x deployments, the legacy libp11 engine still works.

  • Minimum libp11: 0.4.11
[openssl_def]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib64/engines-1.1/pkcs11.so
MODULE_PATH = /opt/craton_hsm/libcraton_hsm.so
init = 0

Limitations: the engine does not route multi-part signing; large messages are buffered in memory before C_Sign.

Java SunPKCS11

Java's built-in SunPKCS11 provider loads Craton HSM directly.

  • Minimum JDK: 11 (PKCS#11 v3.0 headers shipped with JDK 17+ pick up more mechanisms)

Configuration file (/etc/craton_hsm/sunpkcs11.cfg):

name        = CratonHSM
library     = /opt/craton_hsm/libcraton_hsm.so
slot        = 0
showInfo    = true
attributes(generate,*,*) = {
  CKA_TOKEN = true
}

Usage:

import java.security.*;
import java.security.KeyStore;

Provider provider = Security.getProvider("SunPKCS11");
provider = provider.configure("/etc/craton_hsm/sunpkcs11.cfg");
Security.addProvider(provider);

char[] pin = "87654321".toCharArray();
KeyStore ks = KeyStore.getInstance("PKCS11", provider);
ks.load(null, pin);

for (String alias : Collections.list(ks.aliases())) {
    System.out.println(alias);
}

Limitations:

  • SunPKCS11 does not surface PQC mechanisms; the JDK's mechanism table lists classical mechanisms only.
  • Ed25519 requires JDK 15 or later and SunEC cooperation.
  • Operation-state save/restore is not used by SunPKCS11.

NSS (modutil)

NSS (Firefox, Thunderbird, certutil) manages PKCS#11 modules through modutil.

  • Minimum NSS: 3.70
# Register Craton HSM with an NSS database
modutil -dbdir sql:$HOME/.pki/nssdb -add "Craton HSM" \
  -libfile /opt/craton_hsm/libcraton_hsm.so

# Verify
modutil -dbdir sql:$HOME/.pki/nssdb -list

Limitations: NSS caches slot and mechanism information at add time; after token re-initialisation, run modutil -delete then -add again.

p11-kit and pkcs11-tool

p11-kit provides module discovery and proxying.

  • Minimum p11-kit: 0.24
# /etc/pkcs11/modules/craton_hsm.module
module: /opt/craton_hsm/libcraton_hsm.so
critical: yes
managed: yes

p11-kit list-modules
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-mechanisms
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-objects --pin 87654321

pkcs11-tool (from OpenSC) is the standard command-line exerciser for Craton HSM and is used throughout the rest of the documentation.

HashiCorp Vault (PKCS#11 seal)

Vault Enterprise supports PKCS#11 as an auto-unseal seal type.

  • Minimum Vault: 1.11 (Enterprise only; PKCS#11 seal is not in Vault OSS)
# vault.hcl
seal "pkcs11" {
  lib            = "/opt/craton_hsm/libcraton_hsm.so"
  slot           = "0"
  pin            = "87654321"
  key_label      = "vault-unseal-key"
  mechanism      = "0x1087"   // CKM_AES_GCM
  hmac_key_label = "vault-unseal-hmac"
  hmac_mechanism = "0x0251"   // CKM_SHA256_HMAC
  generate_key   = "false"
}

Limitations:

  • Vault expects the unseal key to exist before startup; create it via pkcs11-tool --keygen --key-type aes:32 --label vault-unseal-key first.
  • HMAC mechanism CKM_SHA256_HMAC is not currently registered by Craton HSM; use an AES-GCM-only seal (omit hmac_key_label / hmac_mechanism). This is tracked as a gap.
  • Vault retains an open session for the lifetime of the process.

Kubernetes PKCS#11 signer

The Kubernetes kube-apiserver supports a PKCS#11-based signer for ServiceAccount tokens via the external-signer plugin pattern. The most widely used implementation is k8s-pkcs11-signer.

  • Minimum Kubernetes: 1.24
  • Minimum k8s-pkcs11-signer: 0.3
# /etc/kubernetes/pkcs11-signer.yaml
module: /opt/craton_hsm/libcraton_hsm.so
slot: 0
pin_file: /etc/kubernetes/pkcs11.pin
key_label: sa-signing-key
mechanism: CKM_SHA256_RSA_PKCS

Wire into kube-apiserver:

apiServer:
  extraArgs:
    service-account-signing-key-file: pkcs11:///etc/kubernetes/pkcs11-signer.yaml
    service-account-key-file: /etc/kubernetes/pki/sa.pub

Limitations:

  • The signer expects a long-lived key with CKA_SIGN = true; configure CKA_START_DATE / CKA_END_DATE with care since a deactivated key blocks signing (see Key lifecycle).
  • Ed25519 signing is supported by Kubernetes 1.28+ but is not FIPS-approved.

Generic checklist

Before integrating, verify the environment:

# 1. Library loads and lists a slot
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-slots

# 2. Token is initialised
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-token-slots

# 3. User PIN is set
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --login --pin 87654321 \
  --test

# 4. Target mechanism is supported
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-mechanisms \
  | grep -i <mechanism>

Related