GPG Quick Start
A quick HOWTO for getting started with GnuPG.
First published on July 7, 2004
Last updated on October 7, 2016
A colleague at work once asked me how to get started using
GNU Privacy Guard. He had no experience with it
at all. Here’s a slightly expanded version of what I told him.
Private and public keys are at the heart of
gpg’s encryption and
decryption processes. The best first step is to create a key pair for
Generate a private key.
You’ll have to answer a bunch of questions:
What kind and size of key you want; the defaults are probably good enough.
How long the key should be valid. You can safely choose a non-expiring key for your own use. If you plan to use a key for public signing, you might want to consider a yearly expiration.
Your real name and e-mail address; these are necessary for identifying your key in a larger set of keys.
A comment for your key, perhaps to distinquish a key used for special tasks like signing software releases. The comment can be empty.
A passphrase. Whatever you do, don’t forget it! Your key, and all your encrypted files, will be useless if you do.
You might also want to register your key with public keyservers so that others can retrieve your key without having to contact you directly.
First up, you need to identify your key's ID or fingerprint. The former is easier to use, the latter a bit more secure.
In the example below,
- the ID is 8F54CA35; it's on the line marked pub;
- the fingerprint is 00E5 2D6D 91C0 20D0 F596 2CC5 1E36 9C62 8F54 CA35.
[~]$ gpg --fingerprint heinlein pub 1024D/8F54CA35 2000-11-10 Key fingerprint = 00E5 2D6D 91C0 20D0 F596 2CC5 1E36 9C62 8F54 CA35 uid Paul Heinlein <firstname.lastname@example.org> uid [jpeg image of size 3853] uid Paul Heinlein (Galois, Inc.) <email@example.com> sub 1024g/6088B91E 2000-11-10
To send them, you'll need to locate a public key server. MIT's is well known, but there are others.
# using ID (GnuPG versions 1 and 2) gpg --keyserver pgp.mit.edu --send-keys '8F54CA35' # using fingerprint (GnuPG version 2 and higher) gpg --keyserver pgp.mit.edu \ --send-keys '00E5 2D6D 91C0 20D0 F596 2CC5 1E36 9C62 8F54 CA35'
You may also want to generate an ASCII version of your public key for distribution by e-mail or posting on a web site.
gpg --armor --output pubkey.txt --export 'Your Name'
Encrypting a file for personal use
Encrypting files for your personal use is quite easy.
Encrypt a file called
foo.txt. The argument to the
option should be the all or part of the name you used when generating
your private key.
# the long version gpg --encrypt --recipient 'Your Name' foo.txt # using terse options gpg -e -r Name foo.txt
The encrypted version of the file will by default be named
foo.txt.gpg. You can modify that behavior using the
Decrypt the encrypted file. You’ll be asked to provide the passphrase
you used when generating your private key. If you don’t use the
--output option, the contents of the encrypted file will be sent to
gpg --output foo.txt --decrypt foo.txt.gpg
If you have an encrypted file that you think you’ll want to edit on a regular basis, you might consider using the gnupg.vim plugin for transparently editing gpg-encrypted files.
A more DIY approach can use
make to automate the process of viewing
and editing your encrypted file. Here’s an example
Makefile (to use
it, you’ll need to make sure that the leading whitespace in the targets
is composed of Tabs, not ordinary spaces). The example assumes that
foo.txt is the name of the unencrypted version of your file.
# example Makefile for viewing/editing an encrypted file GPGID = firstname.lastname@example.org FILEPLAIN = foo.txt FILECRYPT = $(FILEPLAIN).gpg GPG = gpg RM = /bin/rm -i VI = vim all: @echo "" @echo "usage:" @echo "" @echo "* make view -- to see $(FILEPLAIN)" @echo "* make edit -- to edit $(FILEPLAIN)" @echo "" edit: @umask 0077;\ $(GPG) --output $(FILEPLAIN) --decrypt $(FILECRYPT) @$(VI) $(FILEPLAIN) @umask 0077;\ $(GPG) --encrypt --recipient $(GPGID) $(FILEPLAIN) @$(RM) $(FILEPLAIN) view: @umask 0077; $(GPG) --decrypt $(FILECRYPT) | less
Encrypting a file for someone else
The really cool thing about GnuPG is that you can safely encrypt files for others using publicly available keys.
Import your friend’s key, which you might have received via e-mail or on
a floppy. If the file is named
key.asc, then just use the
option to add it to your keyring:
gpg --import key.asc
That’s it! You can verify the import using the
Alternatively, you might be able to find your friend’s key on a public keyserver. Here’s what a session looks like when someone searches for my key.
[~]$ gpg --keyserver pool.sks-keyservers.net --search-keys 'paul heinlein' gpg: searching for "paul heinlein" from hkp server pool.sks-keyservers.net (1) Paul Heinlein <email@example.com> 1024 bit RSA key 8F54CA35, created: 2014-06-16 (revoked) (2) Paul Heinlein <firstname.lastname@example.org> Paul Heinlein <email@example.com> Paul Heinlein <firstname.lastname@example.org> Paul Heinlein (Galois, Inc.) <email@example.com> 1024 bit DSA key 8F54CA35, created: 2000-11-10 Keys 1-2 of 2 for "paul heinlein". Enter number(s), N)ext, or Q)uit > Q [~]$
A few notes on this:
- The first result (marked “revoked”) was the result of a failed test I conducted. You can ignore it.
- My key has several e-mail addresses attached to it. That’s perfectly normal.
- In the example above, I chose the
Q)uitoption. Had I pressed
2, that key would have been downloaded and added to my local keyring.
Once you’ve got the other person’s public key, encrypt a file using it.
gpg --encrypt --recipient 'firstname.lastname@example.org' foo.txt
You’ll end up with a file called
foo.txt.gpg that you can send as an
e-mail attachment or make available for downloading via ftp or the web.
Decrypting a file from someone else
If someone sends you an encrypted file, the file has typically been encrypted using your public key. Decrypting it is no different than decrypting a file you’ve encrypted for your own use.
gpg --output foo.txt --decrypt foo.txt.gpg
GnuPG can come in handy when you want to be assured that the file you’ve just downloaded is the one its creator wants you to have. The OpenVPN developers, for instance, release GnuPG signatures for all their downloads.
To verify a file using its detached signature, you must first have
imported the signer’s public key. Assume we’ve downloaded
crucial.tar.gz and the developers have also released a signature file,
crucial.tar.gz.asc. Once you’re confident that you have the
developers’ public key in your local keyring, then the verification step
gpg --verify crucial.tar.gz.asc crucial.tar.gz
Creating a detached signature is similarly easy. The following example
will create a signature for
gpg --armor --detach-sign your-file.zip
People who have imported your public key into their keyrings can then verify that their version of your file is identical to theirs.
Basic Key Management
After a while, you will probably have several keys in your ring. It’s easy to list them all:
Should you lose trust in or contact with a person with a key in your ring, you’ll want to delete it:
gpg --delete-key 'email@example.com'
For further reading
To move beyond these simple instructions, consult the GnuPG Documentation.