Check the signature on a download SIGIL

Why almost nobody checks a signature

A download page prints a signature so that anybody can confirm the file is the one the publisher signed. It is a genuinely strong guarantee, and the proportion of people who ever check one is close to zero.

The reason is entirely practical. Checking means installing gpg, or minisign, or working out the right ssh-keygen -Y verify incantation with the right allowed signers file; and for GnuPG it usually also means importing a key, understanding what the resulting warning about trust actually means, and deciding that the warning is fine. By the time all that is done the file has been installed for twenty minutes.

So this reads the three formats a download page hands out and checks them here, in the tab, with the browser's own cryptography. Nothing is uploaded, and the file is hashed a chunk at a time in a worker, so a multi-gigabyte image can be checked without being held in memory.

The three formats

• minisign: two base64 lines: an algorithm marker, an eight-byte key id and a 64-byte Ed25519 signature, then a trusted comment and a second signature over the first signature and that comment. The ED variant signs the BLAKE2b-512 of the file rather than the file, and because no browser exposes BLAKE2b, that is implemented here.
• SSHSIG: OpenSSH's own format. What is actually signed is the magic string, the namespace, a reserved string, the hash name and the hash of the file, each length-prefixed. Getting that construction right is the whole job; a verifier that hashes the file and checks the signature against it will reject every valid signature in existence.
• OpenPGP: RFC 4880 and RFC 9580, armoured or binary: old and new packet headers, partial lengths, the CRC-24 on the armour, version 4 and version 6 signature packets with their hashed subpackets and trailer, key packets and subkeys with their binding signatures, and RSA, ECDSA, EdDSA and Ed25519 with their multiprecision integers.

The public-key arithmetic is the browser's own, through crypto.subtle. Where a signature's algorithm hashes internally and WebCrypto will only accept one buffer, the file is read into memory up to two gigabytes and refused in plain words beyond that, rather than failing in a way you would have to guess at.

A valid signature answers a narrower question than people think

“This signature is valid” means: whoever holds that private key signed these exact bytes. It does not mean the file is safe, it does not mean the publisher is trustworthy, and above all it does not mean the key is the publisher's.

That last one is where the whole scheme turns. If the key came from the same page as the download, an attacker who could replace the file could replace the key, and both would verify perfectly. A signature is only worth the independence of the key: from the project's repository, a distribution's keyring, a key you have checked before, a fingerprint published somewhere the attacker does not control. This shows you the key id and the signing time so you can compare them against a source of your own choosing, which is the step that actually does the work.

When there is no signature and only a published hash, CHECKSUM is the right tool and answers a weaker question. CERTLENS reads the certificate on the site you downloaded from, and PROVENANCE records what you received and when, for a file that has to be accounted for later.