gpg

Updated: September 28, 2024

GnuPG (or Gnu Privacy Guard) is an adaptation of an earlier encryption standard known as PGP (or Pretty Good Privacy).

One of the benefits about command line tools is the usage is more universal than gui (Graphical User Interface, pronounced goo-eee) conterparts. CLI (Command Line Interface) has more precision and power as well. It is very important to get started and use these in a terminal. In the computer world you can only learn by doing. Use the CLI every time you have a chance. If on windows you will want to install git cli. Powershell sucks and these commands will not work with it. Most of these tools are on a machine by default but as you learn more you will want to download and install more tools but that is for another day.

Table of Contents

tldr

# recieve someones public key (from any key repository)
gpg --recv-keys FAEA82D6

# encrypt doc for some@one.com => doc.txt.gpg
gpg encrypt --recipient some@one.com doc.txt

# decryt doc.txt.gpg
gpg --decrypt doc.txt.gpg

# sign a doc without encryption
gpg --clearsign doc.txt

# encrypt doc with only a passphrase
gpg --symmetric doc.txt

INSTALLATION

Can be installed by most package managers as well as Chocolatey for Windows and Homebrew for Mac.

choco install gnupg -y
brew install gpg

PLACE KEY ON ANOTHER MACHINE

  1. Idendify the desired key and remember ID:
gpg --list-secret-keys user@example.com
  1. Export the key using the ID
gpg --export-secret-keys ID_HERE > private.key
  1. Copy key using scp or usb.
  2. On new machine run:
gpg --import private.key

COMMANDS

    -s, --sign                  make a signature
        --clear-sign            make a clear text signature
    -b, --detach-sign           make a detached signature
    -e, --encrypt               encrypt data
    -c, --symmetric             encryption only with symmetric cipher
    -d, --decrypt               decrypt data (default)
        --verify                verify a signature
    -k, --list-keys             list keys
        --list-signatures       list keys and signatures
        --check-signatures      list and check key signatures
        --fingerprint           list keys and fingerprints
    -K, --list-secret-keys      list secret keys
        --generate-key          generate a new key pair
        --quick-generate-key    quickly generate a new key pair
        --quick-add-uid         quickly add a new user-id
        --quick-revoke-uid      quickly revoke a user-id
        --quick-set-expire      quickly set a new expiration date
        --full-generate-key     full featured key pair generation
        --generate-revocation   generate a revocation certificate
        --delete-keys           remove keys from the public keyring
        --delete-secret-keys    remove keys from the secret keyring
        --quick-sign-key        quickly sign a key
        --quick-lsign-key       quickly sign a key locally
        --sign-key              sign a key
        --lsign-key             sign a key locally
        --edit-key              sign or edit a key
        --change-passphrase     change a passphrase
        --export                export keys
        --send-keys             export keys to a keyserver
        --receive-keys          import keys from a keyserver
        --search-keys           search for keys on a keyserver
        --refresh-keys          update all keys from a keyserver
        --import                import/merge keys
        --card-status           print the card status
        --edit-card             change data on a card
        --change-pin            change a cards PIN
        --update-trustdb        update the trust database
        --print-md              print message digests
        --server                run in server mode
        --tofu-policy VALUE     set the TOFU policy for a key

Options:

    -a, --armor                 create ascii armored output (makes so you can copy/paste/type message onto forum or email)
    -r, --recipient USER-ID     encrypt for USER-ID
    -u, --local-user USER-ID    use USER-ID to sign or decrypt
    -z N                        set compress level to N (0 disables)
        --textmode              use canonical text mode
    -o, --output FILE           write output to FILE
    -v, --verbose               verbose
    -n, --dry-run               do not make any changes
    -i, --interactive           prompt before overwriting
        --openpgp               use strict OpenPGP behavior

EXAMPLES

    -se -r Bob [file]          sign and encrypt for user Bob    
    --clear-sign [file]        make a clear text signature
    --detach-sign [file]       make a detached signature
    --list-keys [names]        show keys
    --fingerprint [names]      show fingerprints

Mac Windows Linux respectively

# [MAC WINDOWS LINUX] to copy to github, gitlab or elsewhere
gpg --export --armor <email> | [pbcopy clip xclip]

USAGE

gpg --full-gen-key          # Create a key with dialog for all options
gpg --gen-key               # create a key with current defaults

gpg -r recipient@secret.gov -e file     # encrypt a file
gpg -d file.gpg                         # decrypt a file

WINDOWS

# if using VS Code path needs to be set
git config --global gpg.program "C:\Program Files (x86)\GnuPG\bin\gpg.exe"

GITLAB

After creating or importing the key onto the machine.

# List key information, we need number in sec
gpg --list-secret-keys 
# Add key to use for signing
git config --global user.signingkey 121CDB71FA9A62D8
# Make it so don't need -S to sign commits
git config --global commit.gpgsign true

GITHUB

Generate and add your key to GitHub

# Every commit will now be signed
git config --global commit.gpgsign true
# Where ABCDEF01 is the fingerprint of the key to use 
git config --global user.signingkey ABCDEF01
# Available in git logs
git config --global alias.logs "log --show-signature"

TROUBLES

If gpg is having trouble signing or password input menu is not showing up, restart daemon.

killall gpg-agent || true       # kill gpg
gpg-agent --deamon              # start gpg

BACKUP AND RESTORE

# Create a backup / place on USB
gpg -o private.gpg --export-options backup --export-secret-keys <email>
# Restore key from backup
gpg --import-options restore --import private.gpg
gpg --edit-key <email>      # type trust then 5 then quit
gpg-connect-agent /bye      # restart agent after setting trust
# Backup trust database (~/.gnupg/trustdb.gpg)
gpg --export-ownertrust > /usb/path/trustdb-backup/
# Restore trustdb from backup
rm ~/.gnupg/trustdb.gpg \
gpg --import-ownertrust < /path/to/trustdb-backup.txt

EXPORTING KEYS

Exporting a key will output the public version and will be called yourname.gpg. The key must first be exported before it can be share to keyservers.

gpg --output your.name.gpg --armor --export youname@domain.com

KEYSERVERS

You want to have your public key searchable and available. Best way to do that is to place them on a Key Server. The other option is sharing by email. Some people place them in the signatures of their email.

gpg --send-keys --keyserver hkp://pgp.mit.edu E8F1E313
gpg: sending key B3219C4BE8F1E313 to hkp://pgp.mit.edu

A list of some keyservers:

FIND A KEY

gpg --keyserver hkp://p80.pool.sks-keyservers.net:80 --search username@domain.com

VERIFY EXTERNAL KEYS

If the person you are trying to send an encrypted message to has an open public key file available (eg. user.asc or user.key) on a website or in a file, we can use the “–import” flag in gpg to add that key to our keyring.

gpg --import < user.asc