GitHub - pike00/coldkey: Post-quantum age key generation and paper backup tool

Your age encryption keys are one disk failure away from total loss. If you use age or sops to encrypt secrets, losing your private key means losing access to everything it protects -- forever.

coldkey generates post-quantum (ML-KEM-768 + X25519) age keys and produces single-page printable HTML backups with QR codes. Print it, laminate it, store it in a fireproof safe. Your secrets survive even if every digital copy is gone.

Quick start

# Install — Homebrew (macOS/Linux)
brew install --cask pike00/tap/coldkey

# Or with Go
go install github.com/pike00/coldkey/cmd/coldkey@latest

# Generate a key and paper backup
coldkey generate -o ~/.config/sops/age/keys.txt

For defense-in-depth during key generation, see Hardened mode (Docker) below.

Commands

`coldkey` (no args) — Interactive mode

Presents a menu to generate a new key or create a backup from an existing one. Prompts for file paths and confirms before overwriting.

`coldkey generate`

Generate a new post-quantum age key pair.

coldkey generate [flags]
  -o PATH       Key file output path (default: stdout)
  -f            Overwrite existing file
  --no-backup   Skip HTML backup generation

`coldkey backup`

Create a printable HTML paper backup from an existing key file.

coldkey backup [flags] KEYFILE
  -o PATH    HTML output path (default: KEYFILE-backup.html)

`coldkey version`

Print the version string.

Security model

Layer	Measure
Memory	`mlockall(MCL_CURRENT\|MCL_FUTURE)` prevents key material from being swapped to disk
Files	Written with mode `0600`, fsynced; temporaries shredded (3-pass overwrite)
Process	Secrets passed via stdin/files only, never in process arguments
Container	`--network none --read-only --cap-drop ALL --security-opt no-new-privileges:true`
Image	`distroless/static:nonroot` — no shell, non-root UID 65534
Memory zeroing	Best-effort `secure.Zero()` on key buffers before GC (see Limitations)

Hardened mode (Docker)

An optional distroless Docker image runs key generation under network isolation, a read-only root filesystem, and dropped capabilities. Note that the resulting keys.txt is written to a host-mounted volume, so the container only hardens the generation step — the key at rest sits on the host like any other file.

docker pull ghcr.io/pike00/coldkey:latest

# Interactive — generate a key and paper backup
just docker-run

# Backup an existing key
just docker-backup ~/.config/sops/age/keys.txt

Output is written to ./output/. The just docker-run and just docker-backup recipes apply these flags automatically:

Flag	Purpose
`--network none`	No network access — key generation is purely local
`--read-only`	Immutable root filesystem
`--cap-drop ALL`	Drop all Linux capabilities
`--security-opt no-new-privileges:true`	Prevent privilege escalation
`--tmpfs /tmp:rw,noexec,nosuid,size=10m`	RAM-backed temp directory
`--cap-add IPC_LOCK`	(Optional) Enable `mlockall` for swap protection

QR code encoding

PQ age stores only the 32-byte seed (not the expanded ML-KEM-768 private key), so the full keys.txt is typically ~2,089 bytes — fitting in a single QR code (version 40, EC-L supports 2,953 bytes).

If a key file exceeds single-QR capacity, coldkey automatically splits it across multiple QR codes using a simple framing protocol:

COLDKEY:<part>/<total>:<data>

Recovery: scan all QR codes in order, strip the COLDKEY:N/M: prefix from each, concatenate, and verify the SHA-256 checksum.

Paper backup contents

The generated HTML document contains:

Title and metadata (date, hostname, user, source path)
Raw key text in monospace (for manual transcription)
QR code(s) with capacity annotation
SHA-256 checksum for verification
Step-by-step recovery instructions
Print button (hidden in print media)

Recovery procedure

Scan the QR code (or type the raw key text)
Save to ~/.config/sops/age/keys.txt
Verify: sha256sum keys.txt matches the printed checksum
Test: sops -d <any .sops file>

Building

just build       # Local binary
just docker      # Docker image (ghcr.io/pike00/coldkey)
just test        # Run tests
just ci          # Full CI: vet → test → build → docker

Limitations

Go GC and secure memory: Go's garbage collector may copy objects in memory, and Go strings are immutable, meaning key material held as a string (e.g. from identity.String()) cannot be reliably overwritten. secure.Zero() uses Go's built-in clear() to erase []byte buffers, but earlier string copies may persist in the heap until garbage collected. mlockall prevents any of this from being swapped to disk; together these provide defense-in-depth, not a cryptographic guarantee that key material is erased from RAM immediately.
mlockall requires CAP_IPC_LOCK: Add --cap-add IPC_LOCK to Docker run for full swap protection. Without it, coldkey prints a warning to stderr and continues.
QR scanning: Very dense QR codes (version 40) may be hard to scan from paper. The raw key text is always included as a manual fallback.

License

MIT