How zombocoder/openhsm works
OpenHSM is a USB-connected HSM: host clients issue protocol commands, firmware transports and dispatches them, and protected device services perform cryptographic operations and manage persistent keys and audit state. The bootloader verifies signed firmware and applies staged updates. Host capabilities include PKCS#11, a USB-to-TCP daemon, a maintenance CLI, and an SSH agent. Some central implementation files were not sampled; uncertain service-call links are omitted or shown as unverified.
Main entry points: main.c Firmware runtime · hsm_command.c Command dispatcher · openhsm_transport.c Host transport · usbd_vendor.c USB vendor class
Components 25
Boot and updates
- Secure bootloader
firmware/bootloader/main.c - Image format
firmware/bootloader/image_header.h - RAM flash apply
firmware/bootloader/flash_ram.c
Device runtime
- Firmware runtime
firmware/src/main.c - USB vendor class
firmware/src/usb/usbd_vendor.c - Command protocol
firmware/src/hsm/hsm_proto.h
HSM services
- Secure sessions
firmware/src/hsm/hsm_session.c - Command dispatcher
firmware/src/hsm/hsm_command.c - Encrypted keystore
firmware/src/hsm/hsm_keystore.c - Flash storage
firmware/src/hsm/hsm_flash.c - Crypto operations
firmware/src/crypto - Hardware RNG
firmware/src/hsm/hsm_rng.c - Audit log
firmware/src/hsm/hsm_audit.c - Tamper response
firmware/src/hsm/hsm_tamper.c
Host clients
- Host transport
host/pkcs11/openhsm_transport.c - PKCS#11 provider
host/pkcs11/openhsm_pkcs11.c - USB TCP daemon
host/daemon/openhsm_daemon.c - Maintenance CLI
host/tools/openhsm-cli/main.c - SSH agent
host/tools/openhsm-ssh-agent/main.c - Ping client
host/tools/openhsm-ping/main.c
Other components
- HSM operator
- SSH user
- OpenSSH
- USB host
- PKCS#11 applications
Connections 27
- Secure bootloader → Image format: verifies image
firmware/bootloader/main.c - Secure bootloader → RAM flash apply: applies update
firmware/bootloader/main.c - Firmware runtime → USB vendor class: polls USB
firmware/src/main.c - USB vendor class → Command dispatcher: dispatches commands
- USB vendor class → Command protocol: frames messages
- Secure sessions → Command dispatcher: unwraps commands
- Firmware runtime → Secure sessions: initializes
firmware/src/main.c - Firmware runtime → Hardware RNG: initializes
firmware/src/main.c - Firmware runtime → Crypto operations: initializes
firmware/src/main.c - Firmware runtime → Encrypted keystore: initializes
firmware/src/main.c - Firmware runtime → Audit log: initializes
firmware/src/main.c - Firmware runtime → Tamper response: services trips
firmware/src/main.c - Command dispatcher → Encrypted keystore: uses key objects
- Command dispatcher → Crypto operations: requests operations
- Encrypted keystore → Flash storage: persists objects
- HSM operator → Maintenance CLI: runs commands
README.md - HSM operator → PKCS#11 provider: uses provider
README.md - HSM operator → Ping client: smoke tests
README.md - Maintenance CLI → Host transport: sends commands
host/tools/openhsm-cli/main.c - PKCS#11 provider → Host transport: uses transport
host/pkcs11/openhsm_pkcs11.c - SSH user → OpenSSH: requests login
- OpenSSH → SSH agent: requests signing
host/tools/openhsm-ssh-agent/main.c - SSH agent → Host transport: forwards signing
host/tools/openhsm-ssh-agent/main.c - Host transport → USB host: communicates over USB
- USB TCP daemon → USB host: bridges USB
README.md - Maintenance CLI → USB TCP daemon: supports remote access
host/tools/openhsm-cli/main.c - PKCS#11 applications → PKCS#11 provider: calls provider
README.md