How to securely install Bitcoin

7 min readMar 7, 2020

Expectations

These instructions require that you understand how files are stored in your computer (abstractly; if you know what a directory/folder is, you’re probably okay) and how to use the command line to run programs and access files. If you don’t understand these concepts, first start with a guide explaining them to you.

Be mindful that the instructions here can only help you install Bitcoin securely. It does not attempt to help you secure your hardware, your operating system, or avoid malware introduced by other applications you install. Generally, if anything else in your computer is compromised, your node will also be at risk, no matter how secure you verify its own install.

If you want an absolutely secure node, in addition to the instructions herein, you will need to (at least) avoid backdoored hardware (including Raspberry Pi, and anything produced by Intel or AMD), run a trustworthy Linux-based operating system, only install or use software either provided by your OS vendor, or otherwise verified using GnuPG (such as described in this article), and ensure it’s kept up to date with the latest vulnerability patches.

Even if you can’t get maximum security by addressing these other concerns, that doesn’t mean you should give up, however: it is still a good idea to verify your Bitcoin node software anyway.

Overview

There are three important steps to ensuring your install of Bitcoin is secure and free of malware:

Verifying the OpenPGP key(s)
Verifying the signature(s)
Verifying the file itself

Each step depends on the previous steps being successful, and while it is possible to skip a step, it is important to understand that your install is not verified unless all the steps are successful.

Note that for examples, I will be verifying my own signature on Bitcoin Knots v0.19.0.1.knots20200104 for ppc64le Linux. To verify someone else’s signature and/or another file, you will need to change the command line to use that fingerprint and/or filename.

Step 0: Installing GNU Privacy Guard (GPG)

Before you can begin, you will need to ensure you have the GNU Privacy Guard (GPG) tools installed. This is what does all the cryptographic verification needed to ensure your files are safe.

If you run a Linux-based system, you can usually install it from your OS vendor. These days, it’s usually already installed “out of the box” — you can check by running gpg --version. If not, try installing it with one of these commands (if they fail, move on to the next):

apt-get install gnupg
dnf install gnupg2
yum install gnupg2
emerge app-crypt/gnupg
pacman -S gnupg 
apk add gnupg

If you have the misfortune of using Windows or macOS, you can download GnuPG from their website, but I’m not aware of any secure way to verify that download. They do, of course, provide signatures, but you have a chicken-and-egg problem: until you install a good copy, you have no way to verify those signatures!

Step 1: Verifying the OpenPGP key(s)

This is arguably the most difficult step of the process: you need to confirm that the key(s) you are using actually are the correct keys used by the people you trust to produce malware-free software. If you’re not careful, you could end up with a fake key for “Luke Dashjr” — which would result in checking that the fake person signed the program, not the real one!

Each OpenPGP key has a “fingerprint”, which is 40 hexadecimal characters (numbers 0–9 and A-F), sometimes shown with spaces to make them easier to read. If you ensure the fingerprint of the key you are using matches the fingerprint of the trusted signer, you know you have the right key.

Obtaining keys and/or fingerprints

The most secure way to verify the keys, is to meet us in person and confirm the key “fingerprint”. Almost nobody memorises their key fingerprint, so it’s normal that we might have to look it up on our own laptop or phone.

Once in a while — usually at conferences or meetups — there may be “key signing parties” where a group of people meets to confirm the fingerprints of everyone else, by each participant either reading their own fingerprint aloud in person, or otherwise manually confirming that what everyone sees/hears is correct. If you get the opportunity to go to one, this is a good way to verify many keys at once.

If you’re not interested in or don’t have the chance to meet up in person, you should ideally verify a key from multiple sources.

Sometimes, conferences post video of presentations, where a key fingerprint might be shown in a slide. While “deep fake” technology is fairly new, do note that slides in video are much easier to manipulate.

Developers will usually post their keys or fingerprints on their website, and perhaps a few others (mine is on my personal website, bitcoinknots.org, bitcoin.org, and GitHub).

If you already have an installed copy of the software you trust, sometimes it will include the keys needed to verify updates (Bitcoin Core only includes it with source code at this time).

Checking the fingerprint of a key file

To look at the fingerprint of a key file, you can use this command:

gpg --import-options show-only --import --with-fingerprint luke-jr.asc

This will print a lot of information about the key file, but the relevant information is at the very top:

pub   rsa8192 2012-03-23 [SC] [expires: 2020-06-09] 
      E463 A93F 5F31 17EE DE6C  7316 BD02 9424 21F4 889F

