Get Started with GnuPG

Install

I'll assume you'll want to use GnuPG v2.

If you're using Ubuntu install from the repos.

user@host:~$ sudo aptitude install gpgv2

You can also install from Nix package manager. It'll usually have newer versions available than the Ubuntu respos (especially if it's LTS).

user@host:~$ nix-env -i gnupg-2.1.1

WARNING: This is a "living document" and will be updated as I learn from my mistakes.

Generate Your Key Pair

You'll need a lot of entropy while generating a key pair. I don't know how much it helps but I run the following in a separate terminal window while I generate a key pair.

user@host:~$ dd if=/dev/urandom of=/dev/null

While the dd process is running, run the following in a different terminal window to generate your key pair.

user@host:~$ gpg2 --gen-key

You'll be asked for your real name and email address. This constructs an identity for you. Make sure to use your actual information here.

You will also be asked to provide a passphrase. Choose a secure passphrase and do not lose it. It's often recommended to keep a printed copy in a safe place, locked away from prying eyes.

Generating a key pair takes a long time; a really long time. So be prepared to wait for the process to complete.

It's recommended to generate the revocation certificate after you generate your key pair and keep it safely in a separate location. This is in case you lose the private key and need to revoke it.

Once the key is generated remember to stop the dd process you had running in the other terminal window.

Publish Your Public Key

Generate an ASCII version of your public key.

user@host:~$ gpg2 --armor --output public-key.asc --export 'My Name'

You can now post the public-key.asc file to your website, social media, etc. for your friends to use freely.

You can also register your public key with a public keyserver, e.g. hkp://keys.gnupg.net.

First list the key ID.

user@host:~$ gpg2 --list-public-keys | grep pub

The output would contain something like this

pub   rsa2048/E7866B03 2015-02-23

Use this ID to send the key to the key server.

user@host:~$ gpg2 --keyserver hkp://keys.gnupg.net --send-keys E7866B03

Verify your key was registered successfully.

user@host:~$ gpg2 --keyserver hkp://keys.gnupg.net --search-keys "My Name"

Import a Friend's Public Key

There are two ways to import your friend's public key.

  • Obtain the key from your friend by direct communication.
  • Obtain from a key server.

Import Exported Public Key

If your friend provided you their exported public key by direct communication (email, in-person, etc.), simply import it.

user@host:~$ gpg2 --import friend-key.asc

Import from Key Server

Just like you did in the previous section, your friend can publish their public key on a key server. Search for their name and import the key.

user@host:~$ gpg2 --keyserver hkp://keys.gnupg.net --search-keys "Name of Friend"

You'll see text like this

(1) Friend <friend1@example.com>
      2048 bit RSA key A55CEC54, created: 2015-02-22
(2) Friend <friend2@example.com>
      4096 bit RSA key 37608D29, created: 2015-01-15, expires: 2016-01-15
(3) Friend <friend3@example.com>
      4096 bit RSA key 6D970B51, created: 2015-01-09, expires: 2020-01-08
(4) Friend <friend4@example.com>
      4096 bit RSA key AB97C451, created: 2014-12-26
(5) Friend <friend5@example.com>
      2048 bit RSA key D88EC702, created: 2014-12-02, expires: 2016-12-01
(6) Friend <friend6@example.com>
      4096 bit RSA key A2F103DD, created: 2014-11-12, expires: 2019-11-11
(7) Friend <friend7@example.com>
      4096 bit RSA key 2D793A1A, created: 2014-10-08, expires: 2019-10-07
(8) Friend <friend8@example.com>
      1024 bit DSA key C74DC1CF, created: 2014-07-30
(9) Friend <friend9@example.com>
      2048 bit RSA key A7B61B58, created: 2014-07-21, expires: 2018-07-21
(10)    Friend <friend10@example.com>
      2048 bit RSA key 414A706E, created: 2014-06-26, expires: 2018-06-26
(11)    Friend <friend11@example.com>
      2048 bit RSA key F4D6C52B, created: 2014-06-08, expires: 2019-06-07
Keys 1-11 of 298 for "Friend".  Enter number(s), N)ext, or Q)uit >

Continue searching for the exact key you want to import. When you find it, enter the number corresponding to it. Say here we import number 5.

Keys 1-11 of 298 for "Friend".  Enter number(s), N)ext, or Q)uit > 5
gpg: key D88EC702: public key "Friend <friend5@example.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1
(12)    Friend <friend12@example.com>
      2048 bit RSA key 82ED28C2, created: 2014-06-08, expires: 2018-06-08
(13)    Friend <friend13@example.com>
      2048 bit RSA key AB2ACC1C, created: 2014-05-04
(14)    Friend <friend14@example.com>
      2048 bit RSA key 803318FC, created: 2014-04-25, expires: 2018-04-25
(15)    Friend <friend15@example.com>
      4096 bit RSA key 4B2B8F4C, created: 2014-04-01
