GPG Tutorial

By Xah Lee. Date: . Last updated: .

This page is a short tutorial on GNU Privacy Guard (GPG).

Gnupg logo

Generate Public and Private Keys

first, generate your public and private key pair.

gpg --gen-key

Just follow the interactive command line instruction.

After it's done, your key will be at the dir ~/.gnupg. Note: the key files there are all binary files.

Be sure you remember your passphrase.

here's sample session:

◆ xah@xah-p6813w◆ 2014-02-22 19:40 ◆ ~
◆ gpg --gen-key
gpg (GnuPG) 1.4.11; Copyright (C) 2010 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.

gpg: directory `/home/xah/.gnupg' created
gpg: new configuration file `/home/xah/.gnupg/gpg.conf' created
gpg: WARNING: options in `/home/xah/.gnupg/gpg.conf' are not yet active during this run
gpg: keyring `/home/xah/.gnupg/secring.gpg' created
gpg: keyring `/home/xah/.gnupg/pubring.gpg' created
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection?
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
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) 1y
Key expires at Sun 22 Feb 2015 09:02:45 PM PST
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: Xah Lee
Email address: xah@xahlee.org
Comment:
You selected this USER-ID:
    "Xah Lee <xah@xahlee.org>"

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.

Not enough random bytes available.  Please do some other work to give
the OS a chance to collect more entropy! (Need 282 more bytes)

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

Not enough random bytes available.  Please do some other work to give
the OS a chance to collect more entropy! (Need 76 more bytes)
+++++

Not enough random bytes available.  Please do some other work to give
the OS a chance to collect more entropy! (Need 28 more bytes)
.+++++
gpg: /home/xah/.gnupg/trustdb.gpg: trustdb created
gpg: key 07438185 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:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2015-02-23
pub   2048R/07438185 2014-02-23 [expires: 2015-02-23]
      Key fingerprint = C3B1 AFF5 C285 F48E 3FB5  EA61 C811 6AFD 0743 8185
uid                  Xah Lee <xah@xahlee.org>
sub   2048R/3668BBB3 2014-02-23 [expires: 2015-02-23]

Don't worry if you made a mistake. If this is your first time using gpg, you can delete the whole ~/.gnupg dir and try again.

{List, Import/Add, Export, Find}, Keys

List Keys

gpg --list-keys
List all public keys.

Here's sample output:

◆ gpg --list-key
/home/xah/.gnupg/pubring.gpg
----------------------------
pub   2048R/07438185 2014-02-23 [expires: 2015-02-23]
uid                  Xah Lee <xah@xahlee.org>
sub   2048R/3668BBB3 2014-02-23 [expires: 2015-02-23]

pub   2048R/5BB6FE3C 2014-02-26 [expires: 2014-05-27]
uid                  Xah Lee <xahlee@gmail.com>
sub   2048R/779449FC 2014-02-26 [expires: 2014-05-27]

Note: in the line pub 2048R/07438185 …, the number after the slash is the key ID. Key ID is useful in many commands.

gpg --list-sigs
List all public keys and signatures.

Export Your Public Keys

now, export your public key.

gpg --export -a
Print your public key as plain text to screen.
gpg --local-user key_id --export -a
Print a specific public key as plain text.

You can place your public key on your website, blog, send it to friend, etc. People need your public key to send you encrypted files or verify your signature.

Note: somebody else can generate a key pair and send to your friend Alice by email and forge email header to pretend it's from you. And your friend might be fooled to encrypted a big secret using this guy's public key thinking it's yours. In general, you shouldn't trust public keys easily. The detailed security risk is beyond this simple tutorial.

Publish Your Key to Public Key Server

You can send your key to a public-key server, so that other people can easily find your key in order to send encrypted messages to you.

gpg --send-keys key_id
Upload your public key to default key server.

sample:

◆ gpg --send-keys 5BB6FE3C
gpg: sending key 5BB6FE3C to hkp server keys.gnupg.net

You can find your key_id by gpg --list-keys, it's the number after the slash.

the default key server is hkp://keys.gnupg.net/

Import/Add Other People's Public Keys

To send a encrypted message to Alice, you need her public key.

gpg --import filename
Import a public key of others.

The filename is usually a plain text file.

Here's a example of public key you can import:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.11 (GNU/Linux)

mQENBFMJgWoBCADTLgXzbRSyPazY+M8j7trJ9hk4B1WYMd79ut7/fEq39s7iR3eb
7LH8ngbnlLsWeNwalZl3LGP3Yu1sCW9lB2nMw8BaP9B5/NN+YaX4y3XJiz10p3JO
jW4cz12Pd/kOrUyAOViNJStPYVmXOJZ0BvwZzxXJPuiJRbWWwZY5VKhjdWEUycF3
GpBKLB0X8uGXXhFIeKQ2v4mZIBYj8vdKbGIPBDFOtRLbhY/sj2je6Er8XF7BIFBQ
msEnGj0kehxqCv6RZkd8RdHTgItOzG+qowitG6YG/rjFY3Mrranc41pAB4tZ0IkU
oX+/rZRo0iizcRnL9SRvk2sHP/D/FG68QiR/ABEBAAG0GFhhaCBMZWUgPHhhaEB4
YWhsZWUub3JnPokBPgQTAQIAKAUCUwmBagIbAwUJAeEzgAYLCQgHAwIGFQgCCQoL
BBYCAwECHgECF4AACgkQyBFq/QdDgYV72wgA0spK+mLZv5RGym9BNleDfi531sF3
I4KrI4t4SuBNA1u5l7wvCm7+SWN/oiuZjkhIxd3OMeePmH3D9JnopLbMQGtYYR4W
q0YpGbkoE898gH/Bm3+IiRkQthCAjxWKEGkrLqeQq2Td4/TxTT9oDg+eHZNtcEsp
0WU+/JEeaFDiAIgp1cOZ5PyZ1g/upnECZ3HD/gkFUTbBeNJmJCW1HT7l2yBa/SMt
8lcpdWaCKDJqiK6hvo3fZMILLyQg+5zbGLPhrkn9R92OCK8EWc4zJVjwWslyxqy5
Dsjs1Lh0SXFb2TEgkWGvp1Pn8niOVimhytY+zEyMm/qz17aCbSSt5bi3cLkBDQRT
CYFqAQgAxy3iLFGv583IhDXphiq04f92BunbNCdwLvDqqzoPuFdp+YfwEkvyTBKS
PiFrNWXXiTThoIbSQSMEkQnyxZkWTIK2UBe1Qpb7B+oSPrLSMVCN+CTc87FiEJnT
iY5x7gtzeCKRUguMXfY1WxyI0gsrichRF8Yy/wQgGgXCpyzgYDlcYxMtGxMl0Nq/
5kma9T64EmT62j1sPvVbqwnRBiMdYld5I31tISi1UZMPvF9wkLk9F92TDbmJzR4c
0Xx9tGsa2FYK/vmh5TruA0bI+Zs0fjeRhB6xFXouE/bDM0V8pCCj32yjwesBeM7J
6nVJIF5nf/+epiur9E5DvpYA1HR6TwARAQABiQElBBgBAgAPBQJTCYFqAhsMBQkB
4TOAAAoJEMgRav0HQ4GFVQsH/2Xip8v8Ux8zSoGbKmdnF39Ma8cOqEw6RlOfkbRu
voXsedZWr5NpAndhrM1oMIPeZU8tXLKzhJLYENqiJ/fTWZVmqKQDcqI4OymvT4C4
Cu/3luqGC0iPpy+qmgg5nQzi142O5SXwM8hQ9/8RZKuI2gtFA8eP7G8mhsIPG73a
UGaquh1p3fxa8MMjxPXd6y40PM71NSQ9rkbwm9Zx7MU3cpOjrXXxtM52WnaxtaIR
Mycv7Axvv9MRDgTI5ozmxPxbthLKyk5XFCG6Tv8zro911qW6vFCfzpQquO1HTtFM
l9xhK+JJFC/S02oSALpBG5noAoxmM4VILvjMzIU7nS65Quw=
=PwPW
-----END PGP PUBLIC KEY BLOCK-----

Find People's Keys

Often, people's keys are on a key server.

gpg --search-keys name
Search a key by name. The name is any string, usually people's name or email address.

sample output:

◆ gpg --search-keys xah
gpg: searching for "xah" from hkp server keys.gnupg.net
(1)     Xah Lee <xahlee@gmail.com>
          2048 bit RSA key 5BB6FE3C, created: 2014-02-26
(2)     Xah Lee <xah@xahlee.org>
          2048 bit RSA key 07438185, created: 2014-02-23
(3)     Łukasz Rumiński <xah-luk@o2.pl>
          2048 bit RSA key CA9CBC6B, created: 2012-04-12
(4)     Łukasz Rumiński <xah-luk@o2.pl>
          2048 bit RSA key C26152F8, created: 2012-03-29
(5)     Xah Lee <xah@xahlee.org>
          1024 bit DSA key CB8F3E74, created: 2000-03-25
Keys 1-5 of 5 for "xah".  Enter number(s), N)ext, or Q)uit > q

Once you find the person, you can import the key by:

gpg --recv-keys key_id
Import a key identified by key_id to your keyring.

Revoke Key

if your computer got stolen (your secret is stolen), you need to revoke your key.

to revoke, you need your passphrase, and your secret key in your computer.

gpg --gen-revoke
Revoke your key.

Sign Documents

you can use gpg to digitally sign documents, so that others know you signed it.

gpg --sign file
Create a signed file. This will create a file in the same path, with .gpg suffix in file name. The created file is compressed binary file.
gpg --clearsign file
Same as --sign, but create a plain text file. The newly created file will have .asc name suffix.

Sign Documents with Different Key

gpg lets you create many key pairs. To specify a particular key, use the --local-user option, like this:

gpg --local-user xahlee@gmail.com --sign myfile.txt

The --local-user option can be used with other commands to specify a key.

Verify Signed Documents

gpg --verify file

You need the other person's public key in your keyring. If you haven't done so, use gpg --import key_filename.

Encrypt File

you can encrypt your files.

gpg --encrypt filename
Encrypt a file using your own public key. So, only yourself can decrypt it later.
gpg --encrypt --recipient name filename
Encrypt a file for name to read, using name's public key. The name is the “uid” in man gpg doc.

You must have name's public key in your keyring. If not, use --import first.

gpg --list-public-keys to show a list of name (uid).

When you encrypt a file for Alice to read, you can and should also sign the file. So, when Alice reads it, she also has confidence that YOU encrypted it, not somebody else.

gpg --encrypt --recipient name --sign filename
Encrypt a file for name to read, and sign it with your name.

Decrypt File

gpg --decrypt filename
Decrypt a file using your secret key. The file must be one that's encrypted by your public key. The output is printed to the screen.
gpg --decrypt filename > output_filename
Decrypt a file and save it as output_filename.