1. What's the Point?
With viruses and many other fiendish means of attack on computer networks today, it is important to verify that the software you are downloading was not modified along its journey from an Internet host to your computer. Fortunately, there is a very robust software package for this: GNU Privacy Guard, also known as "GnuPG" or just "GPG"/"gpg". GnuPG uses modern cryptographic techniques to allow software authors to digitally sign their packages so that others can verify that they have received an authentic copy.
"GPG" is a play on "PGP" ("Pretty Good Privacy"), which was developed in the 1990s by cryptographer Phil Zimmermann. GnuPG is an implementation of OpenPGP, which is an Internet standard. GnuPG offers two broad categories of encryption: bulk data encryption and digital signatures. The category this page discusses is GnuPG's digital signature mechanism. This allows Internet users to verify that a digitally signed file transferred over the Internet (say from a public web server to your computer) was created by the intended author and was received uncorrupted.
As an example of how easy it is to use GnuPG once your system has
it installed and configured, suppose you have downloaded a software
package from the Internet as a compressed tarball with filename
superball-1.0.tar.gz along with its GnuPG signature file,
superball-1.0.tar.gz.sig. With both files saved in the
same directory on your computer, you can verify the authenticity of
the superball-1.0.tar.gz file in a terminal window
from that directory with this command:
gpg --verify superball-1.0.tar.gz.sig
GnuPG would respond by telling you whether or not the .sig
file contained a valid signature for the superball-1.0.tar.gz
tarball.
Without going into technical details, software authors (or authors of any other kinds of files) who use GnuPG use it to create their own keys using a password they choose, which they keep to themselves. When they do this, GnuPG will create a public key and a private key. The author can give the public key to the world, but the secret key remains private with that author.
Anyone who has the public key can verify the cryptographic signature
of a file. You do this by first importing that developer's
public key into the keyring of your copy of GnuPG. Signature
files usually have an extension of ".sig" or
".asc". Source software packages usually are compressed
archive files with an extension like ".tar.gz".
Note that in this document, "GnuPG" refers to the GNU Project's
GNU Privacy Guard package and "gpg" refers to the
binary command that invokes GNU Privacy Guard.
2. Getting GnuPG
Of course, to run GnuPG you first have to have it installed on your computer. You also have to have the "public key" of the person who signed the tarball, stored in your GnuPG keyring. The good news is that once you have a copy of GnuPG installed, it tries to make the rest of the process easy for you.
If your operating system distribution already includes GnuPG through
a secure packaging system, use that version. Most GNU/Linux and BSD
operating system distributions include GnuPG as part of their
infrastructure. It should appear on your system as "gpg",
or possibly for GnuPG version 2 as "gpg2".
If not already installed, follow the instructions in the rest of
this section to obtain a copy whose integrity you can trust.
The most important thing is to have a copy of GnuPG that you can trust. If you are running an operating system distribution that includes GnuPG on its distribution media, that is probably a good way to "bootstrap" GnuPG on your system. If you do not have such media for your system, you can download GnuPG over a secure (encrypted) web connection, from
Note the secure HTTPS web address. As a safeguard against tampering, it is important to download any GnuPG package and its associated signature file over a secure, encrypted Internet connection such as the HTTPS protocol provides.
3. Verifying Your Copy of GnuPG Before You Use It
It's a great idea to verify the downloaded image in more than one way if
possible. The GnuPG website has checksums for its downloadable files
available in various formats: SHA-1, SHA-256, and possibly others at
the time of your download. GnuPG also has its own signature
(.sig) files, but you need a working copy of GnuPG
installed to verify with them.
The GNU coreutils package offers programs for many types
of checksums, including SHA-1 and SHA-256, which are provided for files
on the GnuPG web page
At the time of this writing, the bottom of that page contained SHA-1 checksums for each of the GnuPG packges available on that website.
If your system does not already have programs such as
sha1sum and sha256sum installed, you can
find them in the GNU coreutils package. GNU/Linux system
distributions, Cygwin on Windows, and other systems will probably
install those programs in a "developer" system installation option.
Cygwin and GNU/Linux distributions will typically install gpg
in the /usr/bin directory. FreeBSD and other systems
might install gpg in the /usr/local/bin
directory.
On MacOS, you can install coreutils with the homebrew
package (which you have to download separately), using the command
brew install coreutils
That package will install the GNU checksum programs in
/usr/local/bin with a 'g' in front of each program name:
/usr/local/bin/gsha1sum,
/usr/local/bin/gsha256sum, etc. You can rename them to
their standard names if you like:
/usr/local/bin/sha1sum,
/usr/local/bin/sha256sum, etc.
Otherwise, you can download the coreutils source package
from a GNU repository mirror near you by going to
Once GNU coreutils is installed, as an example you would
simply type
sha1sum gnupg-2.2.9.tar.bz2
to compute the SHA-1 checksum of the gnupg-2.2.9.tar.bz2
file. Then make sure that the letters and digits (a 40-digit hexadecimal
number) that sha1sum prints out match what appears on
the GnuPG webiste for that file.
4. Installing GnuPG on Your System
How you compile (if necessary) and install GnuPG depends upon the
system you are using. If you use a packaging system
(.deb files for Debian GNU/Linux and its derivatives,
.rpm files for Red Hat GNU/Linux and its derivatives,
Cygwin on Windows or homebrew on MacOS, for example), the package
name will probably be "gpg", and those package managers
should install the binary gpg program for you.
Otherwise, compile and install the software as you would other source
packages that follow the GNU Coding Standards.
The rest of this web page will assume that you have installed
gpg on your system, hopefully after verifying it
by a file checksum you obtained from the GnuPG website.
5. Verifying GnuPG with GnuPG
Once you have installed GnuPG, use it to verify the GnuPG package that you downloaded. There are two steps to this: first copying and importing the GnuPG public keys used to sign GnuPG, then using those imported keys to verify signatures. This section describes those two steps.
5a. Importing the GnuPG Public Signing Keys
First, obtain the signing keys directly from the GnuPG website on this web page:
Note again that you are downloading that web page over an encrypted HTTPS link. There is an "ASCII-armored" copy of the various public keys used to sign versions of GnuPG over the years, as described on that web page. That block begins with the line
-----BEGIN PGP PUBLIC KEY BLOCK-----and ends with the line
-----END PGP PUBLIC KEY BLOCK-----
Copy that entire block of text, including all of the "BEGIN" and "END"
lines shown above, into a file on your computer. The convention
is to save such an "ASCII-armored" key in a file with an extension
of ".asc". For example, suppose you save it in the file
"gnupg-sigs.asc". Then import the key into your
computer's GnuPG keyring with the command
gpg --import gnupg-sigs.ascGnuPG should output something like this:
gpg: key 4F25E3B6: public key "Werner Koch (dist sig)" imported
gpg: key 33BD3F06: public key "NIIBE Yutaka (GnuPG Release Key) <gniibe@fsij.org>" imported
gpg: key E0856959: public key "David Shaw (GnuPG Release Signing Key)" imported
gpg: key 4B092E28: public key "Andre Heinecke (Release Signing Key)" imported
gpg: Total number processed: 4
gpg: imported: 4 (RSA: 4)
GnuPG has now saved those public keys in the keyring that it maintains on your computer. Each time you want to verify a file signature from a new developer, you will import that developer's key into GnuPG.
You can list the keys that are in the keyring that GnuPG saves on your computer with the command
gpg --list-keysand if you imported the above public key block correctly, you should see an output that contains messages like this:
pub 2048R/4F25E3B6 2011-01-12 [expires: 2019-12-31]
uid [ unknown] Werner Koch (dist sig)
pub 2048R/33BD3F06 2014-10-29 [expires: 2020-10-30]
uid [ unknown] NIIBE Yutaka (GnuPG Release Key) <gniibe@fsij.org>
pub 2048R/E0856959 2014-10-29 [expires: 2019-12-31]
uid [ unknown] David Shaw (GnuPG Release Signing Key)
pub 3072R/4B092E28 2017-03-17 [expires: 2027-03-15]
uid [ unknown] Andre Heinecke (Release Signing Key)
If you do not see entries from those four signers, you have not imported the ASCII-armored public key block correctly; review the instructions and try again.
5b. Verifying GnuPG with the Keys You Imported
Once you have the signature file and the file that it is associated with in the same directory, and you have the public key of the person who created those files imported into your GnuPG keyring, you are ready to use GnuPG to verify the GnuPG package you downloaded.
Download a file and its signature file from
https://gnupg.org/download/.
For example, suppose you download the source tarball from the table
entry with name GnuPG, and the tarball filename is
gnupg-2.2.9.tar.bz2. Also download its signature file,
which would have the name gnupg-2.2.9.tar.bz2.sig.
Then, in a terminal window in that directory, type the command
gpg --verify gnupg-2.2.9.tar.bz2.sig gnupg-2.2.9.tar.bz2
Note that the signature file and the original tarball file are
explicitly given to GnuPG in this example. You could just provide
the name of the ".sig" file (in this case,
"gnupg-2.2.9.tar.bz2.sig"), but with GnuPG it pays not
to take any shortcuts. The one package you have to be most confident
about downloading uncorrupted is GnuPG. If you have a good copy
of GnuPG installed on your system, it should be able to detect corruption
in any other package file that has a GnuPG signature file; if you have a
corrupted copy of GnuPG installed, you cannot be certain of the
integrity of any signed file on your system.
If everything goes well, gpg should output a message
similar to this:
gpg: assuming signed data in 'gnupg-2.2.9.tar.bz2'
gpg: Signature made Thu Jul 12 06:20:56 2018 PDT using RSA key ID 4F25E3B6
gpg: Good signature from "Werner Koch (dist sig)" [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: D869 2123 C406 5DEA 5E0F 3AB5 249B 39D2 4F25 E3B6
gpg: Signature made Thu Jul 12 17:59:11 2018 PDT using RSA key ID 33BD3F06
gpg: Good signature from "NIIBE Yutaka (GnuPG Release Key) <gniibe@fsij.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: 031E C253 6E58 0D8E A286 A9F2 2071 B08A 33BD 3F06
If gpg indicates that the signature is good, with files
and the ASCII-armored public key block you downloaded from the GnuPG
website over a secure HTTPS connection, then your verification of the
GnuPG file you downloaded is likely to be valid.
If gpg instead outputs a message containing
gpg: Can't check signature: No public key
or a similar error message, first check that you have typed in the
filename correctly. If you have, then either you have not imported
the public key block correctly or one or both of the files you downloaded
is corrupted. The gpg --list-keys command shown above
should have verified that you imported the public keys correctly into
your computer's GnuPG keyring. In that case, try downloading the
file you want to use and its signature file again.
6. Now That You Have Installed GnuPG
Once you have installed GnuPG and have verified the integrity of
the copy you installed by its GnuPG ".sig" signature file,
you can verify other files, including documents whose authors have
signed them with GnuPG.
You might want to start by verifying the copy of the GNU
coreutils package if you had to install that on your computer.
For example, if you downloaded these files:
coreutils-8.30.tar.xz
coreutils-8.30.tar.xz.sig
into a directory, you could go to that directory in a terminal window and then type
gpg --verify coreutils-8.30.tar.xz.sigNotice that you have not downloaded the public key of the developer who created the package. In this case, GnuPG should try to download the key from a public key server, and you should see output similar to this:
gpg: assuming signed data in 'coreutils-8.30.tar.xz'
gpg: Signature made Sun Jul 1 18:41:43 2018 PDT using RSA key ID 306037D9
gpg: requesting key 306037D9 from hkps server hkps.pool.sks-keyservers.net
gpg: key 306037D9: public key "Pádraig Brady <P@draigBrady.com>" imported
gpg: WARNING: signing subkey 851EAD06 is not cross-certified
gpg: please see https://gnupg.org/faq/subkey-cross-certify.html for more information
.
.
.
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 2u
gpg: depth: 1 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 1f, 0u
gpg: next trustdb check due at 2018-08-19
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
gpg: Good signature from "Pádraig Brady <P@draigBrady.com>" [unknown]
gpg: aka "Pádraig Brady <pixelbeat@gnu.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: 6C37 DC12 121A 5006 BC1D B804 DF6F D971 3060 37D9
If GnuPG is able to find a key on a public key server, it will
automatically download it, add it to your computer's GnuPG keyring,
and then try to verify the signature of the assiciated file. In this
case, GnuPG was able to find the developer's public key on the server
"hkps.pool.sks-keyservers.net", download it, add it
to your computer's GnuPG keyring, and use the downloaded key to
verify the integrity of the coreutils-8.30.tar.xz package.
If GnuPG responds with a message saying the signature is good, you can probably trust the integrity of a downloaded file.
You can also verify package files from the public download directory
on this webiste (http://unifoundry.com/pub/ or https://unifoundry.com/pub/)
with GnuPG. For example, suppose you download version 1.0 of the
utf8gen package.
You can place these two files in the same directory:
utf8gen-1.0.tar.gz
utf8gen-1.0.tar.gz.sig
You can use the same technique to have GnuPG search the Internet for
Paul Hardy's public key on a public key server. Or, for extra
precaution, you can copy the ASCII-armored public key directly
from this website at
/1A09227B1F435A33_public.asc
and import it into GnuPG with the "gpg --import"
command as described above. Then you are ready to verify the
packages on this website.
Then go to the directory where the utf8gen "tar"
file and its ".sig" signature file are located in a terminal
window and type
gpg --verify utf8gen-1.0.tar.gz.sig7. Adding All GNU Project Package Maintainer Keys
The GNU Project distributes numerous free software packages. They form the bulk of many operating system distributions, such as GNU/Linux. To download all keys of GNU Project package maintainers in one file, do one of the following:
- In a browser, go to the web address
https://ftp.gnu.org/gnu/. Then right-click on the file "gnu-keyring.gpg" in that directory and save it to your local disk, or -
In a terminal window, type the command
"
wget https://ftp.gnu.org/gnu/gnu-keyring.gpg", or -
In a terminal window, type the command
"
curl https://ftp.gnu.org/gnu/gnu-keyring.gpg -o gnu-keyring.gpg".
Note that the downloading is done from an HTTPS address; do not use ordinary FTP for this download as it is not secure.
Now import the file into your local GPG public keyring in a terminal window with this command:
gpg --import gnu-keyring.gpg
GnuPG will list all of the public keys it is adding; there are
over 500 keys in the file at the time of this writing. When
the import has finished, GnuPG will exit with a summary.
Your system now has all it needs for you to verify all GnuPG keys
in every GNU Project package that appears in the
https://ftp.gnu.org/gnu/ directory.
More Info
You can see the latest news, find online documentation, and learn a lot more about GnuPG on the Free Software Foundation's The Gnu Privacy Guard Wiki Page
