Verifying software downloads on Linux, Windows, and macOS

Don’t care what’s behind the scenes? Skip straight to software verification tutorials for macOS, Linux, and Windows.

Back in the day, software used to arrive in the form of floppy discs, MiniDiscs, and CD-ROMs. But now, it’s all about the download. Everything is downloaded: the apps you use to keep in touch with your family, the video games you use to wind down after work, and probably even the web browser you’re using to read this article.

But this introduces a problem — how do you make sure all this software you’re downloading is authentic?

Well, first thing’s first: you should always make sure you’re downloading software from a trusted source. For Session (and most open-source projects), all our official releases can be found on our GitHub and our website, https://getsession.org. If you really want to, you can even check Session’s code and compile it yourself. That way, you know exactly what your computer is running. 

For the rest of us, you can do something called hash verification. Hash-what, you ask? Well, you can apply a cryptographic hashing algorithm to a piece of information — such as a computer program — and it’ll generate a functionally unique hash. This means that if two different people can generate the same hash, they can verify that they’ve both got the exact same information. 

256 bits of data on the wall: SHA-256

One of the most commonly used hashing algorithm families is the ingeniously named Secure Hash Algorithm 2 (SHA-2), which contains the hashing function SHA-256 (more on that later). 

But, the biggest reason hashes are important is because they’re one-way tickets: you can use any data to generate a hash, but you never use a hash to generate data. 

This means that, for example, if you and a Session developer can generate matching hashes using a version of Session, you’ll know for sure your version is exactly the same as the one shipped by the developer. 

Signed, sealed, delivered: Public key encryption

So, you compared the hash of your version of Session with a hash published by a Session developer, and they matched! Great, but… how do you know it’s really a Session dev that sent you that hash? Verifying online identities can be tricky, but in this case it’s doable using public key encryption — like the one Session uses in its decentralised friend request system. 

GNU Privacy Guard (GPG) allows for the secure transmission of information, and we can use it to verify both the origin of a message, and that its contents haven’t been altered. 

Using GPG encryption, you can sign a piece of information — like a message containing a hash. Once you’ve done that, anybody that has your GPG public key can check to see if it was the real you that signed the message. 

That’s why we always publish signed hashes with all of our releases — so you can rest easy knowing your copy of Session hasn’t been tinkered with. You can find them on our GitHub, or at https://getsession.org/download.

Here’s how you can use those signed hashes to verify your downloads. The process is slightly different depending on which operating system you’re using, so we’ve included guides for Windows, Linux, and MacOS.

Verifying files using GPG on Windows

If you prefer, we’ve also created a video tutorial for verifying files using GPG on Windows. 

0. Download a copy of Session, and then find a message that looks like this:

It’s always located with the release notes on GitHub and under the Signatures button at https://getsession.org. Here’s everything else you’ll need to do:

1. Download and install a trusted GPG utility such as gpg4usb. 

2. Find the public key that signed your download. The public keys of all of our developers are on our GitHub. In this example, the PGP signed message says this at the top: 

The following hashes have been signed for verification using keejef’s GPG keys located in the oxen core repository at https://github.com/oxen-io/oxen-core/blob/master/utils/gpg_keys/KeeJef.asc.

Follow the link in this message. 

3. Copy the entire PGP public key block to your clipboard. 

4. In gpg4usb, click ‘Import Key’ > ‘Clipboard’. 

5. The key import details should appear in a pop-up window. Click ‘OK’. The name of whoever owns the key should appear in the right-hand window. 

6. Tick the checkbox next to this name. 

7. Copy the entire PGP signed message and PGP signature from step 0. 

8. Paste it into the text-box in the left-hand window of gpg4usb.

9. Click ‘verify’. 

10. If the message was signed by the key you imported, a green bar at the bottom of the text-box will appear with the message ‘Text was completely signed by: Kee Jefferys’.

We’ve now successfully verified that the hashes posted with the release were uploaded by Kee — a trusted developer for Session. 

Now we need to check that the hash of your local file matches the hash that Kee generated. 

11. Open a command line — such as Command Prompt, which comes pre-installed with Windows. 

12. Type the following into your command line: 

certUtil -hashfile your_file_path_here sha256

