How to verify Bitcoin software: A Technical Guide to GPG Signatures and SHA256 Hashes

To how to verify Bitcoin software correctly, you must confirm two properties before running any Bitcoin Core binary: integrity via SHA-256 hash comparison, and authenticity via PGP signature validation against trusted developer keys. This guide provides the complete workflow for Windows, macOS, and Linux, plus troubleshooting for common failures.

Why Verification Requires Two Checks, Not One

A hash check alone proves your downloaded file matches a published checksum. A signature check proves that checksum list was signed by someone holding a recognized Bitcoin Core maintainer private key. Without both, an attacker controlling a download mirror or intercepting your connection could serve a malicious binary with a matching checksum, and hash-only verification would still pass

The standard workflow verifies the PGP signature on SHA256SUMS.asc first. Only after confirming "Good signature" from a trusted key should you compute and compare the SHA-256 hash of your binary. Reversing this order wastes effort and creates false confidence.

What SHA-256 Proves and What It Does Not

The SHA-256 function produces a fixed 64-character hexadecimal output from any input. If even one bit changes in the file, the output changes unpredictably. When your locally computed hash matches the corresponding line in SHA256SUMS, you know the file on disk is byte-for-byte identical to what developers published.

The hash does not tell you who created the checksum file. It does not confirm the binary is free of bugs or backdoors. It confirms file identity, not origin or safety.

What a PGP Signature Proves and What It Does Not

A detached PGP signature over SHA256SUMS proves that someone holding a specific private key signed that exact checksum file and that the file has not been modified since signing. If you have independently verified the corresponding public key fingerprint against official sources, you can attribute the signature to a Bitcoin Core release maintainer.

The signature does not prove the developers' build environment was clean. It does not prove the code is vulnerability-free. It proves origin and integrity of the checksum list itself.

Files You Need Before Starting

Download exactly three files from the same release version at the official domain bitcoincore.org:

1. Platform binary (e.g., bitcoin-31.0-win64-setup.exe, bitcoin-31.0-x86_64-linux-gnu.tar.gz)
2. SHA256SUMS: plain text file listing official checksums for every release binary
3. SHA256SUMS.asc: detached PGP signatures over SHA256SUMS

Download all three from https://bitcoincore.org/bin/bitcoin-core-31.0/. Verify the URL shows bitcoincore.org (not a .com variant) and that your browser shows a valid HTTPS certificate. Bookmark the official site to avoid phishing pages promoted in search results.

Common mistakes: downloading from GitHub releases that may omit signature files, renaming files after download (verification commands expect exact original filenames), mixing files from different versions, or downloading over plain HTTP where network attackers can substitute files silently.

Step 1: Verify the PGP Signature on SHA256SUMS

This step confirms the checksum file was signed by Bitcoin Core release maintainers. You need GnuPG version 2.2 or later installed and relevant signing keys imported.

Import Signing Keys from guix.sigs

Bitcoin Core releases are signed by multiple developers. Their public keys are collected in the guix.sigs repository at https://github.com/bitcoin-core/guix.sigs under builder-keys/ (Source: github.com/bitcoin-core/guix.sigs, 2026).

Clone the repository and import keys:

git clone https://github.com/bitcoin-core/guix.sigs.git
cd guix.sigs/builder-keys

On Linux or macOS:

for key in *.gpg; do gpg --import "$key"; done

On Windows PowerShell:

Get-ChildItem *.gpg | ForEach-Object { gpg --import $_.FullName }

You do not need every key. Choose several developers whose identities you can verify through independent channels, then import those.

Run the Verification Command

Navigate to your downloads directory and run:

gpg --verify SHA256SUMS.asc SHA256SUMS

A valid result includes:

gpg: Signature made [date] using RSA key ID [KEYID]
gpg: Good signature from "Developer Name <email>"
gpg: WARNING: This key is not certified with a trusted signature!
Primary key fingerprint: E777 299F C265 DD04 7930 70EB 944D 35F9 AC3D B76A

