pike00/coldkey

Source: https://github.com/pike00/coldkey

coldkey

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.

Install

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

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

Quick start

Docker (recommended)

# Pull the image
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

All just docker-* commands include security hardening flags (network isolation, read-only filesystem, dropped capabilities). Output is written to ./output/.

From source

go install github.com/pike00/coldkey/cmd/coldkey@latest
coldkey generate -o ~/.config/sops/age/keys.txt

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

Docker flags explained

The just docker-run and just docker-backup commands apply these flags automatically:

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

1. Scan the QR code (or type the raw key text)
2. Save to ~/.config/sops/age/keys.txt
3. Verify: sha256sum keys.txt matches the printed checksum
4. 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