Quick-start guide to GPG

GnuPG supports both symmetric key encryption and public key encryption:

1. Symmetric key encryption: The same key is used for both encryption and decryption. Two parties communicating using a symmetric cipher must agree on the key beforehand. Once they agree, the sender encrypts a document using the key, sends it to the receiver, and the receiver decrypts it using the same key. The primary problem with symmetric key encryption is the key exchange. If there are n people who need to communicate, then n(n-1)/2 keys are needed for each pair of people to communicate privately.

2. Public key encryption: This involves creation of a public and private key pair. The private key should never be shared with anyone, while the public key is supposed to be shared with people who want to send you encrypted data. Documents are encrypted using the public key. Later the encrypted file is decrypted with the private key and a passphrase that was set during key generation. As opposed to symmetric key encryption, only n keypairs are needed for n people to communicate privately.

For a more thorough discussion see for instance The GNU Privacy Handbook.

In the following we will primarily discuss public key encryption. A brief introduction to symmetric key encryption is given in the last section.

GPG configuration files

The home directory where GnuPG and its helper tools look for configuration files defaults to ~/.gnupg/ (see also --homedir option). By default the directory has its permissions set to 700, and the files it contains have their permissions set to 600. It is very important to keep ~/.gnupg/ private and have a secure backup stored on a seperate disk as it contains all files generated by the gpg command including the private keys.

For most users the following files are sufficient:

• gpg.conf: standard configuration file read by gpg on startup. It may contain any long options that are available for gpg. A skeleton configuration file is generated on the very first run of gpg.
• gpg-agent.conf: standard configuration file read by gpg-agent on startup. The gpg-agent is a daemon to request and cache passphrases used by gpg.
• dirmngr.conf: standard configuration file read by dirmngr on startup. dirmngr takes care of accessing the OpenPGP keyservers and is also used for managing and downloading certificate revocation lists. A skeleton configuration file is generated on the very first run of gpg.

Example configuration files are included in this repository.

Creating new keys

First create a new keypair (private and public key):

$ gpg --full-gen-key

The user will be prompted to answer several questions:

1. Keypair: The default is RSA and RSA. This means there will be one master key for signing and one subkey for encryption.
2. Keysize: A keysize of 2048 is usually enough.
3. Expiration date: A period of a year is enough most of the time. See Editing keys on how to change it afterwards.
4. Name and email address.
5. Comment: Add a comment for the key's purpose.
6. Passphrase.

Key administration

List all public keys:

$ gpg --list-keys
$ gpg --list-sigs   # list signatures
$ gpg --fingerprint # list fingerprints

List private (secret) keys:

$ gpg --list-secret-keys

Delete a public key:

$ gpg --delete-key <key-id>

Delete a private key:

$ gpg --delete-secret-key <key-id>

Note: <key-id> refers to a key by the name of its owner, email address, the key's fingerprint, by its 8-digit hex ID or similar. For more details, see man gpg, section "HOW TO SPECIFY A USER ID".

Backup a private key

It is recommended to make backups of private keys and save them on a separate and secured medium.

Backup a private key:

$ gpg --export-secret-keys --output private-key.asc --armor <key-id>

By default GnuPG writes to STDOUT if no file is specified with the --output <file> option.

Import backup of a private key:

$ gpg --allow-secret-key-import --import private-key.asc

Editing keys

To open a menu for editing key related tasks, run:

$ gpg --edit-key <key-id>

Useful commands:

• help: display all commands
• passwd: change passphrase
• clean: compact any user ID that is no longer usable (revoked or expired)
• revkey: revoke a key
• addkey: add a subkey to this key
• expire: change expiration date of key
• adduid: add email addresses to this key

Example: renew an expired key

The expiration date of a key can be changed any time, even after it expired:

$ gpg --edit-key <key-id>
# gpg> key 1 (only if you need to update a sub-key, by default primary key is selected)
# gpg> expire
#  (follow prompts)
# gpg> save

Example: add additional UID

Additional email addresses can be added to the key:

$ gpg --edit-key <key-id>
# gpg> adduid
#   Real name: Red Dragon
#   Email address: new_email@address.com
#   ... insert passphrase to unlock secret key ...
# gpg> save

If more UIDs were added to a key, we can set a primary UID:

$ gpg --edit-key <key-id>
# gpg> uid 2
# gpg> primary
#   ... insert passphrase to unlock secret key ...
# gpg> save

Export and import public keys

Export a public key to a 7-bit ASCII file:

$ gpg --armor --output my-public.key --export <key-id>

If no <key-id> has been entered, all present keys will be exported.

The public key can be freely distributed by sending it to friends, publishing on websites or registering it with public key servers.

In order to encrypt a documents for another user as well as to verify their signatures, we need their public key.

Import someone else's public key:

$ gpg --import some-public.key

Revoke a key

If, for instance, the private key bas been stolen, the UID has been changed, or you forgot the passphrase, it is important to notify others that the public key should no longer be used. After generating a new key it is recommended to immediately generate a revocation certificate:

