Getting Started · v1.0
The vendor-neutral, open-source tool that surfaces the health, security posture and PKCS#11 behavior of Hardware Security Modules in a single command. This guide answers what it is, why you need it, how to install it, and how to use it — from scratch.
$ hsmdoctor scan --module .../libsofthsm2.so --slot 1 --pin-env HSM_PIN Health Score: 38/100 CRITICAL Extractable private key legacy-signing (id 01) HIGH Weak RSA key (1024-bit) legacy-signing (id 01) MEDIUM Certificate expiring soon api-cert · 8 days left
01 · Concept
An HSM is a device that generates and protects cryptographic keys in hardware — the key material never leaves the device. Banking, PKI, code signing and TLS infrastructures usually have an HSM as their root of trust.
The common language for talking to these devices is the PKCS#11 (Cryptoki) standard. Excellent low-level PKCS#11 tools already exist; HSM Doctor instead focuses on the questions an HSM administrator actually asks. The “doctor” in the name is literal: it runs a check-up on a token and produces a health score with prioritized findings.
It ships as a single Go binary: the CLI, the embedded web interface and every feature live in one file. Key material and PINs are never read, logged or written to reports — by design it collects metadata only.
02 · Motivation
HSM Doctor turns raw token data into answers to four practical questions:
03 · Glossary
Short definitions for the terms used throughout this guide.
A device that generates and protects keys in hardware. The key never leaves it.
The common interface for talking to HSMs (Cryptoki). HSM Doctor works through it.
A slot is a bay; a token is the logical key/certificate store inside it.
A free, software PKCS#11 implementation. Ideal for trying things without a physical HSM.
The login secret for a token. HSM Doctor never logs or traces it.
A 0–100 summary of the token’s security posture. Higher is better.
HSM-001…
rules: extractable keys, weak RSA, expiring certificates, and more.
The difference between two points in time: added/removed objects, attribute flips, firmware/mechanism changes.
Post-quantum readiness: ML-KEM / ML-DSA / SLH-DSA support plus exposure analysis of existing keys.
A shim that safely records PKCS#11 calls, plus leak/error/performance analysis.
Central monitoring of many HSMs: one central server plus agents running on each host.
Appliance-level health (disk, HA, tamper): SoftHSM stable; Luna/nShield/CloudHSM experimental.
04 · Install
The fastest path is a pre-built binary. Building from source needs a C compiler
(the PKCS#11 wrapper uses dlopen/cgo).
# Easiest: download a pre-built binary from the releases page # github.com/kurtserdar/hsm-doctor/releases (Linux / macOS / Windows) # or build from source (needs a C compiler): $ git clone https://github.com/kurtserdar/hsm-doctor.git $ cd hsm-doctor $ make build # CLI only $ make ui build # CLI + embedded web interface (needs Node.js) # or directly with Go: $ go install github.com/kurtserdar/hsm-doctor/cmd/hsmdoctor@latest
05 · First run
SoftHSM lets you try everything without a physical HSM.
Grab the software PKCS#11 implementation from your package manager.
A DEMO-labeled token in a free slot; user PIN 123456.
Pass it via --pin-env so it never lands in shell history.
discover opens the module and lists slots/tokens — no login required.
scan: inventory + posture rules + health score.
$ sudo apt-get install softhsm2 $ softhsm2-util --init-token --free --label DEMO --so-pin 12345678 --pin 123456 $ export HSM_PIN=123456 $ hsmdoctor discover --module /usr/lib/softhsm/libsofthsm2.so $ hsmdoctor scan --module /usr/lib/softhsm/libsofthsm2.so --slot <SLOT-ID> --pin-env HSM_PIN
Every finding carries a rule id
(like HSM-001) and is grouped by severity:
CRITICAL · HIGH ·
MEDIUM · LOW.
06 · Next steps
The same binary does much more than scanning. Everything works with
--module + --slot or a PKCS#11 URI.
| Command | What it does |
|---|---|
| certs | Certificate expiry monitor; cron/CI-friendly exit codes. |
| test | Safe functional tests (keygen, sign/verify, AES-GCM) using ephemeral objects. |
| bench | Performance measurement under strictly bounded load (duration + op budget). |
| snapshot / diff | Record a token’s state, then compare later to see drift. |
| pqc | Post-quantum readiness: support matrix + exposure analysis of existing keys. |
| vendor | Appliance-level health (disk, HA, partitions, tamper) via vendor providers. |
| trace | Analyze Flight Recorder traces: leaks, ordering bugs, error codes, slow calls. |
| serve | Local web interface + REST API; scan history, automatic drift, Prometheus metrics. |
| server + agent | Fleet: a central server collects reports pushed by agents; monitor many HSMs in one dashboard. |
$ export HSM_PIN=123456 $ hsmdoctor serve --module /usr/lib/softhsm/libsofthsm2.so --pin-env HSM_PIN # → http://127.0.0.1:8080 (dashboard, inventory, certificates, PQC, fleet…)
Tip: Address a token the classic way (--module + --slot)
or with an RFC 7512 PKCS#11 URI:
--uri "pkcs11:token=PROD?module-path=/usr/lib/libpkcs11.so"
HSM Doctor — a vendor-neutral tool for HSM health, security posture and PKCS#11
diagnostics. For more depth, see the docs/ folder in the repository: rules,
vendor providers, tracing, deployment (server/agent, SSO, mTLS) and architecture.
This guide is a starting map; at any step you can ask “what is this, and why is it like that.”