Bitcoin Core is the first implementation of the Bitcoin protocol and is widely-regarded as the de facto standard. Nevertheless, users running this software are trusting it to keep private keys safe and faithfully report network activity. To reduce the risk of running malware, users can verify the authenticity of Bitcoin Core downloads before using them. This tutorial describes how to do so on OSX.

The Threat of Malware

Software that creates or handles Bitcoin payments presents by its nature a highly attractive target for malware authors. They begin by tweaking some of the source code. Then they distribute the result, which looks identical to the authentic version. An unwitting user downloading and installing the software, can fall victim to a wide variety of schemes designed to steal money or information.

Public Key Cryptography to the Rescue

Many Bitcoin users are familiar with the idea of digital signatures. The same idea can be applied to software downloads. The developer signs a download with a private key. Users verify the download using the developer’s public key. A forged file that changes a single bit can be detected with this system, as can a developer who attempts to apply an invalid signature. The standard method for signing binaries is known as Pretty Good Privacy (PGP). Implementations are available for all operating systems.

Download and Install GPG Suite

A popular PGP implementation on OSX is GPG Suite. Begin by downloading the installer from the main page.

We are immediately faced with a conundrum: how do we know that our copy of GPG Suite is authentic? We can’t verify a signature because if we could do that we wouldn’t need GPG Suite.

Fortunately, we can verify the installer’s hash value. Think of a hash value as an immutable, unique identifier that can be assigned to any file. OSX allows hash values to be checked with the shasum utility, which runs from the Terminal application. To access Terminal, press command (⌘) spacebar and type “Terminal”. You’ll see a mostly empty window with a prompt after a dollar sign (“$”). Commands are entered, in text form, after this prompt. Pay attention to capitalization and press enter after each line.

From Terminal, enter the following two commands:

$ cd ~/Downloads
$ echo "{hash}  {filename}" | shasum -a 256 -c -

where:

• {hash} is the string of characters that appears at the bottom of the GPG Tools page after clicking on the “SHA256” link;
• {filename} is the name of the GPG Suite installer you downloaded; and
• two spaces appear between {hash} and {filename}.

For example, On November 1, 2017, I downloaded a file named GPG_Suite-2017.1.dmg and its SHA256 hash value was:

01705da33b9dadaf5282d28f9ef58f2eb7cd8ff6f19b4ade78861bf87668a061

I would then enter the following two commands into Terminal (leaving out the dollar signs):

$ cd ~/Downloads
$ echo "01705da33b9dadaf5282d28f9ef58f2eb7cd8ff6f19b4ade78861bf87668a061  GPG_Suite-2017.1.dmg" | shasum -a 256 -c -

The first command moves my frame of file reference to the Downloads directory. The second command verifies the checksum of the file I downloaded. You should see a response that looks something like:

GPG_Suite-2017.1.dmg: OK

Notice that an attacker who was able to change the GPG Suite website might be able to give you the correct hash value for a fake copy of the installer. This is one of the limitations of using hash values to authenticate downloads.

After downloading and verifying the hash value of GPG Suite installer, double click on it. An installer window will be presented. Double click on the one named Install.pkg. Enter your system password when prompted and follow the remaining instructions.

You will be asked to generate a new key pair. For the purposes of verifying Electrum, this step can be skipped. Click the Cancel button.

Import the Developer Public Key

GPG Tools should present a window containing a single key entry — the one for the GPG Suite team. Before validating the Bitcoin Core signature, we’ll need to add the public key of its developer to our list.

Wladimir J. van der Laan signs Bitcoin Core releases. The bitcoin.org website has published his public key. It can also be looked up in GPG Keychain. Wladimir’s key ID is 36C2E964. Click the GPG Keychain “Lookup Key” button and enter the key ID. Then click Search.

GPG Keychain should respond with an entry for Wladimir J. van der Laan’s public key. Click Retrieve Key.

GPG Keychain should report that Wladimir’s public key was added. You’ll now see two key entries: the original for the GPGTools Team and a new one for the Bitcoin Core developer. We can now verify the signature of any Bitcoin Core download

Download and Verify Bitcoin Core

Unlike some packages such as Electrum, Bitcoin Core doesn’t directly associate a signature with a download. Instead, Bitcoin Core publishes a file containing a list of hash values for all of its download packages. The file containing this list is what Wladimir van der Laan signs.

The overall procedure for using the hashes file is:

1. download Bitcoin Core and the hashes file;
2. verify the signature of the hashes file; and
3. verify a match between the published value contained in the hashes file and the one computed from the download file.

Both files are downloaded from the Bitcoin Core download page. Click the Download Bitcoin Core button to begin the download. Next, download the hashes file located behind the link titled “Verify release signatures” on the downloads page. Click the link titled “Verify release signatures.” Doing so places a file titled SHA256SUMS.asc into your Downloads folder.

Your downloads folder should now contain two files, SHA256SUMS.asc and bitcoin-{version}-osx.dmg, where {version} is the version of Bitcoin Core you downloaded.

To verify the signature of the hashes file, right click on it. A context menu will appear whose last item is called Services. Hovering over it presents a submenu. One of its entries will be called “OpenPGP: Verify Signature of File.” Click it.

You should be presented with a window titled “Verification Results.” A single line should appear. The first entry gives the installer’s filename. The second gives the result of the verification. You should see text beginning with “Signed by: Wladimir J. van der Laan”. The line will be appended with the bolded text “undefined trust.”

Finally, confirm that the SHA-256 hash value published in the hashes file matches the one you’ll obtain through independent verification.

Once again, we’ll use the shasum utility via Terminal. Enter the following two commands, hitting return after each line. Pay attention to capitalization and omit the dollar sign:

$ cd ~/Downloads
$ shasum -c SHA256SUMS.asc 2>&1 | grep dmg

Terminal should respond with the line:

bitcoin-{version}-osx.dmg: OK

if the hash value matches. Otherwise, the response will read:

bitcoin-{version}-osx.dmg: FAILED.

Optional: Sign the Developer Key

At this stage, you’ve verified the signature of the Bitcoin Core download. You could, however, take this one step further by signing Wladimir van der Laan’s public key. The procedure is analogous to the one previously described.

Conclusions

Signature validation should be used for any Bitcoin Core installation destined to control large sums of money. Given that wallets holding spare change today can grow to become wallets holding substantial sums tomorrow, signature verification should be the first step of any Bitcoin Core installation. This guide offers a step-by-step procedure for doing so. Once set up, it can be used to verify the signature of any future Bitcoin Core release, and other Bitcoin software as well.

To recap, the steps are:

1. Download GPG Suite.
2. Verify the GPG Suite checksum.
3. Import the public key for Bitcoin Core’s lead developer.
4. Download the Bitcoin Core installer and hashes files.
5. Verify the signature of the hashes file.
6. Compare the hash value in the hashes file to the one you independently compute with shasum.