304 lines
11 KiB
Markdown
304 lines
11 KiB
Markdown
# Geth Keychain Sigchain Design
|
|
|
|
## Purpose
|
|
|
|
The geth keychain is a signed operation log for mesh identity state. It is the
|
|
source of truth for admin SSH keys, users, devices, nodes, agents, and endpoint
|
|
bindings. Peers do not trust a mutable keychain snapshot. They replay signed
|
|
operations and reduce the accepted log into the current keychain view.
|
|
|
|
This is intentionally similar to the `git-skm` pattern:
|
|
|
|
- `git-skm` treats a committed `allowed_signers` file as trusted only if every
|
|
commit that changed it can be verified from a prior trusted state.
|
|
- geth treats a keychain operation as trusted only if it is signed by an admin
|
|
key that was trusted in the previously accepted keychain view.
|
|
|
|
## Data Model
|
|
|
|
The reusable model lives in the `geth-keychain` crate. The daemon stores it in
|
|
SQLite and syncs it over Iroh, but the crate does not depend on SQLite, Iroh, or
|
|
the geth daemon. Other projects can publish the same keychain as a static
|
|
sigchain file, append it to object storage, embed it in a document, or transport
|
|
it by any other mechanism.
|
|
|
|
The durable log is `KeychainOp[]` plus `KeychainOpSignature[]`. Each operation
|
|
has a deterministic canonical signing payload under the
|
|
`geth.keychain.v1@geth.local` namespace.
|
|
|
|
The namespace is part of a `KeychainProfile`. geth uses:
|
|
|
|
- `geth.keychain.v1@geth.local`
|
|
- `geth.node-enrollment-request.v1@geth.local`
|
|
- default admin principal `admin`
|
|
|
|
Other applications should create their own profile with explicit namespaces or
|
|
`KeychainProfile::for_application("<app>", "<domain>")`. For example,
|
|
`for_application("acme-notes", "example.com")` produces
|
|
`acme-notes.keychain.v1@example.com`. This prevents signatures from one
|
|
application's keychain from being replayed into another application's
|
|
keychain.
|
|
|
|
Important operation kinds:
|
|
|
|
- `KeychainInit`
|
|
- `AdminKeyAdd`
|
|
- `AdminKeyRevoke`
|
|
- `UserAdd`, `UserRename`, `UserRevoke`
|
|
- `DeviceAdd`, `DeviceRevoke`
|
|
- `DeviceKeyAdd`, `DeviceKeyRevoke`
|
|
- `NodeAdd`, `NodeRename`, `NodeRevoke`
|
|
- `NodeEndpointAdd`, `NodeEndpointRevoke`
|
|
- `AgentBind`
|
|
|
|
`AdminKeyAdd` records the admin key fingerprint and, for new operations, the
|
|
OpenSSH public key material, optional principal, and optional validity metadata.
|
|
The public key is part of the signed operation so the key registry can be
|
|
reconstructed from the sigchain itself. Older local data may only have the
|
|
fingerprint; geth can use stored signature public-key material as a fallback
|
|
when exporting the current allowed signers view.
|
|
|
|
## Signature Rules
|
|
|
|
Each signed operation has a `KeychainOpSignature`:
|
|
|
|
- `op_id`
|
|
- signer key fingerprint
|
|
- signer OpenSSH public key
|
|
- namespace
|
|
- OpenSSH signature bytes
|
|
- creation time
|
|
|
|
Signatures are produced with:
|
|
|
|
```sh
|
|
ssh-keygen -Y sign -n geth.keychain.v1@geth.local -f <signing-key> <payload>
|
|
```
|
|
|
|
`<signing-key>` can be:
|
|
|
|
- a local private OpenSSH key file,
|
|
- a FIDO/YubiKey OpenSSH security-key stub,
|
|
- a public key whose private half is already loaded in `ssh-agent`, or
|
|
- a public key backed by a PKCS#11 token loaded into `ssh-agent` with
|
|
`ssh-add -s <provider>`.
|
|
|
|
Encrypted private key files should normally be unlocked into `ssh-agent` before
|
|
running geth control commands. The daemon never stores private keys or
|
|
passphrases. Direct PKCS#11 signing is intentionally not a first-class geth
|
|
backend because portable `ssh-keygen -Y sign` flows do not expose the same
|
|
provider flag as OpenSSH certificate signing.
|
|
|
|
Verification uses:
|
|
|
|
```sh
|
|
ssh-keygen -Y verify \
|
|
-f <allowed-signers> \
|
|
-I <signer-principal> \
|
|
-n geth.keychain.v1@geth.local \
|
|
-s <signature>
|
|
```
|
|
|
|
The signed payload is canonical binary encoding, not JSON.
|
|
|
|
## Verification Algorithm
|
|
|
|
For a candidate log ordered by `(created_at_ms, op_id)`:
|
|
|
|
1. Start from a local trust anchor. In the bootstrap implementation this is a
|
|
locally initialized `KeychainInit` plus an admin key added through
|
|
`geth init --admin-key ... --signing-key ...` or `geth keychain init
|
|
--admin-key ...`.
|
|
2. Maintain an accepted operation prefix and reduce it into the current
|
|
keychain view.
|
|
3. For each next operation, collect its signatures.
|
|
4. Accept the operation only if at least one signature:
|
|
- is from a key fingerprint present in the previous accepted view,
|
|
- carries public key material that hashes to that fingerprint,
|
|
- verifies over the canonical operation payload with OpenSSH, and
|
|
- uses the keychain namespace.
|
|
5. After accepting the operation, append it to the accepted prefix and reduce
|
|
again. This lets a valid `AdminKeyAdd` authorize later operations, and a
|
|
valid `AdminKeyRevoke` stop later authorization by that key.
|
|
6. Reject unsigned, invalidly signed, conflicting, or out-of-authority
|
|
operations.
|
|
|
|
This mirrors `git-skm`'s "verify from the previously trusted
|
|
allowed_signers" model, but the transport and storage are geth/Iroh/SQLite
|
|
instead of Git commits.
|
|
|
|
The `geth-keychain` crate exposes this as a transport-neutral verifier. Callers
|
|
provide:
|
|
|
|
- ordered or unordered `KeychainOp[]`
|
|
- `KeychainOpSignature[]`
|
|
- a `KeychainProfile`
|
|
- a `KeychainSignatureVerifier`
|
|
|
|
The verifier is responsible for the cryptographic backend, such as
|
|
`ssh-keygen -Y verify`, WebCrypto, an HSM, a service-side verifier, or a test
|
|
verifier. The crate owns the replay order, bootstrap rule, profile namespace
|
|
check, previous-view authorization rule, `allowed_signers` projection, and
|
|
reduced keychain view.
|
|
|
|
Minimal reusable Rust shape:
|
|
|
|
```rust
|
|
let profile = geth_keychain::KeychainProfile::for_application(
|
|
"acme-notes",
|
|
"example.com",
|
|
)?;
|
|
let entries = geth_keychain::decode_sigchain_jsonl(sigchain_text)?;
|
|
let (ops, signatures) = geth_keychain::flatten_sigchain_entries(&entries);
|
|
let report = geth_keychain::verify_sigchain_with_profile(
|
|
&ops,
|
|
&signatures,
|
|
&profile,
|
|
&my_verifier,
|
|
);
|
|
```
|
|
|
|
## Static Sigchain File
|
|
|
|
For static hosting and range-friendly distribution, `geth-keychain` defines a
|
|
JSONL sigchain representation:
|
|
|
|
```json
|
|
{"op":{...},"signatures":[...]}
|
|
{"op":{...},"signatures":[...]}
|
|
```
|
|
|
|
Each line is a complete `KeychainSigchainEntry`. This keeps the file appendable
|
|
and cacheable:
|
|
|
|
- A publisher can append new entries to the end of the file.
|
|
- HTTP clients can use `ETag`, `Last-Modified`, and byte range requests to fetch
|
|
only new bytes.
|
|
- A client can decode complete trailing lines, ignore a partial final line until
|
|
the next fetch, and replay verification from its last accepted checkpoint.
|
|
- The canonical signed payload remains the `KeychainOp`; JSONL is only the
|
|
publication container.
|
|
|
|
The crate provides helpers to encode/decode JSONL and flatten entries back into
|
|
`KeychainOp[]` plus `KeychainOpSignature[]`.
|
|
|
|
geth writes checkpoint records with `geth keychain publish-bundle`. The
|
|
checkpoint contains the accepted head, operation/signature counts, byte length,
|
|
BLAKE3 hashes for the sigchain and allowed signers projection, a reduced-view
|
|
hash, generation time, and the discovery base URL. The checkpoint is signed as
|
|
`geth.sigchain.checkpoint.json.sig` so static clients can detect rollback or
|
|
truncation before importing updates. `geth keychain fetch --import` stores the
|
|
last accepted checkpoint for a source URL and rejects older checkpoints from the
|
|
same source. The fetch URL is a retrieval location and may be a `file://` mirror
|
|
for testing; the checkpoint's signed `base_url` remains the advertised static
|
|
publication location. Use `geth keychain verify-checkpoint --base-url <url>` when
|
|
a consumer needs to pin that advertised value explicitly.
|
|
|
|
## Commands
|
|
|
|
Owner bootstrap:
|
|
|
|
```sh
|
|
geth init \
|
|
--admin-key ~/.ssh/id_ed25519_sk.pub \
|
|
--signing-key ~/.ssh/id_ed25519_sk \
|
|
--node-name laptop
|
|
```
|
|
|
|
Add a new admin key:
|
|
|
|
```sh
|
|
geth keychain admin-add \
|
|
--admin-key ~/.ssh/new_admin.pub \
|
|
--signing-key ~/.ssh/current_admin_sk \
|
|
--principal admin
|
|
```
|
|
|
|
Revoke an admin key:
|
|
|
|
```sh
|
|
geth keychain admin-revoke <key-fingerprint> \
|
|
--signing-key ~/.ssh/current_admin_sk
|
|
```
|
|
|
|
Export the reduced active admin key registry in OpenSSH `allowed_signers`
|
|
format:
|
|
|
|
```sh
|
|
geth keychain allowed-signers > allowed_signers
|
|
geth keychain allowed-signers --out allowed_signers
|
|
geth keychain sign-file \
|
|
--in authorized_keys \
|
|
--out authorized_keys.sig \
|
|
--signing-key ~/.ssh/id_ed25519_sk
|
|
geth keychain verify-file \
|
|
--in authorized_keys \
|
|
--signature authorized_keys.sig
|
|
geth keychain sigchain --out geth.sigchain.jsonl
|
|
geth keychain publish-bundle \
|
|
--out public/.well-known/sshsigchain \
|
|
--signing-key ~/.ssh/id_ed25519_sk \
|
|
--snapshot authorized_keys=authorized_keys
|
|
geth keychain verify-checkpoint \
|
|
--checkpoint geth.sigchain.checkpoint.json \
|
|
--signature geth.sigchain.checkpoint.json.sig \
|
|
--sigchain geth.sigchain.jsonl \
|
|
--allowed-signers allowed_signers
|
|
geth keychain fetch --url https://example.com/.well-known/sshsigchain/ --import
|
|
geth keychain verify-sigchain --in geth.sigchain.jsonl
|
|
geth keychain import-sigchain --in geth.sigchain.jsonl
|
|
geth keychain explain <op-id>
|
|
geth keychain explain-signer <key-id>
|
|
```
|
|
|
|
The default static discovery base URL used by `publish-bundle` is
|
|
`https://example.com/.well-known/sshsigchain/`. The keychain does not manage
|
|
`authorized_keys` policy. It signs an arbitrary
|
|
snapshot you provide, which lets other projects keep their own SSH login policy
|
|
while rooting snapshot approval in the keychain. By default `sign-file` uses the
|
|
personal identity namespace `geth.authorized-keys.v1@eric.wendland.dev`; pass
|
|
`--namespace` for project-specific snapshots. The signer must be an active key
|
|
in the current `allowed_signers` projection, so website consumers can fetch the
|
|
snapshot, signature, and allowed signers and verify:
|
|
|
|
```sh
|
|
ssh-keygen -Y verify \
|
|
-f allowed_signers \
|
|
-I admin \
|
|
-n geth.authorized-keys.v1@eric.wendland.dev \
|
|
-s authorized_keys.sig < authorized_keys
|
|
```
|
|
|
|
Replay and verify the local sigchain:
|
|
|
|
```sh
|
|
geth keychain verify
|
|
```
|
|
|
|
## Differences From Git-SKM
|
|
|
|
`git-skm` uses Git commit history as the append-only log and a trusted commit
|
|
hash as the checkpoint. geth uses `KeychainOp[]` as the append-only log and the
|
|
locally initialized owner/admin key as the bootstrap trust anchor.
|
|
|
|
The current geth prototype does not yet provide:
|
|
|
|
- transparency-log style append proofs
|
|
- anti-rollback protection beyond local state, HTTP cache validators, and sync
|
|
conflict checks
|
|
- delegated admin scopes or threshold admin signatures
|
|
- strong compromise-recovery semantics
|
|
|
|
Those are future hardening items. The current prototype is intended to make the
|
|
key registry self-describing, replayable, and testable.
|
|
|
|
## Security Invariants
|
|
|
|
- The admin SSH private key is never copied into geth state.
|
|
- Admin key changes are keychain operations, not mutable ACL edits.
|
|
- Public key material needed to reconstruct active admin signers is stored in
|
|
the signed operation log.
|
|
- Import from peers accepts only operations signed by currently trusted admin
|
|
keys.
|
|
- A discovered peer card or Iroh EndpointID never grants keychain authority.
|
|
- Bearer secrets do not grant keychain mutation rights.
|