git.stella-ops.org/docs/doctor/articles/crypto/hsm.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.crypto.hsm	stellaops.doctor.crypto	warn	crypto hsm pkcs11 security

HSM/PKCS#11 Availability

What It Checks

Verifies HSM (Hardware Security Module) availability via PKCS#11 interface. The check validates three layers:

1. Module configuration: whether a PKCS#11 module path is configured via Crypto:Hsm:ModulePath or Cryptography:Pkcs11:ModulePath.
2. Module file existence: whether the configured .so (Linux) or .dll (Windows) file exists on disk.
3. Slot access: whether the PKCS#11 module can enumerate slots and access the configured slot.
4. Token presence: whether a token is initialized in the slot and accessible (login test).

Condition	Result
Module path not configured	Fail
Module file not found at configured path	Fail
Slot access failed (init error, no slots, permission denied)	Fail
Token not accessible (not initialized, login failure)	Warn
Module loaded, slot accessible, token present	Pass

Evidence collected: ModulePath, ModuleExists, SlotId, SlotLabel, SlotAccess, TokenPresent, TokenLabel.

The check only runs when Crypto:Hsm:Enabled or Cryptography:Pkcs11:Enabled is set to "true".

Why It Matters

HSMs provide tamper-resistant hardware protection for cryptographic keys. When HSM is enabled, all signing operations (attestations, evidence seals, certificate signing) depend on the HSM being accessible. An unavailable HSM means no signing can occur, which blocks evidence generation, attestation creation, and release approvals. HSM connectivity issues can silently degrade to software-based signing if fallback is enabled, which may violate compliance requirements for FIPS 140-2 Level 3 or eIDAS qualified signatures.

Common Causes

• PKCS#11 module path not configured in application settings
• Module file was moved or deleted from the configured path
• HSM software not installed (e.g., SoftHSM2 not installed for development)
• PKCS#11 module initialization failure (driver compatibility issues)
• No slots available in the HSM
• Permission denied accessing the PKCS#11 module or device
• Token not initialized in the configured slot
• Token login required but PIN not configured or incorrect

How to Fix

Docker Compose

# Verify HSM module is accessible
docker compose exec gateway ls -la /usr/lib/softhsm/libsofthsm2.so

# Initialize a token if needed (SoftHSM2 for development)
docker compose exec gateway softhsm2-util --init-token --slot 0 --label "stellaops" --pin 1234 --so-pin 0000

# List available slots
docker compose exec gateway softhsm2-util --show-slots

# Set environment variables
# Crypto__Hsm__Enabled=true
# Crypto__Hsm__ModulePath=/usr/lib/softhsm/libsofthsm2.so
# Crypto__Hsm__Pin=1234

docker compose restart gateway

Bare Metal / systemd

# Install SoftHSM2 (for development/testing)
sudo apt install softhsm2

# Configure PKCS#11 module path
stella crypto config set --hsm-module /usr/lib/softhsm/libsofthsm2.so

# Initialize token
softhsm2-util --init-token --slot 0 --label "stellaops" --pin 1234 --so-pin 0000

# List slots
softhsm2-util --show-slots

# Verify module permissions
ls -la /usr/lib/softhsm/libsofthsm2.so

# Configure token PIN
stella crypto config set --hsm-pin <your-pin>

# For Windows with SoftHSM2:
# stella crypto config set --hsm-module C:\SoftHSM2\lib\softhsm2.dll

# In appsettings.json:
# "Crypto": {
#   "Hsm": {
#     "Enabled": true,
#     "ModulePath": "/usr/lib/softhsm/libsofthsm2.so"
#   }
# }

sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
crypto:
  hsm:
    enabled: true
    modulePath: /usr/lib/softhsm/libsofthsm2.so
    pinSecret: stellaops-hsm-pin
    slotId: 0

# Create HSM PIN secret
kubectl create secret generic stellaops-hsm-pin \
  --from-literal=pin=<your-pin>

# For hardware HSMs, mount the device into the pod
# Add to pod spec: devices: ["/dev/pkcs11"]

# Initialize token
kubectl exec deploy/stellaops-gateway -- softhsm2-util --init-token --slot 0 --label stellaops --pin 1234 --so-pin 0000

helm upgrade stellaops ./charts/stellaops -f values.yaml

Verification

stella doctor run --check check.crypto.hsm

Related Checks

• check.crypto.fips — FIPS 140-2 Level 3+ requires key storage in a validated HSM
• check.crypto.eidas — qualified eIDAS signatures may require HSM-backed keys
• check.crypto.certchain — the TLS certificate private key may reside in the HSM
• check.compliance.attestation-signing — attestation signing keys may be HSM-protected