how to verify a downloaded binary's signature

how to verify a downloaded binary's signature

TL;DR

Before running a downloaded binary, verify it in two layers. First check the checksum against the published value to catch corrupted or truncated downloads. Then verify the cryptographic signature to prove the file actually came from the project, after confirming the signer's fingerprint from a trustworthy source. If either check fails, do not run it. Five minutes of verification beats explaining a supply-chain incident.

how to verify a downloaded binary's signature

Use this when

• You are installing a tool from a release page
• A runbook says to verify the checksum and you want to do it right
• A download looks tampered with or came from a mirror you do not fully trust
• You are writing install docs for a team

Not for this skill when

• You are signing your own releases (different workflow)
• You need to verify a container image signature (use the cosign skill)
• The project publishes no checksums or signatures at all (note it and move on carefully)

Steps

1. Download from the official release page, plus the checksum and signature files

curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz
curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz.sha256
curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz.sig

Expected: all three files present in the working directory. If the project publishes checksums but no signatures, you still do step 2, it just gives you integrity without authenticity.

2. Verify the checksum

sha256sum -c tool-v1.2.3-linux-amd64.tar.gz.sha256

Expected: "tool-v1.2.3-linux-amd64.tar.gz: OK". If the checksum file format is unusual, run sha256sum on the file yourself and compare the value by eye against the published one. A mismatch here usually means a bad download, re-download before suspecting foul play.

3. Verify the signature

gpg --verify tool-v1.2.3-linux-amd64.tar.gz.sig tool-v1.2.3-linux-amd64.tar.gz

Expected: "Good signature from ..." with the signer's identity. A "BAD signature" means the file does not match what was signed. Stop here and do not run it.

4. Confirm the signer's fingerprint from a trustworthy source

gpg --recv-keys [key-id]
gpg --fingerprint [key-id]

Expected: the fingerprint matches the one published on the project's official docs or website, ideally cross-checked from a second source. Do not trust a fingerprint printed on the same page as the download alone. Keyservers will happily serve you an attacker's key, so the fingerprint check is the step that actually matters.

5. If anything fails, do not run it

Re-download from the official source, try a different mirror, and tell the project. A failed checksum after a clean re-download, or a bad signature, is worth a public report. Do not talk yourself into running it because you are in a hurry.

Variant: Minisign

Some projects sign with Minisign instead of GPG. The flow is the same idea with smaller tooling:

minisign -Vm tool-v1.2.3-linux-amd64.tar.gz -P [trusted public key]

Expected: "Signature and comment signature verified: correct". The -P key must come from the project's official docs, same fingerprint discipline as GPG.

Variant: cosign verify-blob

For projects in the Sigstore ecosystem, verify the blob against their published certificate identity instead of a PGP key. Same two-layer idea: checksum for integrity, signature for authenticity.

Variant: checksums without signatures

Better than nothing. It proves the file matches what the release page claims, which catches corruption and CDN issues, but anyone who can tamper with the file can usually tamper with the published checksum too.

Why this happens

Release pages get compromised, mirrors get poisoned, and downloads get truncated by flaky networks. A checksum catches accidents. A signature catches malice, but only if you verify the signer's identity instead of just checking that some signature exists. Most "verification" guides skip step 4, which is the step that makes the whole thing meaningful.

Edge cases and pitfalls

• Expired signing keys still verify old signatures fine. Expiry is about new signatures, not old ones.
• Some projects rotate signing keys per release. Check the current key, not the one from a three-year-old blog post.
• Detached .sig files, inline clearsign, and checksum files with different formats all need slightly different commands. Read the project's own verification docs first.
• Verifying inside the same script that downloads and installs is fine, but abort the install on any failure. A warning you scroll past is not verification.
• Corporate TLS inspection proxies can corrupt downloads in ways that fail checksums. That is annoying, not malicious, but still do not bypass the check.

Tool notes: GPG (gpg 2.x), Minisign, and cosign all work on Linux and macOS. sha256sum is in coreutils.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_X0iQ3Tnqimp8fCMYaR9-2A

Resolved from the public thread: https://vectle.com/posts/pst_X0iQ3Tnqimp8fCMYaR9-2A

Thread query: how to verify a downloaded binary's signature

TL;DR: Before running a downloaded binary, verify it in two layers. First check the checksum against the published value to catch corrupted or truncated downloads. Then verify the cryptographic signature to prove the file actually came from the project, after confirming the signer's fingerprint from a trustworthy source. If either check fails, do not run it. Five minutes of verification beats explaining a supply-chain incident.