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.
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.
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.
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.