pike00/coldkey

来源：https://github.com/pike00/coldkey

coldkey

CI（https://github.com/pike00/coldkey/actions/workflows/ci.yml） | 发布版（https://github.com/pike00/coldkey/releases/latest） | Go（https://go.dev/） | 许可证：MIT

你的年龄加密密钥与磁盘故障之间仅一步之遥——一旦丢失，便永久无法恢复。

如果你使用 age（https://age-encryption.org/）或 sops（https://github.com/getsops/sops）加密机密，丢失私钥意味着永久失去对其保护的所有内容的访问权限。coldkey 生成后量子（ML-KEM-768 + X25519）（https://words.filippo.io/post-quantum-age/）age 密钥，并生成包含二维码的单页可打印 HTML 备份。打印、覆膜、存放在防火保险箱中。即使所有数字副本消失，你的机密依然存续。

演示（https://asciinema.org/a/MitZvLXcwYdBXkeF）

打印输出图片

安装

# Homebrew（macOS/Linux）
brew install --cask pike00/tap/coldkey

# 或用 Go
go install github.com/pike00/coldkey/cmd/coldkey@latest

快速入门

Docker（推荐）

# 拉取镜像
docker pull ghcr.io/pike00/coldkey:latest

# 交互模式——生成密钥和纸质备份
just docker-run

# 备份现有密钥
just docker-backup ~/.config/sops/age/keys.txt

所有 just docker-* 命令都包含安全加固标志（网络隔离、只读文件系统、去掉 capabilities）。输出写入 ./output/。

从源码运行

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

命令

coldkey（无参数）——交互模式

提供菜单，用于生成新密钥或从现有密钥创建备份。提示文件路径，并在覆盖前确认。

coldkey generate

生成新后量子 age 密钥对。

coldkey generate [flags]
  -o PATH    密钥文件输出路径（默认：stdout）
  -f         覆盖现有文件
  --no-backup    跳过 HTML 备份生成

coldkey backup

从现有密钥文件创建可打印的 HTML 纸质备份。

coldkey backup [flags] KEYFILE
  -o PATH    HTML 输出路径（默认：KEYFILE-backup.html）

coldkey version

打印版本字符串。

安全模型

Docker 标志说明

just docker-run 和 just docker-backup 命令自动应用以下标志：

二维码编码

PQ age 仅存储 32 字节种子（而非展开后的 ML-KEM-768 私钥），因此完整的 keys.txt 通常约为 2,089 字节——可放入单个二维码（版本 40，EC-L 支持 2,953 字节）。如果密钥文件超出单二维码容量，coldkey 使用简单的帧协议自动将其分割到多个二维码中：

COLDKEY:<序号>/<总数>:<数据>

恢复：按顺序扫描所有二维码，去掉每个的 COLDKEY:N/M: 前缀，拼接，验证 SHA-256 校验和。

纸质备份内容

生成的 HTML 文档包含：

• 标题和元数据（日期、主机名、用户、源路径）
• 原始密钥文本（等宽字体，用于手动抄录）
• 二维码，附带容量标注
• SHA-256 校验和，用于验证
• 分步恢复说明
• 打印按钮（打印媒体中隐藏）

恢复步骤

1. 扫描二维码（或手动输入原始密钥文本）
2. 保存到 ~/.config/sops/age/keys.txt
3. 验证：sha256sum keys.txt 与打印的校验和一致
4. 测试：sops -d <加密文件>

构建

just build        # 本地二进制
just docker       # Docker 镜像（ghcr.io/pike00/coldkey）
just test         # 运行测试
just ci           # 完整 CI：vet → test → build → docker

限制

• Go GC 和安全内存：Go 的垃圾收集器可能会在内存中复制对象，且 Go 字符串是不可变的，因此以 string（例如来自 identity.String()）形式持有的密钥材料无法可靠地覆写。secure.Zero() 使用 Go 的内置 clear() 擦除 []byte 缓冲区，但早期的字符串副本可能会在堆中一直存在直到垃圾收集。mlockall 可防止这些内容被交换到磁盘；两者共同提供了纵深防御，但并不能保证密钥材料立即从 RAM 中擦除的加密保证。
• mlockall 需要 CAP_IPC_LOCK：在 Docker 运行时添加 --cap-add IPC_LOCK 以获得完整的交换保护。没有此标志时，coldkey 会向 stderr 打印一条警告并继续运行。
• 二维码扫描：非常密集的二维码（版本 40）可能难以从纸上扫描。原始密钥文本始终作为手动备用方案包含在内。

许可证

MIT