---
checkId: check.crypto.hsm
plugin: stellaops.doctor.crypto
severity: warn
tags: [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
```bash
# 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
```bash
# 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
```yaml
# values.yaml
crypto:
  hsm:
    enabled: true
    modulePath: /usr/lib/softhsm/libsofthsm2.so
    pinSecret: stellaops-hsm-pin
    slotId: 0
```

```bash
# 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