Coldkey is a command-line tool for generating post-quantum age encryption keys and creating paper backups. It addresses the problem of losing age private keys—essential for decrypting files encrypted with age or sops—by producing printable HTML documents with QR codes.

Installation

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

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

Quick Start with 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 none, --read-only, --cap-drop ALL, --security-opt no-new-privileges:true. Output is written to ./output/.

Commands

• Interactive mode (coldkey): Menu to generate a new key or create a backup from an existing one.
• Generate (coldkey generate [-o PATH] [-f] [--no-backup]): Generate a new post-quantum age key pair (ML-KEM-768 + X25519). Default output to stdout unless -o provided.
• Backup (coldkey backup [flags] KEYFILE): Create a printable HTML paper backup from an existing key file.
• Version (coldkey version): Print the version string.

Security Model

• Memory: Uses mlockall(MCL_CURRENT|MCL_FUTURE) to prevent swapping key material 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: Distroless/static:nonroot image with no shell, non-root UID 65534.
• Memory zeroing: Best-effort secure.Zero() on key buffers before GC.

QR Code Encoding

Post-quantum age keys store only a 32-byte seed, so keys.txt is typically ~2,089 bytes—fitting in a single QR code (version 40, EC-L supports 2,953 bytes). For larger files, coldkey splits across multiple QR codes using a framing protocol: COLDKEY:<part>/<total>:<data>. Recovery: scan all QR codes in order, strip prefixes, concatenate, and verify SHA-256 checksum.

Paper Backup Contents

The generated HTML includes: title/metadata (date, hostname, user, source path), raw key text in monospace, QR code(s) with capacity annotation, SHA-256 checksum, and step-by-step recovery instructions.

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>

Limitations

Go's garbage collector may copy objects in memory, and Go strings are immutable—key material held as a string (e.g. from identity.String()) cannot be securely zeroed. Coldkey performs best-effort zeroing on byte buffers.