Critical elements: "Good signature" means cryptographic math checks out. The fingerprint must match what you verified from official sources. The "not certified" warning is normal and expected because you have not established a local GPG web-of-trust path. It does not indicate a problem. You handle trust by manually verifying the fingerprint, not by relying on GPG's trust database.

Pass or Fail Decision

If you see "Good signature" and the fingerprint matches your independently verified records, proceed to hash verification. If you see "BAD signature," stop immediately. Do not install anything. Re-download SHA256SUMS.asc from the official site and retry. If the bad signature persists, delete all files and start over on a different network connection. If you see "no public key," you have not imported the signing key. Import it from guix.sigs and retry.

Step 2: Verify the SHA-256 Hash of Your Binary

After confirming a valid signature, compute the SHA-256 hash of your downloaded binary and compare it character-by-character against the corresponding line in SHA256SUMS.

Find the Expected Hash

Open SHA256SUMS in a text editor. Each line contains a 64-character hex string followed by the filename. Locate the line matching your platform binary.

Compute the Hash by Operating System

Linux:

sha256sum bitcoin-31.0-x86_64-linux-gnu.tar.gz

macOS:

shasum -a 256 bitcoin-31.0-arm64-apple-darwin.dmg

Windows PowerShell:

certutil -hashfile bitcoin-31.0-win64-setup.exe SHA256

Compare Output Precisely

Place computed and expected hashes side by side. All 64 characters must match exactly. Do not rely on visual scanning alone. Use your terminal's search function or paste both strings into adjacent lines in a text editor and compare character by character.

A faster method on Linux and macOS:

sha256sum --check SHA256SUMS --ignore-missing

Expected output: bitcoin-31.0-x86_64-linux-gnu.tar.gz: OK

The --ignore-missing flag skips files listed in SHA256SUMS that are not present. If output shows anything other than "OK," the file does not match. Do not install it.

OS-Specific Notes and Common Pitfalls

Windows: Install Gpg4win from https://gpg4win.org/. If PowerShell does not recognize gpg, use the full path: C:\Program Files (x86)\GnuPG\bin\gpg.exe. SHA256SUMS uses Unix-style line endings (LF); this rarely affects manual comparison but can impact automated scripts.

macOS: Install GnuPG via Homebrew (brew install gnupg) or GPG Suite. Note that macOS Gatekeeper performs separate code-signing checks against Apple certificates. That check does not replace Bitcoin Core's release verification. You must still verify PGP signature and SHA-256 hash yourself.

Linux: GnuPG is available via package manager: sudo apt install gnupg (Debian/Ubuntu), sudo dnf install gnupg2 (Fedora). The filename in your directory must exactly match the filename in SHA256SUMS. Renaming the file causes check failure even if contents are identical.

How to Verify Signing Keys Safely

The signature is only meaningful if you verified you have the correct public key. An attacker who compromises your download could provide their own key and matching signature.

The Fingerprint Verification Rule

Never trust a key solely because it appeared on a keyserver or came bundled with a download. Keyservers host any key anyone uploads, and short key IDs can have collisions. Always verify the full 40-character fingerprint, not just the 8-character short ID.

Get the fingerprint from your local keyring with gpg --fingerprint [KEY_ID], then compare against at least two independent sources: the official Bitcoin Core download page, the guix.sigs repository on GitHub, and announcements on the bitcoin-dev mailing list.

Automated Verification Script

Bitcoin Core includes a Python script at contrib/verify-binaries/verify.py that automates both signature and hash verification. Usage: ./contrib/verify-binaries/verify.py pub 31.0. This script is convenient but still requires you to have imported and verified the keys you trust (Source: github.com/bitcoin/bitcoin, 2026).

Troubleshooting Verification Failures

Most failures have straightforward causes. Work through them methodically before concluding something adversarial happened.

Hash Mismatch Causes Ranked by Likelihood

