Verifying the recovery tool

Every printed card carries two short pieces of text: the recovery tool’s SHA-256 hash and a minisign public key fingerprint. Together they let you prove that the recover.html in front of you is exactly the file we published, no matter where you downloaded it from, and no matter whether AmberKey still exists.

Verification is optional but cheap, and for a file you’re about to trust with key material, worth the two minutes.

Check the hash

The hash is a fingerprint of the file’s exact contents. Compute it and compare with the printed value:

Linux:

sha256sum recover.html

macOS:

shasum -a 256 recover.html

Windows (PowerShell):

Get-FileHash recover.html -Algorithm SHA256

Compare the output with the hash printed on the card. You don’t need to check all 64 characters character-by-character under stress. The first and last 8 are plenty to rule out accident, and the signature check below rules out malice.

Check the signature

The hash pins one exact release. The signature proves any release is genuinely ours. Releases are signed with minisign, a small, widely packaged verification tool (apt install minisign, brew install minisign).

Download the .minisig file next to recover.html on the release page, then:

minisign -Vm recover.html -P <public key printed on the card>

Signature and comment signature verified means the file is authentic.

If the hash doesn’t match

Don’t panic — the common cause is version skew, not tampering. Cards print the hash of the release that was current when they were printed; if you downloaded a newer release, its hash will differ. Two clean ways to resolve it:

1. Verify the signature instead. Every genuine release, old or new, verifies against the same printed minisign key. If the signature checks out, the file is ours.
2. Or download the exact printed version. Release pages list hashes for every version; find the one matching your card and use that file.

If a file fails both checks — wrong hash and bad signature — do not use it. Download from a different mirror (GitHub, then Codeberg, then Software Heritage or the Internet Archive; the full list is on the continuity page) and check again.

Why you can trust the hash at all

Every release is signed and built from pinned source, and the hash is produced and signed in that environment. Within a fixed build environment the output is deterministic, and the build instructions live in the repository for anyone to audit. (Bit-exact rebuilds on an arbitrary machine aren’t guaranteed yet — a dependency compiles nondeterministically, a gap we’re closing openly; see the note below.) The signature is the trust root: verify it and the hash of the signed file, and you have exactly what we released.

During a fire drill

The fire drill includes this verification on purpose, so that the first time you check a hash isn’t the day it matters. If you’re setting AmberKey up now, run the commands above once against your saved copy. Then you’ll recognize both the ritual and the expected output.

A note on reproducible builds

Builds of recover.html are deterministic within a pinned build environment, and every release ships the hash produced and signed there. Today, rebuilding on an arbitrary machine may not be bit-exact (a dependency compiles nondeterministically, a gap we’re actively closing upstream). Until it is, the minisign signature is the trust root: verify the signature and the hash of the signed artifact, and you have exactly what we released.