Software Verification

Don’t trust, verify.

File Integrity

When we download a software package from the Internet, we want to ensure that the file hasn’t been corrupted. We can verify the integrity of a downloaded file by using a checksum.

A checksum is a fingerprint of a file’s contents. The change of a single bit in the file will produce a different checksum.

The developer publishes the checksum of the software package in a corresponding checksum file for us to download and compare.

We calculate the checksum of the package after download. If our checksum matches the developer’s checksum, we know that the software has arrived intact.

Each line in a checksum file contains the checksum of a software package, followed by the name of the corresponding package. Checksum files often contain several entries, one for each downloadable file in the release.

Most software projects publish SHA-256 cryptographic checksums. We will use the sha256sum command-line utility to calculate them.

File Authenticity

We also want to ensure that the software package is genuine, and that a bad actor hasn’t tampered with it or replaced it.

A software developer vouches for the authenticity of a file by digitally signing it with his private key. We verify the authenticity of that file using the corresponding public key.

The developer digitally signs the software package’s checksum file rather than the software package itself. Because the checksum uniquely identifies the contents of the software package, signing the checksum file effectively signs the software package itself.

The developer publishes three files: the software package, its checksum file, and the digital signature of the checksum file.

Along with the above three files, we’ll also need the software developer’s public key.

To verify the signature, we need the developer’s public key. For security, the public key is usually published separately from the software download page, often in multiple locations. If a hacker compromises the download page, he might be able to replace the software package, its checksum file, and the signature file. But it’s less likely that he would also be able to replace the public key everywhere that it has been published.

We will use the gpg command-line utility as our file verification tool.

Example

An example will make it clearer.

MySoftware releases version 3.2.1 of its software package, my-soft-3.2.1.tar.gz.

First, the developer calculates the package's SHA-256 checksum:

sha256sum my-soft-3.2.1.tar.gz

The command outputs a checksum followed by the filename:

dcf1873f2208ba4f962f3398d47e154c39c0084be8f4553e05c940d0ace3d004  my-soft-3.2.1.tar.gz

The developer places this line in a checksum file, commonly named SHA256SUMS, together with the checksums of any other files in the release.

After downloading the software package, we calculate its checksum:

sha256sum my-soft-3.2.1.tar.gz

If the checksum matches the one in SHA256SUMS, we know that the file arrived intact.

More commonly, we let sha256sum perform the comparison for us:

sha256sum --ignore-missing --check SHA256SUMS

The --check option reads the entries in SHA256SUMS, looks for matching filenames in the current directory, calculates their checksums, and compares them with the published values.

If the checksums match, you'll see:

my-soft-3.2.1.tar.gz: OK

We have now verified the integrity of the downloaded file.

The developer also digitally signs the checksum file using his private key. The signature is typically stored in a file named SHA256SUMS.asc.

We need the developer's public key to verify the signature.

Look for the public key on the project's Security, Verify, or Release Signing Keys page. The project documentation will usually tell you where to find it. Some projects also publish their public keys on OpenPGP key servers such as keys.openpgp.org.

When you located the key, right-click the link to copy its address.

Then download it by pasting the copiedlink after wget:

wget https://example.org/keys/developer.asc

Import it into GnuPG's keyring:

gpg --import developer.asc

Alternatively, you can download and import it in one step using curl:

curl -fsSL https://example.org/keys/developer.asc | gpg --import

With the public key now in GnuPG's keychain, we can verify that the checksum file was signed by the developer:

gpg --verify SHA256SUMS.asc SHA256SUMS

The gpg command looks in the signature file (SHA256SUMS.asc) for the key’s identifier. It uses the identifier to check if the corresponding key is in its keychain. If it finds it, it uses the key to check that the signature on the SHA256SUMS file is valid.

If the signature is valid, you'll see a message similar to:

gpg: Good signature from "Developer Name <developer@example.com>"

This tells us that the checksum file was signed by the holder of the corresponding private key. Since we have already verified that our downloaded software matches the checksum file, we have also verified the authenticity of the software package.