Overview

Docs path: Start / Overview

openKMS is a deny-by-default signing API for Solana and Cosmos, backed by a YubiHSM2 you actually own. Autonomous strategies (the kind of trading agents Openclaw is built around) request signatures over plain HTTP. Per-key policy stops the bad trades before the hardware ever touches them.

Private keys never leave the YubiHSM2. The runtime auth key the service binds as can sign, but cannot export or mutate keys. There is no plaintext egress.

The 0.1.0-rc.1 release is a stable prototype snapshot: small, fail-closed, designed for a homelab Raspberry Pi that signs for a strategy.

Five gates between the strategy and your keys

Every signing request crosses these layers in order. Each is fail-closed and emits to the audit log.

Strategy --> Auth --> Decode --> Policy --> Replay --> YubiHSM2
                                                           |
                                                       Signature

1. Auth — bearer token in signer_token_file; admin token is separate.
2. Decode — chain-specific (Solana VersionedMessage, Cosmos SignDoc).
3. Policy — rate limits, per-tx and rolling daily caps, program / message / recipient allowlists, kill switch.
4. Replay — cache for deterministic signatures over a configured window.
5. YubiHSM2 — sign inside hardware. Append-only audit log + Prometheus counters update on accept and on every denial.

Trust split

• Host plane runs the HTTP server, policy, replay cache, audit log, and metrics on a hardened systemd unit.
• HSM plane holds signing keys, the wrap key, and the runtime auth key inside the YubiHSM2.

A privileged attacker on the host can ask the connector for signatures within the policy. Policy is the blast-radius bound; the HSM is the key-egress bound.

Documentation map

• Quick Start — local build, ceremony, key provisioning, backup, and service start.
• Configuration — every block in the canonical TOML.
• Policy Authoring — how the policy engine evaluates a signing request.
• Openclaw Integration — how a trading agent should call openKMS as a signing boundary.
• Security Model — what the HSM does and does not protect.
• Deployment — systemd, host hardening, reverse proxy.
• Backup and Restore — wrap-encrypted recovery from the ceremony mnemonic.
• Testing and Automation — local commands and CI lanes.
• HTTP API — public routes and link to the generated OpenAPI.
• Architecture — module layout and request flow.

Source of truth

Documentation describes these artifacts; it is never authoritative on its own.

• HTTP API: openapi/openkms.v1.json (CI rebuilds and diffs it from src/openapi.rs).
• Config: examples/config.toml (parsed and .validate()-checked in tests/docs_drift.rs).
• Agent guidance: .agents/skills/openkms/SKILL.md.
• Contributor / CI runbooks: docs/remote-e2e.md, docs/broadcast-e2e.md, deploy/README.md.