Skip to content

keys

keys <mint | generate | wkd> [flags]

Constructor: signingcli.NewCmdKeys(log Logger) *cobra.Command — the parent group with all three subcommands attached. Each subcommand also has its own exported constructor (NewCmdKeysMint, NewCmdKeysGenerate, NewCmdKeysWKD) if you want to attach them individually.

keys groups the cryptographic operations a tool author runs while setting up release-binary signing:

Subcommand Purpose
mint Wrap an existing signer (KMS or local PEM) in OpenPGP framing and emit the armored public half.
generate Generate a fresh keypair locally (Ed25519 or RSA) and emit both halves.
wkd Generate a Web Key Directory tree from one or more public keys.

Key output files use 0644 for public (armored) halves — they are meant to be distributed — and 0600 for private halves. Writes use O_EXCL and refuse to clobber an existing file unless --force is passed, so a private key is never silently overwritten.

keys mint

keys mint --backend <name> --key-id <id> --name <name> --email <email> [flags]

Constructor: signingcli.NewCmdKeysMint(log Logger) *cobra.Command.

Wrap an existing signer — an HSM/KMS-held key or an on-disk PEM private key — in OpenPGP framing and write the armored public half to a file. The private half never touches this tool; every signing operation flows through the backend.

Flags

Flag Required Default Description
--backend yes — Signing backend name (compiled-in; --help lists them).
--key-id yes — Backend-specific key identifier. aws-kms: KMS key ID/ARN/alias. local: PEM file path.
--name yes — OpenPGP user-id real name (e.g. "GTB Release").
--email yes — OpenPGP user-id email (e.g. release@example.com).
--output no release.asc Output file path for the armored public key. Stdout (-) is not supported.
--created no now Creation time (RFC3339). Pin only when re-minting an existing key — a different creation time yields a different fingerprint.
--force no false Overwrite an existing output file.

Backend-specific flags (e.g. --kms-region) are added by the backend when compiled in.

Output

Writes the armored public key and logs an INFO line with backend, key_id, output, creation_time, and the fingerprint. Publish the resulting .asc via keys wkd and/or embed it in your tool's trust set; pass it to sign --public-key.

keys generate

keys generate --algorithm <ed25519|rsa> --name <name> --email <email> [flags]

Constructor: signingcli.NewCmdKeysGenerate(log Logger) *cobra.Command.

Generate a fresh keypair entirely in-process (no shell-out, no backend) and write both halves to disk. Used during onboarding for a rotation-authority key and for the tutorial / local signing key.

The on-disk format of the private half depends on the algorithm:

  • --algorithm ed25519 — public half: armored OpenPGP; private half: armored OpenPGP secret-key block (the format gpg --export-secret-keys uses). Intended for rotation-authority keys.
  • --algorithm rsa — public half: armored OpenPGP; private half: PKCS#1 PEM. Pairs with keys mint --backend local for the tutorial path.

Encrypted on-disk private halves are not produced in v0.1. Use filesystem-level encryption (LUKS, FileVault, age) and move the private half to offline storage immediately.

Flags

Flag Required Default Description
--algorithm yes — ed25519 or rsa.
--rsa-bits no 4096 RSA modulus size; one of 2048, 3072, 4096. Ignored for ed25519.
--name yes — OpenPGP user-id real name.
--email yes — OpenPGP user-id email.
--output no <algorithm>.asc Output path for the armored public key.
--private-output no derived from --output Private-half path: .asc → .priv.asc for Ed25519, .asc → .pem for RSA. Must differ from --output.
--created no now Creation time (RFC3339). Pin only when re-deriving an existing key.
--force no false Overwrite existing output files.

This subcommand takes no backend and no backend-specific flags.

Output

Writes both halves, logs an INFO line with algorithm, public_output, private_output, creation_time, and fingerprint, then a WARN line reminding you to move the private half to offline storage.

keys wkd

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

Constructor: signingcli.NewCmdKeysWKD(log Logger) *cobra.Command.

Read one or more armored OpenPGP public keys, group them by email, and write a Web Key Directory tree (per draft-koch §3.1) under --output, ready to upload to a static host.

For each requested email, keys whose UIDs contain that email are concatenated — in lexicographic fingerprint order for reproducible output — into a single hu/<z-base-32-hash> bucket. A key with multiple matching UIDs lands under every matching email's bucket (standard WKD behaviour).

Arguments

Argument Required Description
<public-key.asc>… yes (one or more) Armored OpenPGP public-key files. A file holding a key ring contributes each entity individually.

Flags

Flag Required Default Description
--domain yes — DNS domain serving the WKD endpoint (e.g. phpboyscout.uk). Appears in the URL path for the advanced method.
--email no all emails found Email address(es) to publish under. Repeatable. If omitted, every distinct email across the input keys is published.
--output no ./wkd-staging Output directory; receives a .well-known/openpgpkey/… tree.
--method no advanced URL layout: advanced (served from openpgpkey.<domain>) or direct (served from <domain> itself).
--submission-address no (none) Address to write to the WKD submission-address file. Empty means do not emit the file; auto uses the first --email; any other value is used verbatim.

Output

Writes the tree and logs a WKD bucket INFO line per email (with its hash and key count), a wrote line per file, and a final WKD tree complete summary. Serve the .well-known/openpgpkey/… tree over HTTPS.

See also