Verifying Binaries

Overview

What is a binary?

Binaries are typically the easiest way for users to install software.

A binary is a file in machine-language format that a computer can read and execute. Most programmers don’t write software in machine-language. Instead, programmers write code in human-readable programming languages like Go, Javascript, C, or Python–otherwise known as source code. Advanced users and programmers can then compile the source code, which creates an executable binary.

However, if you aren’t a programmer and you don’t want to have to download compilers to run a piece of software, you can just download a binary executable. This binary file will have been compiled from the source code into a stand-alone program by someone else.

Why should you verify binaries before running them?

You shouldn’t immediately trust that a binary is safe, even if you downloaded it from a familiar website.

If you run a binary that you didn’t compile yourself, you’re placing your trust in whomever compiled the binary for you. This carries inherent risks. Since binary code is not human-readable, it’s impossible to directly tell if the binary was compiled from the true source code, or if the source code was tampered with by an adversary first.

Consider the case where an adversary created malware and disguised it to look like a Decred binary. Adversaries can try to trick you into running their malware by setting up fake download locations, phishing, or using a Man-in-the-middle attack. In theory, even if you download the binary from somewhere you trust (like GitHub), an attacker could still potentially intercept and replace your download with their own malware. If you run the binary without verifying that it isn’t malware, you expose yourself to security risks.

Therefore, to protect yourself, you should always verify that your binary is authentic Decred software.

How do you verify that a binary hasn’t been tampered with?

The core concept of file verification relies on hashing. The Decred project takes it a step further and uses GnuPG to sign their hashes. The signature guarantees that the files are distributed directly by Decred.

When the Decred project compiles source code into binaries, each binary is hashed using SHA-256. Each hash is stored in a manifest.txt file. Then the manifest is signed using the Decred project’s public GnuPG key. This creates a unique signature file, ending in manifest.txt.asc.

To check if your downloaded binary is a 100% match to the Decred project’s binary release, you need to do two things:

Verify that the manifest was directly signed by the Decred project: Download the manifest.txt and the signature manifest.txt.asc. Use GnuPG to check the signature against the public Decred release signing key.
- SUCCESS: If the signatures match, you know you can trust that the manifest came directly from the Decred project, and that the hashes inside it are trustworthy.
- FAIL: If the signatures don’t match, then your manifest is not the official Decred project manifest. Do not continue, delete the files you’ve downloaded, and check for security problems before trying again.
Verify that the binary hash matches the manifest hash: Hash your downloaded binary and verify that its hash matches the hash in the Decred project’s manifest.txt.
- SUCCESS: If your hash matches the hash in the manifest, you know you can trust and run the binary.
- FAIL: If your hash doesn’t match, your binary doesn’t match the official Decred project’s binary release, and you should not continue. Delete the binary you’ve downloaded, and check for security problems before trying again.

Detailed Instructions

Preliminary Steps

First, go to the Decred releases page and download:

The binary installer for your specific OS / architecture
The file manifest and hashes, ending in -manifest.txt
The signature for the manifest, ending in -manifest.txt.asc

Also, make sure GnuPG is installed:

On Windows, install GnuPG with the latest version of gpg4win.
On macOS, install GnuPG with the latest version of GPGTools.
On Linux, GnuPG is installed by default.

With GnuPG installed, the following instructions will work from any terminal on Windows, macOS, or Linux/UNIX

Add the Decred project’s release public keys to your GnuPG keyring

You only need to do this step one time, so you can skip this step when verifying later releases on the same computer.

There are several ways to import the Decred release public keys into GnuPG. The most direct method is to use the ASCII Key Block below:

The Decred Release ASCII Key Block (click to expand)

Simply copy that entire text, save it as key.txt, and open a terminal.

In the terminal, use the cd command to navigate to the directory path where you’ve saved key.txt. Then use the gpg --import command.

(Note that Windows uses \ for directory paths, but Linux/macOS use /)

$ cd /path/to/the/key
$ gpg --import < key.txt

You can then delete key.txt.

You could also skip the entire “save it as a file” step and just type gpg --import, press enter so you’re on a new line, then paste the raw text of the key block directly into your terminal. enter again for a new line, Ctrl + Z and enter on Windows or Ctrl + D on Linux, and you’re done.

Example output:

gpg: key 6DF634AA7608AF04: public key "Decred Release <release@decred.org>" imported
gpg: Total number processed: 1
gpg:               imported: 1

Just to confirm, you can check if the Decred release public keys are on your GnuPG keyring:

$ gpg --list-keys release@decred.org

Example output:

pub   rsa4096 2016-01-27 [SC]
      FD13B6835E248FAF4BD1838D6DF634AA7608AF04
uid           [ unknown] Decred Release <release@decred.org>
sub   rsa4096 2016-01-27 [E]
sub   rsa4096 2016-01-27 [S]

Verify that the manifest was directly signed by the Decred project

If you have the Decred project’s release public keys on your GnuPG keyring, you can verify if the signature for the manifest was created by the Decred release signing key.

In a terminal, navigate to where you saved both the manifest.txt and the manifest.txt.asc. Then ask GnuPG to verify the signed manifest, like so:

$ gpg --verify <your manifest.txt.asc file>

For example, if you wanted to verify decred-v1.7.2-manifest.txt.asc:

$ gpg --verify decred-v1.7.2-manifest.txt.asc

Example output:

gpg: assuming signed data in 'decred-v1.7.2-manifest.txt'
gpg: Signature made Wed 11 May 2022 11:41:05 AM EDT
gpg:                using RSA key F516ADB7A069852C7C28A02D6D897EDF518A031D
gpg: Good signature from "Decred Release <release@decred.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: FD13 B683 5E24 8FAF 4BD1  838D 6DF6 34AA 7608 AF04
     Subkey fingerprint: F516 ADB7 A069 852C 7C28  A02D 6D89 7EDF 518A 031D

If you see Good signature from "Decred Release <release@decred.org>", then you’re successful! You can trust that the manifest.txt came directly from the Decred project.

The WARNING shown is not a problem. It just means you haven’t told GnuPG that you want to trust Decred.

Verify that the binary hash matches the manifest hash

Now that you know you can trust the manifest.txt, open it and view the SHA-256 hashes. Find the row for the binary (or zip of binaries) you’re interested in. The first 64 characters are the “correct” hash from the Decred project. You want to check your binary and make sure you get the same hash.

There are many ways to generate a SHA-256 hash, but here are a few:

WindowsmacOSLinux

If you have 7-Zip installed, simply open up Windows Explorer, right click on the binary file, mouseover CRC SHA, then click SHA-256.

In a terminal:

$ certutil -hashfile <your binary file> SHA256

In a terminal:

$ shasum -a 256 <your binary file>

In a terminal:

$ sha256sum <your binary file>

Example output:

ab0c4d53576f4bd486c8c64451edc0b000a5eaae6e18e29e367f24522e11a7c6  decred-linux-amd64-v1.7.2.tar.gz

If your output hash matches the hash from the manifest, you’re done! The binary for your platform is now verified and you can be confident it was generated by the Decred Project. It’s safe to install the software.

Links for further reading

https://gnupg.org/gph/en/manual.html#CONCEPTS

https://alexcabal.com/creating-the-perfect-gpg-keypair