Verifying open source software
In this guide, we walk you through verifying the legitimacy of an open source software package before installation. As the old adage goes, "Check yo sigs before you wreck yo gigs."
Chief Information Security Officer and Director of Digital Security
Public domain photo. CC0 Public Domain
Verifying software should be your first priority whenever you download a new piece of software. If you are downloading software by verified individual developers or an organization like Apple or Microsoft, the verification process is handled for you. However, you may want to use software built by developers who haven’t joined Apple’s or Microsoft’s developer program, and therefore won’t be able to sign their software in the canonical way. We should always be critical before installing “indie” software, but if the project is open source, it’s built around the notion that the software’s source code should be made public and subject to external audits and verification. Open source software verification is a straightforward process that should only take a few minutes, but can save you from a headache in the future.
What will happen to you if you don’t verify your software, you ask? Well, sometimes nothing. Other times, malicious users can infect your device with malware masquerading as the software you presumed you downloaded. You can avoid downloading and infecting your device with duped software by verifying the authenticity of the source.
Before you do anything…
It’s advisable to do thorough research into where the software is being downloaded from. Nefarious actors have gotten very good at tricking either you (or your device!) that the developer site and download are legitimate when they are not.
If possible, you should always download your files from the software developer’s site. If that isn’t possible, the developer should have links to code repositories like Github or Sourceforge visible to you right from their site.
Time to verify
Sometimes, developers only publish a short, strange-looking string that represents the entire software file. A cryptographic hash, or checksum, is the result of a one-way (irreversible) function that takes the software as input, and spits out a unique code as output. Like the fingerprints on our hands, each checksum uniquely represents the corresponding file-- any change to the original file, no matter how tiny, would result in a totally different checksum.
Your computer can compute the checksum of any file fairly easily — all you need to do is open Terminal (Mac users) or Command Prompt (Windows) and type in a basic command. If the resulting checksum from your computer matches the checksum from the developer’s HTTPS-protected website, you can be sure the software file you download is a bit-by-bit replica of what the developer intended to publish.
The following examples demonstrate computing a checksum under the SHA-256 algorithm, which is the industry standard. You might, however, encounter checksums computed with other algorithms, such as SHA-1. While technically weaker, they can also (begrudgingly) be used if necessary — simply replace the algorithm accordingly.
On a Mac
Open Terminal (do a spotlight search, or navigate to Applications >Utilities>Terminal,). In Terminal, type the following, and press enter:
shasum -a 256 /path/to/file.dmg
CertUtil -hashfile \path\to\file.exe SHA256
Here’s a cool tip: If typing the full path of the file you want to hash is too much work, simply drag the file by its icon and drop it into the Terminal or Command Prompt window. The app will immediately fill in the proper path to the file for you.
Verify by PGP
The best way to verify software is to use PGP (Pretty Good Privacy), with its software implementation, GPG. Windows users should use a program called GPG4Win; Mac users have a choice of using GPGTools, or the minified GnuPG suite. This guide will not cover how to install and set-up GPG, but have a look at this excellent guide by EFF to get started.
Note: you do not need your own key to get started verifying, nor do you need to set up PGP for your email. For the purposes of this tutorial, you only need to have the GnuPG software installed.
In order to verify software with GnuPG, you first need three things:
- Software file (normally a .exe or .dmg file)
- Signature file (a .sig or .asc file)
- Public developer key (an .asc file)
It’s important to note that it’s not always obvious where these things are, but often you can find them on the release notes on the developer’s site. It sometimes feels like a scavenger hunt; you just have to keep at it.
Here’s an example of how we found the right information to verify the open-source encryption utility, VeraCrypt.
2. Find the PGP signature
This developer also had a handy link to the signatures right from the download page, which is very thoughtful. The signature file is named after the software file, with the only difference being the .sig file extension appended to the end. Download this file into the same folder as the software you downloaded in the previous step.
3. Find the developer’s public key
While the developer also links to their key right from their website, it’s better to corroborate this information using a public keyserver. If you’d like to be more certain of the authenticity of the developer key, you can cross-reference the 40-character fingerprint you have uploaded onto your keyring with results on multiple keyservers, such as MIT PGP keyserver and OpenPGP keyserver.
Choosing MIT’s keyserver, I did a search for the key by its fingerprint (the 40-character string, preceded by 0x , that’s published there). Please note, the full 40-character fingerprint should always be prefered, but you might encounter a truncated string with the last 16 characters of a fingerprint; this is called the “long ID” of the same key, and at current writing, is generally good enough to identify the entire key.
With all the parts assembled, it’s time to verify.
On a Mac
Import the developer’s public key into your GPG keychain. You can right-click on the PGP key link from the project's download page and select Save Link As…, then right-click on the downloaded key, select Services > OpenPGP: Import Key from File. You can also visit a public keyserver to download and manually import the key file.
Next, right-click on the software file, scroll to Services in the context menu, and select OpenPGP: Verify signature of file.
If you get a message reading: “Warning: Invalid signature”, then the software you downloaded is not properly signed by the developer’s key. It isn’t advisable to install this software; either double-check your process and try verifying again, or trash the software completely and try another avenue.
If the software file is properly signed, you will see a “Signing Key...” result, with the name, email address, and key signature of the developer. If you get a message reading “Untrusted signature”, check the developer’s public key again. Have you confirmed that the 40-character fingerprint for this key matches, and indeed belongs to the developer? If so, the software is legitimately signed by the developer, but you just haven’t yet established trust with the developer’s key in your keyring. You may still proceed with the installation.
On Windows
Import the developer’s public key into your GPG keychain. You may need to right-click the link for the developer’s public key and select Save Link As to download it as a file instead of opening it in the browser. Right-click on the downloaded developer public key file, scroll to More GpgEX options in the context menu, and select Import keys.
Next, right-click on the software file, scroll to More GpgEX options in the context menu, and select Verify.
If you get a message in red reading: “Invalid signature...”, then the software you downloaded is not properly signed by the developer’s key. It isn’t advisable to install this software; either double-check your process and try verifying again, or trash the software completely and try another avenue.
If you get a message reading: “The data could not be verified. Signature created on … With certificate ... The used key is not certified by you or any trusted person,” check the developer’s public key again. Have you confirmed that the 40-character fingerprint for this key matches, and indeed belongs to the developer? If so, the software is legitimately signed by the developer, but you just haven’t yet established trust with the developer’s key in your keyring. You may still proceed with the installation.
Why don't we have both?
Sometimes, developers use both checksums and signature files to offer verification. The idea here is, instead of signing the software with their key, the developer will sign a (significantly smaller) text file that lists the checksums of the software you should download. That way, if the software you download has a checksum that matches what’s written in the signed text file, you can equally trust the provenance of the software.