Bitcoin Core Security
There are three important steps to ensuring your install of Bitcoin is secure and free of malware:
Last updated
There are three important steps to ensuring your install of Bitcoin is secure and free of malware:
Last updated
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.
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):
If you have the misfortune of using Windows or macOS, you can , 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!
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.
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.
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).
To look at the fingerprint of a key file, you can use this command:
This will print a lot of information about the key file, but the relevant information is at the very top:
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.
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):
Or if you only have the fingerprint, like this (put the key fingerprint you want to use!):
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):
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.
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):
If this is successful, it will tell you:
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…
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!):
This will print something like:
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.
Developers will usually post their keys or fingerprints on their website, and perhaps a few others (mine is on , , , and ).
Bitcoin Core’s “assert” file pairs are published here:
Bitcoin Knots’s “assert” file pairs are published here: