GPG cheat sheet

  ·  4 min  ·  #development

This post is mainly a reference for my future self to come back to in order to find all the commands I might need relative to GPG key management.

Table of contents

  1. The gnupg directory
  2. Show the keys
  3. Create a new key pair
  4. Delete a key pair
  5. Get Public Key text block
  6. Encrypt files
  7. Decrypt files
  8. Backup & Restore
  9. Configuration

The gnupg directory

This is where all the files are stored. Its default location is ~/.gnupg. I prefer moving it out of sight by adding this line to the shell's config file:

export GNUPGHOME="$HOME/.local/share/gnupg"

If a ~/.gnupg directory already existed before, I can simply move it to this new location.

Show the keys

To see all the keys stored:

gpg --list-secret-keys --keyid-format LONG

The output will be, for each key:

sec   rsa3072/AABBCC112233ABCD 2023-02-24 [SC]
      QWERTYUIOP01234567ABCDEFAABBCC112233ABCD
uid                 [ultimate] User (comment) <mail@account.com>
ssb   rsa3072/1A2B3C4D5E6F7G8H 2023-02-24 [E]

Where:

  • The sec line shows:
    • rsa3072: details about encryption
    • AABBCC112233ABCD: key ID
    • creation date of that key
    • S: key can be used for Signatures
    • C: key can be used for Certification
  • Next line shows the key fingerprint
  • The uid line shows owner's name, comment and mail account
  • Finally the ssb line shows the subkey. E means it can be used for Encryption

Create a new key pair

gpg --full-generate-key

It will ask to insert:

  • Encryption type (can leave default RSA + RSA)
  • Key length (4096 is preferred: the longer it is the more secure)
  • Expiration time (can leave default = no expiration)
  • Name
  • Email
  • Comment (can be left blank)
  • Passphrase

The passphrase is probably the most important field.
It acts just like a password: the user will be asked to provide it when they want to decrypt a file (previously encrypted with their key).
This passphrase must not be forgotten/lost otherwise the user will no longer be able to access their files.
At the same time, it must not be kept in a public place/file where anybody could read it. If another person were to get hold of it they would be able to access all of the private data and, even worse, steal the user's digital identity.

Delete a key pair

It is required that the private key is deleted first.

gpg --delete-secret-key ID

ID can either be the key's id (in this case AABBCC112233ABCD, or the fingerprint on the next line) or the user's (Name). What happens if a user has multiple keys I don't know. I'll keep using the key's id.
Now the public key can be deleted too, using the same ID.

gpg --delete-key ID

Get Public Key text block

Useful to share the public key.

gpg --armor --export KeyID

Encrypt files

gpg -o file.gpg --encrypt -r email@account.com plain.txt

With the -o option I specify the output file (gpg extension is a convention).
With -r I specify the recipient: the user whose public key will be used to encrypt. This allows only the owner of the correspondent private key to be able to decrypt the file.

Decrypt files

gpg -o plain.txt --decrypt file.gpg

Backup & Restore

Create backup copy of public keys, secret keys, and trust database:

gpg --export --export-options backup --output public.gpg
gpg --export-secret-keys --export-options backup --output private.gpg
gpg --export-ownertrust > trust.gpg

Then, get these files on the new machine and import them:

gpg --import public.gpg
gpg --import private.gpg
gpg --import-ownertrust trust.gpg

Configuration

There are 2 configuration files to edit.

gpg.conf

This file has to be put in $GNUPGHOME/gpg.conf. A list of all the options can be found at this website.

gpg-agent.conf

The second one is $GNUPGHOME/gpg-agent.conf.
What I can define here is for how long I can access my secret documents without having to re-enter the passphrase. I set this time interval to 5 hours.
Equally important is the program to use as pinentry; I can specify a custom script that determines whether to use a tty or GUI pinentry based on whether the program requesting the passphrase is running in a terminal or not.

default-cache-ttl 18000
max-cache-ttl 18000
pinentry-program /path/to/pinentry_auto.sh