1. Incomplete download (most common): the download was interrupted or resumed incorrectly. Re-download the binary from scratch.
2. Wrong file or wrong line in SHA256SUMS: you selected the hash for a different platform or version. Double-check the filename.
3. File corruption during transfer: rare over HTTPS but possible. Re-download.
4. Antivirus modification: some antivirus software modifies executables on disk. Check your antivirus quarantine log.
5. Disk error: storage medium corruption can silently alter file contents.

When to Abort Entirely

Delete all three files and start over on a different network connection if you see "BAD signature" that persists after re-downloading SHA256SUMS.asc, if a hash mismatch survives two complete re-downloads of the binary, or if you have any reason to suspect your network is being tampered with (public WiFi, captive portal, untrusted VPN).

Optional Hardening: Reproducible Builds

Reproducible builds allow anyone to compile Bitcoin Core from source and produce byte-for-byte identical binaries to the official release. Multiple independent builders publish attestations in the guix.sigs repository. If several builders produce the same hash, you have strong evidence the released binary matches public source code with no hidden modifications inserted during compilation.

Bitcoin Core has achieved reproducible builds since version 0.21, with each release verified by multiple independent builders (Source: bitcoincore.org, 2026). This step is worth the effort when securing substantial holdings on a node or when you want cryptographic proof that the binary matches source code. For most users, verifying signature and hash is sufficient protection against common attack vectors.

Pre-Installation Checklist

Complete these steps in order before running Bitcoin Core:

1. Download three files from bitcoincore.org/bin/bitcoin-core-31.0/: platform binary, SHA256SUMS, SHA256SUMS.asc
2. Import signing keys from guix.sigs/builder-keys
3. Run gpg --verify SHA256SUMS.asc SHA256SUMS and confirm "Good signature" with fingerprint matching independently verified records
4. Compute hash of your binary using OS-appropriate command
5. Compare computed hash against matching line in SHA256SUMS. All 64 characters must be identical
6. Only then install and run Bitcoin Core

If any step fails, do not proceed. Re-download and retry, or start over on a different network.

Traders on platforms like BYDFi who run Bitcoin nodes for market data verification can use this workflow to ensure their software integrity before connecting to production environments. BYDFi's BTC spot market provides live order book data for those looking to trade Bitcoin after securing their node infrastructure.

Frequently Asked Questions

What does it mean to verify a Bitcoin Core download in plain terms?

It means proving two things about the file on your disk before you run it. First, confirm the file is identical to what developers published by comparing its SHA-256 hash against the official checksum list. Second, confirm that the checksum list was actually signed by recognized Bitcoin Core maintainers by checking a PGP signature against their verified public keys. Together these catch tampered downloads, corrupted transfers, and files from compromised mirrors.

Can I skip the signature check and just verify the hash?

No. A hash check alone confirms the file matches some published checksum, but it does not confirm who published that checksum. An attacker who can replace the binary on a download mirror or during network interception can also replace the SHA256SUMS file with one listing the hash of their malicious binary. Your hash check would pass against the forged checksum. The signature ties the checksum list to a specific private key held by a Bitcoin Core maintainer.

What does the "not certified with a trusted signature" GPG warning mean?

This warning appears because you have not established a local GPG web-of-trust path to the signing key. It is expected behavior during Bitcoin Core verification and does not mean the signature is invalid. What matters is that the fingerprint printed by GPG matches the fingerprint you verified from at least two independent official sources. The cryptographic verification is separate from GPG's trust-database bookkeeping.

My hash does not match. What should I do first?

Re-download the binary entirely rather than resuming a partial transfer. The most common cause is an incomplete or interrupted download. Second, verify you are checking the correct line in SHA256SUMS for your exact platform and architecture. Third, check if antivirus software modified the file. Only after these steps should you suspect network tampering.

How do I verify on Windows without Linux tools?

Install Gpg4win from gpg4win.org for signature verification. Use the built-in PowerShell command certutil -hashfile [filename] SHA256 for hash verification. No Linux tools are required. The full Windows walkthrough appears in the OS-specific section above.

This article is for educational purposes only and does not constitute financial advice.