GPG Cheat Sheet
---------------

Generate a new key
==================

.. code-block::

    $ gpg --gen-key
    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? 1
    RSA keys may be between 1024 and 4096 bits long.
    What keysize do you want? (2048) 4096
    Requested keysize is 4096 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)
    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: Alice Doe
    Email address: alice.doe@gmail.com
    Comment: Alice's key
    You selected this USER-ID:
        "Alice Doe (Alice's key) <alice.doe@gmail.com>"

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

    gpg: key 0F7AA11C 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
    pub   4096R/0F7AA11C 2018-03-18
          Key fingerprint = EAF1 C5CF 4A61 7FFB E551  D8BA 28FD 8A49 0F7A A11C
    uid                  Alice Doe (Alice's key) <alice.doe@gmail.com>
    sub   4096R/8F2A5CE4 2018-03-18


:Key type: RSA & RSA:
  This means, a master RSA key for signing and certifying, and a RSA sub encrytion key
:Key size:
  Unless there is a good reason not to do so, choose 4096
:Key validity:
  0 (does not expire). A master key usually does not expire
:Real name, email address:
  Real values need to be chosen here - these are the primary identification information.

List keys
=========

List public keys
~~~~~~~~~~~~~~~~

.. code-block::

    $ gpg -k
    pub   4096R/0F7AA11C 2018-03-18
    uid                  Alice Doe (Alice's key) <alice.doe@gmail.com>
    sub   4096R/8F2A5CE4 2018-03-18

:pub:
    Stands for mater public key
:uid:
    User ID
:sub:
    Subordinate public key
:4096:
    Key length
:R:
    Type of encryption, R is for RSA
:0F7AA11C:
    Key short ID
:2018-03-18:
    Date of creation

List private keys
~~~~~~~~~~~~~~~~~

.. code-block::

    $ gpg -K
    sec   4096R/0F7AA11C 2018-03-18
    uid                  Alice Doe (Alice's key) <alice.doe@gmail.com>
    ssb   4096R/8F2A5CE4 2018-03-18

:sec:
    Secret master key
:ssb:
    Secret subordinate key

Show key roles
~~~~~~~~~~~~~~

.. code-block::

    $ gpg --edit-key alice
    Secret key is available.

    pub  4096R/0F7AA11C  created: 2018-03-18  expires: never       usage: SC
                     trust: ultimate      validity: ultimate
    sub  4096R/8F2A5CE4  created: 2018-03-18  expires: never       usage: E
    [ultimate] (1). Alice Doe (Alice's key) <alice.doe@gmail.com>


:S:
    Key that can be used for signing messages
:C:
    Key that can be used to certify other keys
:E:
    Key that can be used for encryption

Create a subordinate signing key
================================

A subordinate signing key is useful in the sense that the master secret key can be stored in a secure place. For example, if I own a laptop, and it gets stolen, I have lost my secret master key, and there is no way to use the public key anymore - the only option is to revoke it entirely (c.f. below). With a subordinate signing secret key, I can keep the master secret key somewhere else (on a piece of paper for example, that can be stored in a safe), and delete it form my laptop. If my laptop gets stolen, only the subordinate secret signing key is compromised, and I can revoke this subordinate key alone, the public key will still be valid.

.. code-block::

    $ gpg --edit-key alice
    gpg> addkey
    (enter passphrase)
    Please select what kind of key you want:
        (3) DSA (sign only)
        (4) RSA (sign only)
        (5) Elgamal (encrypt only)
        (6) RSA (encrypt only)
    Your selection? 4
    RSA keys may be between 1024 and 4096 bits long.
    What keysize do you want? (2048) 4096
    Requested keysize is 4096 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) 6m
    Key expires at Fri 14 Sep 2018 10:38:09 PM +08
    Is this correct? (y/N) y
    Really create? (y/N) y

    pub  4096R/0F7AA11C  created: 2018-03-18  expires: never       usage: SC
                     trust: ultimate      validity: ultimate
    sub  4096R/8F2A5CE4  created: 2018-03-18  expires: never       usage: E
    sub  4096R/BD2FD2EF  created: 2018-03-18  expires: 2018-09-14  usage: S
    [ultimate] (1). Alice Doe (Alice's key) <alice.doe@gmail.com>

    gpg> save


Export keys
===========

.. code-block::

    $ gpg -a --output public.key --export alice
    $ gpg -a --output secret.master.key --export-secret-keys alice
    $ gpg -a --output secret.sub.key --export-secret-subkeys alice

The "-a" option creates a ASCII armored version of the key, i.e. it is in the form of ASCII characters, human readable. Keys are normally a bunch of random bytes. The armored version is useful for transmitting via email for example (public key only), or for printing the secret keys to store in a secure location.


Generate a revocation certificate
=================================

This step **must be done** at the time of the key creation. The revocation certificate can be applied to revoke the whole public key, in case the master secret key is corrupted.

.. code-block::

    $ gpg --output revoke.crt --gen-revoke alice

    sec  4096R/0F7AA11C 2018-03-18 Alice Doe (Alice's key) <alice.doe@gmail.com>

    Create a revocation certificate for this key? (y/N) y
    Please select the reason for the revocation:
      0 = No reason specified
      1 = Key has been compromised
      2 = Key is superseded
      3 = Key is no longer used
      Q = Cancel
    (Probably you want to select 1 here)
    Your decision? 1
    Enter an optional description; end it with an empty line:
    > The secret master key has been compromised - the public key can't be trusted anymore
    >
    Reason for revocation: Key has been compromised
    The secret master key has been compromised - the public key can't be trusted anymore
    Is this okay? (y/N) y

    You need a passphrase to unlock the secret key for
    user: "Alice Doe (Alice's key) <alice.doe@gmail.com>"
    4096-bit RSA key, ID 0F7AA11C, created 2018-03-18

    ASCII armored output forced.
    Revocation certificate created.

    Please move it to a medium which you can hide away; if Mallory gets
    access to this certificate he can use it to make your key unusable.
    It is smart to print this certificate and store it away, just in case
    your media become unreadable.  But have some caution:  The print system of
    your machine might store the data and make it available to others!

It can be a good idea to create a couple of revocation certificates, with different reasons, just in case.
The revocation certificate, as well as the secret master key, must be stored in a secure place.

Revoke the public key
~~~~~~~~~~~~~~~~~~~~~

This is to be used if the secret master key is compromised.

.. code-block::

    $ gpg --import revoke.crt
    $ gpg --keyserver keyserver.ubuntu.com --send-keys 0F7AA11C

It is important to send the revoked public key to the keyserver, so that other parties are aware that they should not use this key.

Revoke the subordinate key
~~~~~~~~~~~~~~~~~~~~~~~~~~

This is to be used if the secret subordinate key is compromised - but the master secret key is still safe.
Please make backups of the keys before attemping this (see above secion *Export keys*).

.. code-block::

    $ gpg --delete-secret-keys alice
    $ gpg --import secret.master.key
    $ gpg --edit-key alice
    Secret key is available.

    pub  4096R/0F7AA11C  created: 2018-03-18  expires: never       usage: SC
                         trust: ultimate      validity: ultimate
    sub  4096R/8F2A5CE4  created: 2018-03-18  expires: never       usage: E
    sub  4096R/BD2FD2EF  created: 2018-03-18  expires: 2018-09-14  usage: S
    [ultimate] (1). Alice Doe (Alice's key) <alice.doe@gmail.com>

    gpg> key 2

    pub  4096R/0F7AA11C  created: 2018-03-18  expires: never       usage: SC
                         trust: ultimate      validity: ultimate
    sub  4096R/8F2A5CE4  created: 2018-03-18  expires: never       usage: E
    sub* 4096R/BD2FD2EF  created: 2018-03-18  expires: 2018-09-14  usage: S
    [ultimate] (1). Alice Doe (Alice's key) <alice.doe@gmail.com>

    gpg> revkey
    Do you really want to revoke this subkey? (y/N) y
    Please select the reason for the revocation:
      0 = No reason specified
      1 = Key has been compromised
      2 = Key is superseded
      3 = Key is no longer used
      Q = Cancel
    Your decision? 1
    Enter an optional description; end it with an empty line:
    > Key has been compromised - please do not trust messages signed with it
    >
    Reason for revocation: Key has been compromised
    Key has been compromised - please do not trust messages signed with it
    Is this okay? (y/N) y

    You need a passphrase to unlock the secret key for
    user: "Alice Doe (Alice's key) <alice.doe@gmail.com>"
    4096-bit RSA key, ID 0F7AA11C, created 2018-03-18


    pub  4096R/0F7AA11C  created: 2018-03-18  expires: never       usage: SC
                         trust: ultimate      validity: ultimate
    sub  4096R/8F2A5CE4  created: 2018-03-18  expires: never       usage: E
    This key was revoked on 2018-03-18 by RSA key 0F7AA11C Alice Doe (Alice's key) <alice.doe@gmail.com>
    sub  4096R/BD2FD2EF  created: 2018-03-18  revoked: 2018-03-18  usage: S
    [ultimate] (1). Alice Doe (Alice's key) <alice.doe@gmail.com>

    gpg> save

    $ gpg --keyserver keyserver.ubuntu.com --send-keys 0F7AA11C

It is assumed that the master secret key is not in the keyring (see below section), so it is needed to delete the secret key as a whole and reimport it from the master secret key.

Remove the master secret key from the device
============================================

**WARNING:** the secret master key must have been exported first, and stored somewhere else, otherwise, it is permanently lost.
It is assumed that the keys have been exported on disk, as mentioned in the above section.

The complete secrey key must be deleted, and the sub-key reimported.

.. code-block::

    $ gpg -K

    sec   4096R/0F7AA11C 2018-03-18
    uid                  Alice Doe (Alice's key) <alice.doe@gmail.com>
    ssb   4096R/8F2A5CE4 2018-03-18
    ssb   4096R/BD2FD2EF 2018-03-18

    $ gpg --delete-secret-keys alice

    sec  4096R/0F7AA11C 2018-03-18 Alice Doe (Alice's key) <alice.doe@gmail.com>

    Delete this key from the keyring? (y/N) y
    This is a secret key! - really delete? (y/N) y

    $ gpg --import secret.sub.key
    gpg: key 0F7AA11C: secret key imported
    gpg: key 0F7AA11C: "Alice Doe (Alice's key) <alice.doe@gmail.com>" not changed
    gpg: Total number processed: 1
    gpg:              unchanged: 1
    gpg:       secret keys read: 1
    gpg:   secret keys imported: 1

    $ gpg -K

    sec#  4096R/0F7AA11C 2018-03-18
    uid                  Alice Doe (Alice's key) <alice.doe@gmail.com>
    ssb   4096R/8F2A5CE4 2018-03-18
    ssb   4096R/BD2FD2EF 2018-03-18

    $ rm secret.master.key secret.sub.key

The # in *sec#* indicates that the master key is not present on the device.

Please note that *rm* is not a secure way to delete a file, please look at *shred* or *wipe* for better ideas on how to securely delete a file.

Encrypt and sign a message
==========================

.. code-block::

    $ echo "The bad guys are not nesessarily the ones we are told they are" | gpg --output message.asc -a -e -s -u alice -r guillaume


:--output message.asc:
    The ecrypted message is stored in a file named "message.asc"
:-a:
    ASCII armor of the encrypted message - useful for sending over a text based channel (e.g. email)
:-e:
    Tell gpg to encrypt
:-s -u alice:
    Tell gpg to sign the message (-s), and to use Alice's secret key for that (-u alice)
:-r guillaume:
    The recipient of the message. Only this recipient can decrypt the message, with his secret key. Multiple recipients can be specified. In this example, Alice is not able to decrypt the message, even though she encrypted it. This can be useful, if she is pressured / tortured to give the key to decrypt the message, there is no way for her to provide it.

Decrypt a message
=================

This is assuming it is run on Guillaume's machine, with his secret key available.

.. code-block::

    $ gpg -d message.asc

    You need a passphrase to unlock the secret key for
    user: "Guillaume Humbert <guillaume.humbert.jp@gmail.com>"
    4096-bit RSA key, ID 40C17670, created 2018-02-25 (main key ID EBC7B065)

    gpg: encrypted with 4096-bit RSA key, ID 40C17670, created 2018-02-25
          "Guillaume Humbert <guillaume.humbert.jp@gmail.com>"
    The bad guys are not nesessarily the ones we are told they are
    gpg: Signature made Sun 18 Mar 2018 11:15:41 PM +08 using RSA key ID BD2FD2EF
    gpg: Good signature from "Alice Doe (Alice's key) <alice.doe@gmail.com>"

Decrypting will also verify the signature.

Send public key to a key server
===============================

.. code-block::

    $ gpg --keyserver keyserver.ubuntu.com --send-keys 0F7AA11C

There is generally no need to send the key to many key servers, they usually mirror each other, and keys are automatically propagated.

Receive public key from a key server
====================================

.. code-block::

    $ gpg --keyserver serverurl --recv-key EBC7B065