verifying-signatures.md

Verifying digital signatures

What is a digital signature?

A digital signature is a small segment of text that, like a traditional "physical" signature with a pen on paper, represents the certification of a given document or file. In the same way that a person might sign their name at the end of a letter, software developers will sometimes "sign" their applications and make those digital signatures available for download – typically in the form of small ".asc" or ".sig" files offered alongside the main application. Generally speaking, whenever a developer provides links to digital signature files, it is a good idea to download them with the application and to verify them before running the associated application.

Unlike signatures made with a pen on paper, digital signatures, when correctly implemented, are extremely difficult to forge. Because proper digital signatures rely on public-key cryptography, only persons who posses the "signing key" that corresponds to a particular identity can generate digital signatures on behalf of that identity. Mallory, for instance, cannot sign files using Bob's identity unless she also possesses Bob's privately-held signing key; so long as Bob is the only person in possession of his signing key, it is reasonable to assume that any files digitally signed by Bob's key came from Bob himself.

Why are digital signatures important?

While a letter signed with a pen on paper might provide a weak indication of that letter's authenticity, digital signatures, when used correctly, can provide stronger, cryptographic proof of a file's authenticity as well as its integrity. In other words, a properly verified signature provides a high degree of assurance both a) that the file in question came from the person(s) who signed it and b) that the file in question has not been altered after the fact. The act of verifying a digital signature can thus allow users detect whether or not an application has been forged or tampered with by potentially-malicious third parties.

It is important to note, however, that verified digital signatures provide no guarantee that the underlying application is not malicious, nor that it is free of bugs. It may be possible, for example, for an especially determined attacker to compromise the computer of a software developer and proceed to "sign" malicious applications on their behalf or to insert malicious code into another program or computer upon which an application might depend. In the case of Gridsync, measures have been taken to drastically reduce the likelihood of the first type of compromise (in this case, by generating the original Gridsync Release Signing Key on a computer that is unable to connect to the Internet and requiring a unique write-only hardware device to sign subsequent releases), however, it remains possible that malicious code or "backdoors" could still be inserted into the application through other means (for example, by a sophisticated attacker who might stealthily compromise one of the dedicated machines currently used for building and distributing the application). Accordingly, it is ultimately up to the user to decide whether or not any given application should be considered "trusted" independently of the presence of a verified digital signature.

How do I verify a digital signature?

The process of verifying a digital signature for the first time requires three steps: 1) downloading and installing an application that can verify digital signatures (typically GnuPG), 2) importing the developer's public signing key, and 3) verifying that the signature of the application was generated by the developer's signing key.

Step 1: Installing GnuPG

If you don't already have it, you will need to download and install GnuPG or another reputable/compatible application that can verify OpenPGP signatures. The specific application you install depends on your underlying operating system:

• For Windows: Download and install Gpg4win
• For macOS: Download and install the GPG Suite or use Homebrew to install the gnupg package
• For GNU/Linux: Use your distribution's package manager to install the gnupg package

Step 2: Importing the developer's public key

With GnuPG already installed, the Gridsync Release Signing Key can be imported directly with the following command:

• For Windows: "C:\Program Files\Gnu\GnuPg\gpg.exe" --keyserver keyserver.ubuntu.com --recv-keys 0xD38A20A62777E1A5
• For macOS or GNU/Linux: gpg --keyserver keyserver.ubuntu.com --recv-keys 0xD38A20A62777E1A5

In order to ensure that the key has been imported successfully, you can run the following afterward:

• For Windows: "C:\Program Files\Gnu\GnuPg\gpg.exe" --fingerprint 0xD38A20A62777E1A5
• For macOS or GNU/Linux: gpg --fingerprint 0xD38A20A62777E1A5

This should display output containing the following lines:

pub   rsa4096/0x2777E1A5 2017-06-28 [SC] [expires: 2022-06-27]
      Key fingerprint = D2E7 EFD9 B780 8437 D91E  CD13 D38A 20A6 2777 E1A5
uid           [ unknown] Gridsync Release Signing Key

If the "Key fingerprint" line above matches what you see on your computer, the key has been successfully imported.

Step 3: Verifying the signature

To verify a digital signature for Gridsync, you should download both the standard application package for your operating system (e.g., "Gridsync-macOS.dmg" for macOS) as well as the associated ".asc" digital signature file (e.g., "Gridsync-macOS.dmg.asc").

Assuming that both of these files have been placed into your home folder (and that you've already imported the Gridsync Release Signing Key in step 2 above), you can verify the application's signature by issuing one of the following commands:

• For Windows: "C:\Program Files\Gnu\GnuPg\gpg.exe" --verify Gridsync-Windows-setup.exe.asc Gridsync-Windows-setup.exe
• For macOS: gpg --verify Gridsync-macOS.dmg{.asc,}
• For GNU/Linux: gpg --verify Gridsync-Linux.tar.gz{.asc,}

If you have placed these files elsewhere (for example, in your local "Downloads" folder), you will have to modify the command above accordingly (e.g., replacing "Gridsync-macOS.dmg" with "Downloads/Gridsync-macOS.dmg" and so on).

Among the output from this command, you should see the the following lines:

gpg: Good signature from "Gridsync Release Signing Key" [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: D2E7 EFD9 B780 8437 D91E  CD13 D38A 20A6 2777 E1A5
gpg: binary signature, digest algorithm SHA512, key algorithm rsa4096

The "Good signature" line (and matching "fingerprint" below it) indicates that the digital signature has been successfully verified, i.e., that the application on your computer is identical to the one originally signed by the developer's key (note that the "WARNING" line above simply indicates that you have not yet assigned a "trust index" to the Gridsync Release Signing Key with GnuPG; GnuPG will still correctly verify signatures for keys that you have not yet trusted). If this line reads "Bad signature" instead, your application has been corrupted in some way (whether by a potential attacker or, more likely, a download that simply failed to complete) and should not be installed or run on your computer.