GNU Privacy Guard (GnuPGP / GPG)

This page describes usage of GnuPG, for the specific purpose of encrypting files (for yourself - e.g. as part of a backup strategy). The Online GPG Project Documentation is excellent, and contains a lot more detail.

Wikipedia has a great article about how public-key cryptography works.

Borrowed and abbreviated from the excellent gnupg.org:

GnuPG is the GNU project's complete and free implementation of the OpenPGP standard as defined by RFC4880. GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications.

GnuPG is Free Software (meaning that it respects your freedom). It can be freely used, modified and distributed under the terms of the GNU General Public License.

As mentioned, GPG is very well-documented - see the Online Documentation Overview as well as the Manual, the GNU Privacy Handbook and the GPG manpage.

This page is based on GnuPG 1.4.9.

Options

The GPG commandline tool is very flexible, and provides options for doing many things. The following describes encryption (and decryption) options , options useful for scripting, and key management options, as well as an example of basic usage.

Encryption Options

These are the options which are useful in basic usage of GPG for encryption (and decryption) - see also the example of basic usage.

A brief summary of useful options for the GPG commandline tool. The focus is on encrypting and decrypting files.
Option	Description
--symmetric file	Encrypts the file with a passphrase, without the need for neither public nor secret keys - this is less secure, but a lot simpler: # encrypt to .bashrc.gpg, prompting for passphrase gpg --symmetric .bashrc # decrypt to stdout gpg --decrypt .bashrc.gpg
--local-user <name>	Use this to specify the user-id which identifies the sender (i.e. yourself). Without this option, gpg will use the default key, if specified, or the first key in the keyring. gpg --local-user test1 ...
--recipient <name>	Use this to specify the user-id of the recipient - without a specified user-id, GPG will prompt. There are many ways to specify a user ID, see the manpage ("How to specify a user ID") for details. The simplest (and also the default) is to specify a string that occurs in the ID and is unique in the local keyring, e.g. gpg --recipient 'backup' ... If the username is simple, it can be specified as an exact match using =user-id, e.g. gpg --recipient '=backup-test' ...
--encrypt [file]	Encrypt the file. Unless provided as options, this will prompt for the parameters required to perform the encryption: user-id, passphrase, etc. Writes to file.gpg, unless a filename is provided using --output . Anybody can encrypt files using anybody else's public key, just encrypting provides no guarantees about the origin of the file.
--sign [file]	Sign the file, using your secret key. Use the --local-user option to specify which secret key to use. A signed file is still readable by anybody who has your public key - signing a file will do nothing to keep the contents secret.
--decrypt [file.gpg]	Decrypt the file, or stdin if none is provided. Writes the decrypted file to stdout, unless a filename is provided using --output .
--output file	Write the output to the file. By default, output is written to stdout.

Key Management Options

Key management is central to using GPG.

Generating, importing, exporting and deleting keys.
Option	Description
--gen-key	Generate a new key pair (public/secret). Note that for simply encrypting/decrypting a file, the --symmetric option might be sufficient.
--list-keys	List the available keys. Does not require a password, since no secret information will be listed, just the IDs of the available keys.
--export key-id > key-id.key	Export the public key with the indicated id. You probably want to redirect the input somewhere, since the key is not in textual format - it will make little sence on the console.
--export-secret-keys key-id > key-id.secret-key	Export the private ("secret") key(s) with the indicated id(s). You only really want to do this for backup and maybe if you use more than one machine. Be careful with this - anybody with this key can read encrypted files meant for you, and pretend to be you.
--import key-id.key key-id.secret-key	Use this to import keys exported using --export or --export-secret-keys .
--delete-keys key-id	Delete the public key with the given id. Private keys are not deleted, use the --delete-secret-keys option to do that.
--delete-secret-keys key-id	Delete the private key with the given key-id.

Scripting Options

These options are useful when using GPG in scripts - not generally recommended, but useful in special cases (for example, when automating tests for a script that uses GPG.

When using GPG from a script, arguments should be provided by means other than prompting the user.
Option	Description
--batch	Indicates that there is no user to answer interactive questions. Hence, if GPG finds itself lacking input, it should fail rather than prompt.
--passphrase-fd number	Instructs GPG to read the passphrase from the indicated file descriptor (e.g. 0 which is stdin). By default, GPG will only read it from the console. Providing the passphrase from a file descriptor is insecure, since it is very easy for it to end up hardcoded in a script, or in other easily unsafe places like the history of an interactive shell.

Examples

Generating a key

For use in the other examples, two sets of test keys are generated ( $ is the prompt, emphasized text is typed by the user):

$ gpg --gen-key
gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation,
Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) DSA and Elgamal (default)
   (2) DSA (sign only)
   (5) RSA (sign only)
Your selection? 
Enter
DSA keypair will have 1024 bits.
ELG-E keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 
Enter
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 
Enter
Key does not expire at all
Is this correct? (y/N) 
y

You need a user ID to identify your key; the software constructs
the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: 
test1
Email address: 
Enter
Comment: 
Enter
You selected this USER-ID:
    "test1"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? 
O
You need a Passphrase to protect your secret key.

We need to generate a lot of random bytes. It is a good idea to
perform
some other action (type on the keyboard, move the mouse, utilize
the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
+++++.+++++.++++++++++++++++++++++++++++++++++++++++++++++++++.+++++++++++++++++++++++++...+++++.+++++.+++++++++++++++++++++++++.++++++++++>++++++++++.................+++++++++++++++..+++++..+++++++++++++++++++++++++....+++++.+++++.+++++.+++++++++++++++...++++++++++++++++++++.++++++++++.++++++++++.++++++++++..+++++..++++++++++++++++++++>+++++..+++++>+++++...................................................................>.+++++....................................................................................................................>+++++<+++++.....................................<...+++++..+++++^^^
gpg: key E56AB40B marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   3  signed:   0  trust: 0-, 0q, 0n, 0m, 0f,
3u
pub   1024D/E56AB40B 2010-10-31
      Key fingerprint = 800C 7EC5 C9CB F953 413E  290F 6EFD 9D7E
E56A B40B
uid                  test1
sub   2048g/196CCD77 2010-10-31

Example: Basic Usage

The following is a very simple example of using GPG:

# encrypt my-file to my-file.gpg with my-friend's public key
gpg --recipient my-friend --encrypt my-file

My-friend can decrypt the file using s/his private key:

# decrypt the file to my-decrypted-file
gpg --output my-decrypted-file --decrypt my-file.gpg

Example: Signing and Encrypting a file

The most common uses of GPG are to:

Encrypt a file so only the recipient can read it (using the recipients public key; the file can only be decrypted using the recipients private key)
Sign a file so the recipient can check that it really came from you (using your private key; the "signature" can be checked using your public key)

Assume test1 wants to send a file to test2, and that they have exchanged public keys:

# file.txt contains the message from test1 to test2
echo 'Hello world!' > file.txt

# test1 encrypts (using test2's public key) and signs file.txt
(using test1's private key)
gpg --local-user test1 --recipient test2 --encrypt file.txt
rm file.txt

# ... test1 sends file.txt.gpg to test2...

# test2 decrypts file.txt.gpg to file.txt (requires the private key
of test2)
gpg --output file.txt --decrypt file.txt.gpg
if test "$(cat file.txt)" = 'Hello world!'; then echo OK; fi

Example: Encrypting a file for yourself

Sometimes it is practical to encrypt a file so you can only read it yourself. This is useful for example when protecting backups that you intend to store where they might be read by somebody else.