(16)    Friend <friend16@example.com>
      2048 bit RSA key 3E2943D8, created: 2014-04-01
(17)    Friend <friend17@example.com>
      2048 bit RSA key 71DA14D8, created: 2014-03-09
(18)    Friend <friend18@example.com>
      2048 bit RSA key A90FC456, created: 2014-03-03
(19)    Friend <friend19@example.com>
      4096 bit RSA key FBCF01B0, created: 2014-03-02, expires: 2018-03-02
(20)    Friend <friend20@example.com>
      4096 bit RSA key 3A486DA8, created: 2014-02-27
(21)    Friend <friend21@example.com>
      2048 bit RSA key BC75B3D9, created: 2014-02-15, expires: 2018-02-15
(22)    Friend <friend22@example.com>
      2048 bit RSA key 978DBE9D, created: 2014-02-07
Keys 12-22 of 298 for "Friend".  Enter number(s), N)ext, or Q)uit >

Now you may quit the session.

Keys 12-22 of 298 for "Friend".  Enter number(s), N)ext, or Q)uit > q
gpg: error searching keyserver: Operation cancelled
gpg: keyserver search failed: Operation cancelled

Verify the key was imported successfully.

user@host:~$ gpg2 --list-public-keys

You'll have some output like

/home/username/.gnupg/pubring.kbx
-------------------------------
pub   rsa2048/E7866B03 2015-02-23
uid       [ultimate] My Name <my.name@example.com>
sub   rsa2048/C2B7D292 2015-02-23

pub   rsa2048/D88EC702 2014-12-02 [expires: 2016-12-01]
uid       [ unknown] Friend <friend5@example.com>
sub   rsa2048/EE4022B0 2014-12-02 [expires: 2016-12-01]

Delete Friend's Public Key

There are situations where you want to delete your friend's public key.

List all keys in your keyring.

user@host:~$ gpg2 --list-public-keys

Now delete the one you want.

user@host:~$ gpg2 --delete-key D88EC702

Edit Your Key

TODO

Export Your Key Pair

When you want to use the key pair on multiple machines, you may want to export it and then import wherever it's needed.

List your secret keys.

user@host:~$ gpg2 --list-secret-keys

Export the public and private keys of the key pair you want to copy to another machine or keyring. You'll be asked for the passphrase when exporting the private key.

user@host:~$ gpg2 --armor --output public-key.asc --export E7866B03
user@host:~$ gpg2 --armor --output private-key.asc --export-secret-key E7866B03

Securely copy public-key.asc and private-key.asc to the target.

On the target machine you can now import the key pair.

user@target:~$ gpg2 --armor --import public-key.asc
user@target:~$ gpg2 --armor --allow-secret-key-import --import private-key.asc

Verify the import was successful on the target machine.

user@target:~$ gpg2 --list-secret-keys

Delete public-key.asc and private-key.asc files on the source and target machines.

Revoke Your Key Pair

Sometimes you need to revoke your key. It may have been compromised, you don't want to use it for some reason, etc.

List all secret keys in your keyring.

user@host:~$ gpg2 --list-secret-keys

Now generate a revocation certificate for the key you want to revoke. You'll be asked for a reason for revocation. It's a good idea to also provide an accurate description for why you needed to revoke the key.

You'll also be prompted for the passphrase you used when creating the key pair.

user@host:~$ gpg2 --armor --output revoke.asc --gen-revoke E7866B03

When the time comes to revoke your key pair, import the revocation certificate into your keyring.

user@host:~$ gpg2 --import revoke.asc

Verify the revocation was successful.

user@host:~$ gpg2 --list-secret-keys

You'll see something like

/home/username/.gnupg/pubring.kbx
-------------------------------
sec   rsa2048/E7866B03 2015-02-23 [revoked: 2015-02-23]
uid       [ revoked] My Name <my.name@example.com>

Now you are ready to send your revoked key to the key server. Be careful, though, because once you publish your revocation it can't be undone. Read how to unrevoke a key for more information.

user@host:~$ gpg2 --keyserver hkp://keys.gnupg.net --send-keys E7866B03

Verify the revocation was successful on the key server as well.

user@host:~$ gpg2 --keyserver hkp://keys.gnupg.net --search-keys E7866B03

The output would contain something like

(1) My Name <my.name@example.com>
      2048 bit RSA key E7866B03, created: 2015-02-23 (revoked)

Encrypt and Decrypt Your Private File

TODO

Encrypt and Decrypt Your Public File

TODO

Encrypt and Decrypt a Friend's Public File

Name the encrypted file as something.asc (replace something) with a more descriptive name.

user@host:~$ gpg2 --decrypt something.asc

You'll be asked to enter your passphrase.

Encrypt Email Message You're Sending

TODO

Sign Email Message You're Sending

TODO

Decrypt Email Message You Received

TODO

Verify Signed Email Message You Received

TODO