Coldkey는 포스트퀀텀 age 암호화 키를 생성하고 종이 백업을 만드는 CLI 도구입니다. age 또는 sops로 암호화된 파일을 복호화하는 데 필수적인 age 개인 키를 잃어버리는 문제를 해결하기 위해 QR 코드가 포함된 인쇄 가능한 HTML 문서를 생성합니다.

설치

# 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-* 명령에는 --network none, --read-only, --cap-drop ALL, --security-opt no-new-privileges:true와 같은 보안 강화 플래그가 포함됩니다. 출력은 ./output/에 작성됩니다.

명령어

• 대화형 모드 (coldkey): 새 키를 생성하거나 기존 키로 백업을 생성하는 메뉴.
• 생성 (coldkey generate [-o PATH] [-f] [--no-backup]): 새 포스트퀀텀 age 키 쌍(ML-KEM-768 + X25519) 생성. -o가 제공되지 않으면 기본적으로 stdout에 출력.
• 백업 (coldkey backup [flags] KEYFILE): 기존 키 파일에서 인쇄 가능한 HTML 종이 백업 생성.
• 버전 (coldkey version): 버전 문자열 출력.

보안 모델

• 메모리: mlockall(MCL_CURRENT|MCL_FUTURE)을 사용하여 키 자료가 디스크로 스왑되는 것을 방지.
• 파일: 모드 0600으로 작성, fsync됨; 임시 파일은 3회 덮어쓰기로 파쇄.
• 프로세스: 비밀은 stdin/파일로만 전달되며, 프로세스 인수에는 절대 전달되지 않음.
• 컨테이너: 셸이 없는 Distroless/static:nonroot 이미지, 비루트 UID 65534.
• 메모리 제로화: 가비지 컬렉션 전에 키 버퍼에 대해 secure.Zero()를 최선의 방식으로 수행.

QR 코드 인코딩

포스트퀀텀 age 키는 32바이트 시드만 저장하므로 keys.txt는 일반적으로 약 2,089바이트이며, 단일 QR 코드(버전 40, EC-L은 2,953바이트 지원)에 들어갑니다. 더 큰 파일의 경우 coldkey는 프레이밍 프로토콜을 사용하여 여러 QR 코드로 분할합니다: COLDKEY:<part>/<total>:<data>. 복구: 모든 QR 코드를 순서대로 스캔하고 접두사를 제거한 후 연결하고 SHA-256 체크섬을 확인합니다.

종이 백업 내용

생성된 HTML에는 제목/메타데이터(날짜, 호스트명, 사용자, 소스 경로), 고정폭 글꼴의 원시 키 텍스트, 용량 주석이 있는 QR 코드, SHA-256 체크섬, 단계별 복구 지침이 포함됩니다.

복구 절차

1. QR 코드를 스캔하거나 원시 키 텍스트를 입력합니다.
2. /.config/sops/age/keys.txt에 저장합니다.
3. 확인: sha256sum keys.txt가 출력된 체크섬과 일치하는지 확인합니다.
4. 테스트: sops -d <임의의 .sops 파일>

제한 사항

Go의 가비지 컬렉터는 메모리에서 객체를 복사할 수 있으며, Go 문자열은 불변입니다. 문자열로 키 자료를 보유하면(예: identity.String()에서) 안전하게 제로화할 수 없습니다. Coldkey는 바이트 버퍼에 대해 최선의 제로화를 수행합니다.