13. Hit enter. Your command line should generate a SHA256 hash. 

14. Compare the hash you generated with the one published in Kee’s signed message. If they match, you’ve successfully verified that your files are the same. 

Done!

Verifying files using GPG on Linux

If you prefer, we’ve also created a video tutorial for verifying files using GPG on Linux. 

0. Download a copy of Session, and then find a message that looks like this: 

It’s always located with the release notes on GitHub and under the Signatures button at https://getsession.org. Here’s everything else you’ll need to do:

1. Find the public key that signed your download. The public keys of all of our developers are on our GitHub. In this example, the PGP signed message says this at the top: 

The following hashes have been signed for verification using keejef’s GPG keys located in the loki core repository at https://github.com/oxen-io/oxen-core/blob/master/utils/gpg_keys/KeeJef.asc.

2. Copy the entire PGP public key block to your clipboard. 

3. Open your command line — such as Terminal. 

4. Type the following and then hit enter: 

gpg --import

5. Paste your clipboard and hit enter.

6. Press ctrl+d, this will import the key you’ve just pasted. Some information should appear about the owner of the key. 

7. Copy the entire PGP signed message and PGP signature from step 0 to your clipboard. 

8. Go back to your command line, type the following, and hit enter: 

gpg --verify 

9. Paste your clipboard and hit enter. 

10. Press Ctrl+D, this will verify that the key you imported signed this message. A message should appear containing ‘good signature’. If it says bad signature, the key you imported did not sign the message.

Hopefully, we’ve now successfully verified that the hashes posted with the release were uploaded by Kee — a trusted developer for Session.

Now we need to check that the hash of your local file matches the hash that Kee generated. 

11. In your command line, type the following and hit enter: 

sha256sum your_file_path_here

12. A SHA256 hash will appear in your command line. Compare the hash you have generated to the one published in Kee’s signed message. If they match, you’ve successfully verified that your files are the same. 

 Done!

Verifying files using GPG on MacOS

If you prefer, we’ve also created a video tutorial for verifying files using GPG on MacOS. 

0. Download a copy of Session, and then find a message that looks like this: 

It’s always located with the release notes on GitHub and under the Signatures button at https://getsession.org. Here’s everything else you’ll need to do:

1. Download and install GPGSuite. 

2. Find the public key that signed your download. The public keys of all of our developers are on our GitHub. In this example, the PGP signed message says this at the top: 

The following hashes have been signed for verification using keejef’s GPG keys located in the loki core repository at https://github.com/oxen-io/oxen-core/blob/master/utils/gpg_keys/KeeJef.asc.

3. Click ‘RAW’, and then save the .asc file to your computer. 

4. Open your command line (such as Terminal), type the following, and hit enter: 

gpg --import your_.asc_file_path_here

5. Right click the ‘gpg: key’ that appears, and then click copy. 

6. Type the following into your command line, then hit enter: 

gpg --fingerprint paste_gpg_key_here

7. You’ve now imported a GPG key. Some information should appear about the owner of the key. 

8. Copy the entire PGP signed message and PGP signature from step 0 to your clipboard. 

9. Type this into your command line and hit enter: 

gpg --verify 

10. Paste your clipboard, hit enter, then hit ctrl+d. A message should appear containing ‘good signature’. If it says bad signature, the key you imported did not sign the message. 

Hopefully, we’ve now successfully verified that the hashes posted with the release were uploaded by Kee — a trusted developer for Session. 

Now we need to check that the hash of your local file matches the hash that Kee generated.

11. In your command line, type the following and hit enter: 

shasum -a 256 your_file_path_here 

12. A SHA256 hash will appear in your command line. Compare the hash you have generated to the one published in Kee’s signed message. If they match, you’ve successfully verified that your files are the same. 

Done!

Verifying software with GPG: Done!

There is a lot to learn in the world of public key encryption. Really, this article just brushes the surface of what you can accomplish with these tools. 

Verifying the software you’re downloading is always important, especially if you’re dealing with something that is going to handle sensitive information — like a private messaging app. Now you can make sure your version of Session is the same as the version we shipped, and relax knowing that nobody in the world can snoop on your messages.