$ gpg --output revoke.asc --gen-revoke <key-id>

Store the file revoke.asc somewhere safe. It can be used to revoke the key later when the private key is compromised.

To revoke your key, import the revocation certificate:

$ gpg --import revoke.asc

If a key server is used, update the key server as well:

$ gpg --keyserver subkeys.pgp.net --send <key-id>

Note: The --keyserver option is not required, when the keyserver is specified in ~/.gnupg/dirmngr.conf.

Encrypting and decrypting

After a public key has been imported, we can encrypt a file or message to that recipient:

$ gpg [--output <outfile>] --recipient <key-id> --encrypt <some-file>

By default the encrypted file will be appended a .gpg suffix. This can be changed with the --output <outfile> option.

To encrypt a file for personal use, <key-id> is simply the name or email address (or anything else) that was used during key generation.

When encrypting or decrypting a document, it is possible to have more than one private key in use. In this case, we need to select the active key with the option --local-user <key-id>. Otherwise the default key is used.

Decrypt a file that has been encrypted with our own public key:

$ gpg --output somefile.txt --decrypt somefile.txt.gpg

gpg will prompt for the passphrase and then decrypt and write the data to the file specified with the --output option.

Further options:

• --armor, -a: encrypt file using ASCII text
• --hidden-recipient <user-id>, -R <user-id>: put recipient key IDs in the encrypted message to hide receivers of message against traffic analysis
• --no-emit-version: avoid printing version number in ASCII armored output

Signing and checking signatures

To avoid the risk that someone else claims to be you, it is useful to sign every document that is encrypted. If the encrypted document is modified in any way, a verification of the signature will fail.

Sign a file with your own key:

$ gpg --sign <file> --output <file.sig>

Note that the file is compressed before being signed. The output will be in binary format and thus won't be human-readable. To make a clear text signature, run:

$ gpg --clearsign <file> --output <file.sig>

This causes the document to be wrapped in an ASCII-armored signature but otherwise does not modify the document. Hence, the content in a clear text signature is readable without any special software. OpenPGP software is only required to verify the signature.

A disadvantage of above methods is that users who received the signed documents must edit the files to recover the original (since signature is now part of document). It is also possible to make a detached signature to a file:

$ gpg --armor --output <file.sig> --detach-sign <file>

This is highly recommended when signing binary files (like tar archives).

Sign and encrypt a file:

$ gpg --sign <file> [--armor] --encrypt --recipient <user-id> [--local-user <key-id>]

--local-user <key-id> specifies the key to sign with, it overrides --default-key <key-id> option, which is usually specified in ~/.gnupg/gpg.conf.

When an encrypted file has been signed, the signature is usually checked when the file is decrypted using the --decrypt option:

$ gpg --output <file> --decrypt <file.gpg>

To just check the signature use the --verify option:

$ gpg --verify <pgp-file/sig-file>

This assumes the signer's public key has already been imported.

Assuming we downloaded a file archive.tar.gz and a corresponding detached signature archive.tar.gz.asc, we can verify the signature after downloading the signer's public key as follows:

$ gpg --verify archive.tar.gz.asc archive.tar.gz

Key servers

Public keys can be registered with a public key server, so that others can retrieve the key without having to contact you directly.

Send public key to key server, so that others can retrieve the key:

$ gpg --keyserver <keyserver-name> --send-keys <key-id>

Find details about a key on the key server without importing it:

$ gpg --keyserver <keyserver-name> --search-keys <key-id>

Locate the key of a user by email address:

$ gpg --keyserver <keyserver-name> --auto-key-locate keyserver --locate-keys user@example.com

Import key from key server:

$ gpg --keyserver <keyserver-name> --receive-keys <key-id>

Update all keys that have already been retrieved from a key server, e.g. with latest signature, user IDs, etc.:

$ gpg --refresh-keys

To fetch keys automatically from a key server, add the following to ~/.gnupg/gpg.conf:

keyserver-options auto-key-retrieve

To avoid repeatedly specifying the key server with --keyserver, set a default key server in ~/.gnupg/dirmngr.conf:

keyserver hkps://keys.openpgp.org

A list of common key servers can be found in the ArchWiki.

A new way to retrieve public OpenPGP keys is provided through the Web Key Directory. More details can be found in the GnuPG Wiki.

Symmetric key encryption

Documents can be encrypted with a symmetric cipher using a passphrase. The default cipher used is AES-128 but can be changed with the --cipher-algo option.

Encrypt a file using a symmetric key:

$ gpg --symmetric <file>

This will create an encrypted file with a .gpg appended to the old file name.

Decrypt the encrypted file:

$ gpg [--output myfile] --decrypt myfile.gpg

The user will be prompted to enter the passphrase used to encrypt.

References and further reading

• The GNU Privacy Handbook
• Arch Linux wiki
• OpenPGP best practices
• LinuxCrypto
• Linux commandline encryption tools
• GPG quickstart
• Ana's blog