In this case, E463 A93F 5F31 17EE DE6C 7316 BD02 9424 21F4 889F is the fingerprint for my key.

NOTE: If GPG says the key is expired, that is probably okay! In Step 2, you will update it to the newest version of the same key, which usually extends the expiration date.

Importing the verified key

Regardless of how you verify the key, you should make sure to remember which key you used, so you can verify the same key is used when you update in the future. Even if you skip verifying the key (not safe), at least this will ensure your updates are signed by the same person as the version you are installing today.

When you’re comfortable that the key you have is correct, import it like this (replace luke-jr.asc with the filename holding the key you want):

gpg --import < luke-jr.asc

Or if you only have the fingerprint, like this (put the key fingerprint you want to use!):

gpg --keyserver hkp://keyserver.ubuntu.com --recv-key E463A93F5F3117EEDE6C7316BD02942421F4889F

Step 2: Verifying the signature(s)

Now that you know what key you wish to verify with, the next step is to check the signature is valid.

Before you can proceed with this step, you must be sure your copy of the signer’s key is up to date. If you fail to do so, you may get a message about the key being expired. Run (again, use the actual fingerprint you want):

gpg --keyserver hkp://keyserver.ubuntu.com --refresh-key E463A93F5F3117EEDE6C7316BD02942421F4889F

Next, you will need two files (in addition to the program file you’re checking): the “.assert” file which contains a list of file fingerprints, and the “.assert.sig” file which contains the signature for that list. This is because instead of signing the program file itself, what we do is fingerprint all the files, and then sign that list. You will need both files.

Bitcoin Core’s “assert” file pairs are published here: https://github.com/bitcoin-core/gitian.sigs/find/master
Bitcoin Knots’s “assert” file pairs are published here: https://github.com/bitcoinknots/gitian.sigs/find/knots

Note that there is a separate file pair for each signer. If you are verifying that multiple people have signed your file (which you should), you will need to check each file pair. Also be sure you are getting the files for the version you intend to verify!

When you find the files you want on the list, open it in your browser by clicking the link, then right-click on the “Raw” or “Download” button and select “Save Link As”.

Once you have both “assert” files, you can then check the signature by running (adjust the file name to your specific .assert.sig):

gpg --verify bitcoin-core-linux-0.19-build.assert.sig

If this is successful, it will tell you:

gpg: Signature made Sun 19 Jan 2020 03:47:15 AM UTC 
gpg: using RSA key E463A93F5F3117EEDE6C7316BD02942421F4889F 
gpg: Good signature from “Luke Dashjr <luke@dashjr.org>” [ultimate]

Notice the key fingerprint in bold. That must match the key you verified in step 1, or it may have been signed by someone else! The part about “Good signature” is also important, but the name and email address are not — if the fingerprint is wrong, those can both be faked.

Assuming all went well, you now know the “.assert” file is vouched for by the person who controls the key in question, and can proceed to verify that your actual program file is the one listed in that “.assert” file…

Step 3: Verifying the file itself

To verify your program file, you must first take a cryptographic hash of it (essentially taking its fingerprints). This is done with a simple command (substitute the actual filename you’re verifying!):

Linux: sha256sum bitcoin-0.19.0.1.knots20200104-powerpc64le-linux-gnu.tar.gzWindows: certUtil -hashfile bitcoin-0.19.0.1.knots20200104-win64.zip SHA256macOS: shasum -a 256 bitcoin-0.19.0.1.knots20200104-osx-unsigned.dmg

This will print something like:

d370692590c4546ac0de250da91c6c288d9ee5252f1a4b857a5b80c4e3d81149  bitcoin-0.19.0.1.knots20200104-powerpc64le-linux-gnu.tar.gz

This is the fingerprint of the file content, followed by the filename you specified.

Now open the “.assert” file in any plain text editor/viewer, and look for that fingerprint. It should be in the “out_manifest” section at the top— if you get as far as “in_manifest” or “base_manifests”, you’ve gone too far.

If you find it in the “.assert” file, then you’ve verified the file you have, is the same one the signer vouches for (you’ll see their filename in the “.assert” file to the right of the fingerprint — it will likely be the same as your filename).

If it’s missing in the “.assert” file, that can mean either you are using the wrong “.assert” file, or your file does not match (in which case, you will see a different fingerprint next to the expected filename). If the file is listed, but has a different fingerprint, please do not open your file, but instead save it (we may ask you for a copy later) and contact the security team of the affected project.