HSM (PKCS#11) Operations Guide

Hardware Security Module integration for @anoobot/encryption using PKCS#11 (SoftHSM, Luna, AWS CloudHSM, etc.).

Environment Variables

Development (Software Simulator)

export NODE_ENV=development
export ALLOW_SOFTWARE_HSM=true
# Do not set ANOOBOT_HSM_ENABLED
pnpm exec vitest run packages/encryption/src/__tests__/hsm.test.ts

SoftHSM2 (Docker)

docker run -d --name softhsm \
  -e SOFTHSM_PIN=0000 \
  -v softhsm-tokens:/var/lib/softhsm/tokens \
  ghcr.io/opendnssec/softhsm2:latest

export ANOOBOT_HSM_ENABLED=true
export HSM_LIBRARY_PATH=/usr/lib/softhsm/libsofthsm2.so
export HSM_SLOT_ID=0
export HSM_PIN=0000
export HSM_TEST=true
pnpm exec vitest run packages/encryption/test/hsm.integration.test.ts

Production Checklist

1. Provision HSM token and create AES-256 keys with labels matching your key hierarchy.
2. Set ANOOBOT_HSM_ENABLED=true and never set ALLOW_SOFTWARE_HSM in production.
3. Run validateHsmProductionConfig() at gateway/desktop startup.
4. Monitor HSM login failures and encrypt/decrypt error rates in Prometheus.
5. Rotate PINs via your HSM vendor procedure; update secrets manager, not git.

Supported Operations

• Key generation (AES-256)
• Encrypt / decrypt (AES-GCM via PKCS#11 when token supports CKM_AES_GCM)
• Sign / verify (PKCS#11 backend only)

Troubleshooting