keys command¶

sigillum keys manages the keys used for release signing — OpenPGP for checksum manifests, minisign for the artefacts themselves.

sigillum keys <subcommand> [flags]

keys on its own does nothing but print help.

Subcommands at a glance¶

The two families serve different verifiers. OpenPGP keys are published over WKD and verify checksum manifests; minisign keys are published as plain files and verify release artefacts for cargo-binstall and rtb-update, neither of which parses OpenPGP.

File permissions every subcommand uses¶

Output files are created with O_EXCL, so the "does it exist?" check and the create are one atomic syscall — there is no window between them. --force switches to truncate-and-rewrite.

keys generate¶

Generate a fresh keypair entirely in-process — no shell-out, no gpg — and write both halves.

Which private-key format do I get?¶

This is the flag most likely to catch you out, because the default for Ed25519 is not readable by the local signing backend.

Pointing --backend local --key-id at an Ed25519 .priv.asc fails with no PEM block found in file. Generate with --private-format pem when the key is going to sign anything locally; that is what makes minisign artefact signing possible without an HSM.

--private-format openpgp with --algorithm rsa fails with --private-format openpgp is not supported for --algorithm rsa; RSA private halves are written as PKCS#1 PEM. An unknown value fails with unknown --private-format "x".

Failure modes¶

The private half is encoded and written before the public half, under the no-clobber guard, so a failure cannot leave a lone public key behind whose private half was never saved.

What it logs¶

INFO Generated OpenPGP keypair algorithm=rsa public_output=release.asc private_output=release.pem creation_time=… fingerprint=9458EAFE…
WARN Move the private-half file to offline storage now. private_output=release.pem

keys mint¶

Wrap a signer that already exists — a KMS key or a local PEM — in OpenPGP framing and write the armored public half. It does not generate a private key; the private half never leaves its backend.

What minting actually does¶

1. Resolve the signer through the backend — for KMS, one GetPublicKey call.
2. Build a v4 OpenPGP entity around the public half with your user ID, and produce the positive-cert self-signature. That self-signature is one kms:Sign call — the only time the private half is consulted.
3. Armor the result to --output and log the fingerprint at INFO.

The creation time folds into the fingerprint, which is why --created exists: same key material, same user ID and same creation time re-derives the same fingerprint. Different creation times give different fingerprints for the same underlying key.

Failure modes¶

Stdout is refused because the armored bytes would interleave with log lines.

If the armored key is written but cannot be parsed back, mint logs WARN Wrote armored key but could not parse it back to read fingerprint and still succeeds — the file exists and gpg --show-key can recover the fingerprint.

keys wkd¶

Build a Web Key Directory tree from one or more armored public-key files, ready to upload to a static host.

sigillum keys wkd <public-key.asc> [<public-key.asc>...] [flags]

At least one key file is required.

--email is not required. Only --domain is. With --email omitted, every distinct email across the input keys gets its own bucket — which is usually what you want and is why the flag has no MarkFlagRequired.

What the tree looks like¶

wkd-staging/
└── .well-known/
    └── openpgpkey/
        └── phpboyscout.uk/
            ├── policy                (empty file, required by the spec)
            ├── submission-address    (only when --submission-address is set)
            └── hu/<z-base-32-hash>   (binary concatenated keys)

Keys matching an email are concatenated in lexicographic fingerprint order, so the tree is reproducible across deploys. A key with several matching UIDs lands in every matching bucket — standard WKD behaviour. A multi-entity key ring file is split per entity, so no entity is cross-published into another's bucket.

Failure modes¶

keys minisign¶

Resolve an Ed25519 signing key through a backend and emit its minisign public key — the base64 string release consumers pin. Nothing secret is involved: for a KMS key this is one GetPublicKey call.

With no --output the bare key goes to stdout and the log line to stderr, so sigillum keys minisign … > key.b64 produces a usable file. This is deliberate and regression-tested: the value once went to stderr, which looked correct on a terminal and produced an empty file when redirected.

The key identifier derives from the public key itself, so re-running against the same key produces the same output on any machine. Re-derive rather than store.

Where the value goes¶

Failure modes¶

keys publish¶

Stage a minisign public key into a static keys site: write it to a stable path and record it in a machine-readable keys.json.

sigillum keys publish <public-key.pub> [flags]

Exactly one .pub file, produced by keys minisign --output.

--project must match ^[a-z0-9][a-z0-9._-]{0,63}$ — lowercase alphanumeric with dots, dashes or underscores. That constraint exists because the value becomes a path segment: rejecting separators and traversal here is what stops any input writing outside the site root.

It reads a file rather than a backend on purpose. Minting a key touches your KMS; publishing it touches the trust anchor. Keeping them apart means the publish step needs no cloud credentials, so a compromised runner cannot rewrite what the world believes your keys are.

What it writes¶

keys-staging/
├── keys.json
└── minisign/
    └── mytool/
        └── v1.pub

keys.json entries carry id, project, generation, algorithm (minisign-ED), purpose, status, valid_from, pubkey and path, sorted by project then generation so the file does not churn between runs. The pubkey field is the exact string cargo-binstall pins, so the two can be compared directly.

The manifest is an audit and discovery record, never a trust input. Consumers verify against a key compiled into them or pinned in crate metadata; keys.json exists so a pinned value can be checked against what was published.

The untrusted comment in the published .pub is rewritten to a standard form, so a --comment passed to keys minisign does not survive publication. Only the key material is compared.

Why publishing is add-only¶

Consumers pin these keys. Changing one under them is exactly what must never happen. Retired and revoked keys stay published — a signature made under a key must remain checkable long after its private half is destroyed — so rotation is publishing a new generation, never removing an old one.

Failure modes¶

Related¶

• sign command reference
• Generate or mint a signing key
• Publish a WKD tree
• Sign an artefact for Rust consumers
• What sigillum does not do