# zombocoder/openhsm architecture

> Architecture diagram of the GitHub repository zombocoder/openhsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zombocoder/openhsm
- Repository: https://github.com/zombocoder/openhsm

## Overview

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: [`firmware/src/main.c`](https://github.com/zombocoder/openhsm/blob/main/firmware/src/main.c) (Firmware runtime), [`firmware/src/hsm/hsm_command.c`](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_command.c) (Command dispatcher), [`host/pkcs11/openhsm_transport.c`](https://github.com/zombocoder/openhsm/blob/main/host/pkcs11/openhsm_transport.c) (Host transport), [`firmware/src/usb/usbd_vendor.c`](https://github.com/zombocoder/openhsm/blob/main/firmware/src/usb/usbd_vendor.c) (USB vendor class)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and updates"]
  node_bootloader["Secure bootloader<br/>[main.c]"]
  node_image_header["Image format<br/>[image_header.h]"]
  node_flash_apply["RAM flash apply<br/>[flash_ram.c]"]
end

subgraph group_device["Device runtime"]
  node_app["Firmware runtime<br/>[main.c]"]
  node_usb_class["USB vendor class<br/>[usbd_vendor.c]"]
  node_protocol["Command protocol<br/>[hsm_proto.h]"]
end

subgraph group_services["HSM services"]
  node_session["Secure sessions<br/>[hsm_session.c]"]
  node_command["Command dispatcher<br/>[hsm_command.c]"]
  node_keystore[("Encrypted keystore<br/>[hsm_keystore.c]")]
  node_flash[("Flash storage<br/>[hsm_flash.c]")]
  node_crypto["Crypto operations"]
  node_rng["Hardware RNG<br/>[hsm_rng.c]"]
  node_audit[("Audit log<br/>[hsm_audit.c]")]
  node_tamper["Tamper response<br/>[hsm_tamper.c]"]
end

subgraph group_host["Host clients"]
  node_transport["Host transport"]
  node_pkcs11["PKCS&#35;11 provider<br/>[openhsm_pkcs11.c]"]
  node_daemon["USB TCP daemon<br/>[openhsm_daemon.c]"]
  node_cli["Maintenance CLI<br/>[main.c]"]
  node_ssh_agent["SSH agent<br/>[main.c]"]
  node_ping["Ping client<br/>[main.c]"]
end

node_operator(("HSM operator"))
node_ssh_user(("SSH user"))
node_openssh["OpenSSH"]
node_usb_host["USB host"]
node_pkcs11_apps(("PKCS&#35;11 applications"))

node_bootloader -->|"verifies image"| node_image_header
node_bootloader -->|"applies update"| node_flash_apply
node_app -->|"polls USB"| node_usb_class
node_usb_class -->|"dispatches commands"| node_command
node_usb_class -->|"frames messages"| node_protocol
node_session -->|"unwraps commands"| node_command
node_app -->|"initializes"| node_session
node_app -->|"initializes"| node_rng
node_app -->|"initializes"| node_crypto
node_app -->|"initializes"| node_keystore
node_app -->|"initializes"| node_audit
node_app -->|"services trips"| node_tamper
node_command -.->|"uses key objects"| node_keystore
node_command -.->|"requests operations"| node_crypto
node_keystore -.->|"persists objects"| node_flash
node_operator -->|"runs commands"| node_cli
node_operator -->|"uses provider"| node_pkcs11
node_operator -->|"smoke tests"| node_ping
node_cli -->|"sends commands"| node_transport
node_pkcs11 -->|"uses transport"| node_transport
node_ssh_user -->|"requests login"| node_openssh
node_openssh -->|"requests signing"| node_ssh_agent
node_ssh_agent -->|"forwards signing"| node_transport
node_transport -->|"communicates over USB"| node_usb_host
node_daemon -->|"bridges USB"| node_usb_host
node_cli -->|"supports remote access"| node_daemon
node_pkcs11_apps -->|"calls provider"| node_pkcs11

click node_bootloader "https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/main.c"
click node_image_header "https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/image_header.h"
click node_flash_apply "https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/flash_ram.c"
click node_app "https://github.com/zombocoder/openhsm/blob/main/firmware/src/main.c"
click node_usb_class "https://github.com/zombocoder/openhsm/blob/main/firmware/src/usb/usbd_vendor.c"
click node_protocol "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_proto.h"
click node_session "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_session.c"
click node_command "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_command.c"
click node_keystore "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_keystore.c"
click node_flash "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_flash.c"
click node_crypto "https://github.com/zombocoder/openhsm/tree/main/firmware/src/crypto"
click node_rng "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_rng.c"
click node_audit "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_audit.c"
click node_tamper "https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_tamper.c"
click node_transport "https://github.com/zombocoder/openhsm/blob/main/host/pkcs11/openhsm_transport.c"
click node_pkcs11 "https://github.com/zombocoder/openhsm/blob/main/host/pkcs11/openhsm_pkcs11.c"
click node_daemon "https://github.com/zombocoder/openhsm/blob/main/host/daemon/openhsm_daemon.c"
click node_cli "https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-cli/main.c"
click node_ssh_agent "https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-ssh-agent/main.c"
click node_ping "https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-ping/main.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootloader,node_image_header,node_flash_apply,node_ssh_user toneBlue
class node_app,node_usb_class,node_protocol toneAmber
class node_session,node_command,node_keystore,node_flash,node_crypto,node_rng,node_audit,node_tamper toneMint
class node_transport,node_pkcs11,node_daemon,node_cli,node_ssh_agent,node_ping toneRose
class node_operator,node_openssh,node_usb_host,node_pkcs11_apps toneIndigo
```

## Components

### Boot and updates

- [Secure bootloader](https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/main.c): `firmware/bootloader/main.c`
- [Image format](https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/image_header.h): `firmware/bootloader/image_header.h`
- [RAM flash apply](https://github.com/zombocoder/openhsm/blob/main/firmware/bootloader/flash_ram.c): `firmware/bootloader/flash_ram.c`

### Device runtime

- [Firmware runtime](https://github.com/zombocoder/openhsm/blob/main/firmware/src/main.c): `firmware/src/main.c`
- [USB vendor class](https://github.com/zombocoder/openhsm/blob/main/firmware/src/usb/usbd_vendor.c): `firmware/src/usb/usbd_vendor.c`
- [Command protocol](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_proto.h): `firmware/src/hsm/hsm_proto.h`

### HSM services

- [Secure sessions](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_session.c): `firmware/src/hsm/hsm_session.c`
- [Command dispatcher](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_command.c): `firmware/src/hsm/hsm_command.c`
- [Encrypted keystore](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_keystore.c): `firmware/src/hsm/hsm_keystore.c`
- [Flash storage](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_flash.c): `firmware/src/hsm/hsm_flash.c`
- [Crypto operations](https://github.com/zombocoder/openhsm/tree/main/firmware/src/crypto): `firmware/src/crypto`
- [Hardware RNG](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_rng.c): `firmware/src/hsm/hsm_rng.c`
- [Audit log](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_audit.c): `firmware/src/hsm/hsm_audit.c`
- [Tamper response](https://github.com/zombocoder/openhsm/blob/main/firmware/src/hsm/hsm_tamper.c): `firmware/src/hsm/hsm_tamper.c`

### Host clients

- [Host transport](https://github.com/zombocoder/openhsm/blob/main/host/pkcs11/openhsm_transport.c): `host/pkcs11/openhsm_transport.c`
- [PKCS#11 provider](https://github.com/zombocoder/openhsm/blob/main/host/pkcs11/openhsm_pkcs11.c): `host/pkcs11/openhsm_pkcs11.c`
- [USB TCP daemon](https://github.com/zombocoder/openhsm/blob/main/host/daemon/openhsm_daemon.c): `host/daemon/openhsm_daemon.c`
- [Maintenance CLI](https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-cli/main.c): `host/tools/openhsm-cli/main.c`
- [SSH agent](https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-ssh-agent/main.c): `host/tools/openhsm-ssh-agent/main.c`
- [Ping client](https://github.com/zombocoder/openhsm/blob/main/host/tools/openhsm-ping/main.c): `host/tools/openhsm-ping/main.c`

### Other components

- **HSM operator**
- **SSH user**
- **OpenSSH**
- **USB host**
- **PKCS#11 applications**

## Connections

- Secure bootloader → Image format: verifies image (evidence: `firmware/bootloader/main.c`)
- Secure bootloader → RAM flash apply: applies update (evidence: `firmware/bootloader/main.c`)
- Firmware runtime → USB vendor class: polls USB (evidence: `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 (evidence: `firmware/src/main.c`)
- Firmware runtime → Hardware RNG: initializes (evidence: `firmware/src/main.c`)
- Firmware runtime → Crypto operations: initializes (evidence: `firmware/src/main.c`)
- Firmware runtime → Encrypted keystore: initializes (evidence: `firmware/src/main.c`)
- Firmware runtime → Audit log: initializes (evidence: `firmware/src/main.c`)
- Firmware runtime → Tamper response: services trips (evidence: `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 (evidence: `README.md`)
- HSM operator → PKCS#11 provider: uses provider (evidence: `README.md`)
- HSM operator → Ping client: smoke tests (evidence: `README.md`)
- Maintenance CLI → Host transport: sends commands (evidence: `host/tools/openhsm-cli/main.c`)
- PKCS#11 provider → Host transport: uses transport (evidence: `host/pkcs11/openhsm_pkcs11.c`)
- SSH user → OpenSSH: requests login
- OpenSSH → SSH agent: requests signing (evidence: `host/tools/openhsm-ssh-agent/main.c`)
- SSH agent → Host transport: forwards signing (evidence: `host/tools/openhsm-ssh-agent/main.c`)
- Host transport → USB host: communicates over USB
- USB TCP daemon → USB host: bridges USB (evidence: `README.md`)
- Maintenance CLI → USB TCP daemon: supports remote access (evidence: `host/tools/openhsm-cli/main.c`)
- PKCS#11 applications → PKCS#11 provider: calls provider (evidence: `README.md`)
