Programster's Blog

Tutorials focusing on Linux, programming, and open-source

GPG Cheatsheet

This guide was initially written for GPG 1 which has mostly the same interface as GPG 2. From now on this guide will be maintained for v2 but if you see anything that is still for v1 please write it in the comments and I will fix it.

Please install GPG2 if you haven't already.

Table Of Contents

  1. Key Management
    1. Create Key
    2. List All Keys
    3. List Public Keys
    4. List Private Keys
    5. Exporting Public Keys
    6. Exporting Private Keys
    7. Import Keys
    8. Edit Key
    9. Delete Public Keys
    10. Delete Private Keys
  2. File Encryption
    1. Encrypt Files Using GPG Key (Asymmetric Encryption
    2. Encrypt File Using Passphrase (Symmetric Encryption)
    3. Decrypt File Using Passphrase (Symmetric Decryption)
  3. Signing
    1. Create External Text Signature
    2. Clearsign a Document
  4. Verification
    1. Verify Clearsigned Document
    2. Verify External Signature
  5. References

Key Management

Create Key

Refer to "Generate GPG Keys".

List All Keys

gpg2 --list-keys

List Public Keys

gpg2 --list-public-keys

List Private Keys

gpg2 --list-secret-keys

Exporting Public Keys

If you just want other's to be able to send you encrypted messages, you just need to give them your public key. The public key can only be used for encrypting messages, so you can pretty much give it to anybody.

To export all public keys, execute:

gpg2 --export --armour > $FILENAME.asc

If you want to export a single public key, then you need to also specify some sort of identifier, such as the email address or the key user's name

gpg2 --export --armour "blah@gmail.com" > $FILENAME.asc
  • The --armour converts from binary output to ascii so that one can transfer the file to any computer safely.
  • Other's quite often use the .key extension. The asc extension is to represent the fact that it is in ascii format.

Exporting Private Keys

If you own multiple computers, or are about to reinstall your operating system, you may need to export your private key. Your private key can be used to decrypt files, so be careful how you store it or send it anywhere.

To export all private keys, execute:

gpg2 --export-secret-key --armour > $FILENAME.asc

If you want to export a single private key, then you need to also specify some sort of identifier, such as the email address or the key user's name

gpg2 --export-secret-key --armour "blah@gmail.com" > $FILENAME.asc
  • The --armour converts from binary output to ascii so that one can transfer the file to any computer safely.
  • Other's quite often use the .key extension. The asc extension is to represent the fact that it is in ascii format.

Import Key(s)

What use is exporting keys if you couldn't import them?

gpg2 --import $FILENAME

Edit Key

You may wish to edit a key, in order to set/edit its passphrase.

gpg2 --edit-key $KEY_ID_OR_EMAIL

Then run the following in order to set/change the passphrase:

passwd

To save the change, execute:

save

Delete Public Keys

gpg2 --delete-key "email@domain.com"

Delete Private/Secret Keys

gpg2 --delete-secret-keys "email@domain.com"

File Encryption

Encrypt Files Using GPG Key - (Asymmetric Encryption)

If you wish to encrypt some files to send to somebody else (such as an email attachment) and you have their public key, then you can use this to encrypt the files before sending them. You could use this technique to encrypt your own files, and just provide your own email address as the recipient, but bear in mind that this is much slower than using symmetric encryption using a passphrase.

gpg \
  --encrypt \
  --recipient $RECIPIENT_EMAIL \
  --output $OUTPUT_FILEANAME.gpg \
  $FILE_TO_ENCRYPT

The recipient can then decrypt the files using:

gpg2 --decrypt $ENCRYPTED_FILENAME.gpg > $DECRYPTED_FILENAME

Symmetric Passphrase Based Encryption

The commands below are for if you want to just keep files encrypted on your system, rather than share them with someone. This is because the commands will use symmetric encryption which is a lot faster than asymmetric (public key) encryption, but make it harder to give them to someone as you would have to somehow securely provide them with the passphase.

Encrypt File Using Passphrase

gpg2 \
  --output $OUTPUT_FILENAME.gpg \
  --symmetric \
  --cipher-algo AES256 \
  $FILE_TO_ENCRYPT

The list of possible ciphers are: 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH, CAMELLIA128, CAMELLIA192, CAMELLIA256

Decrypt File

gpg2 \
  --output $OUTPUT_FILENAME \
  --decrypt $ENCRYPTED_FILE

Alternatively:

gpg2 --decrypt $ENCRYPTED_FILE > $OUTPUT_FILENAME

The decrypt command automatically use the appropriate key if one exists, or ask for a passphrase if it doesn't.

Using Passphrase File

You can use the command below if you wish to specify a file that has the passphrase to use to decrypt the files (so that your password isn't viewable in the history by all the other users on the system). Just make sure that file isn't accessible by other users.

gpg2 \
  --decrypt \
  --no-use-agent \
  --passphrase-file $PASSPHRASE_FILE \
  --output $OUTPUT_FILENAME \
  $ENCRYPTED_FILE

If --no-use-agent doesn't work, then try --batch as a replacement.

Signing

Create External Text Signature

gpg2 --detach-sign --armor /path/to/doc.txt

This will create another document with the .asc extension appended which has just the signature for the document, in plaintext form.

Clearsign a Document

gpg2 --clearsign /path/to/doc.txt

This will create another document with the .asc extension appended which has the original body of the document, along with the signature. For example:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

This is my message to sign
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJZIbkvAAoJEDDuuAeDtd9Xw/QQAKMxzXP+X6GlGOignrHaSgXS
1cNkELarFAcyG9q6WX0McRa2aWo4kpEL7hHF9gKRkoqEigXj0XijsjhmuowR8+Uv
mdCL1r2W6yYXwQAibenJIy8zXEgkSPeuCYikyy9YkLyDuXRtYJgVJFKZ1dRonDUA
Wm6HRfXoF4VNxgVNbyOHhLsLXy/j0sESptaCmU87OdWYAruFXmpYsDcwV1pB5/Qr
OAQHBQsp9XQLiWyiYDB+13+VWK882gZZYecu7kwsC/dfd8gToA27Yo0eXzFlSbOK
EqX4qOkbmyQrhGrrpYTLTwSfnJa+gBuKLKAbE/J3n7ovkmYojOfMlaKxvYlam30v
z2Lr1G7Z1SQPwZ+W/PYnssgeypkuOSfeqSjiV6lEIwNUYcldxD9sj/ol/U4Rp5Vi
XVD1E/jA2mL/ww+NdjcMhutcP+iuj0yk05e6jvd7qF4+uN/FxD7tD4GiTtBZbt8v
Hqgg5Rr/4l5ruhfPb9pqzEci+8rGPD4FKQY7n/sYXv0EBZHce+SxL2p7sQTGyTpI
0JFPU3PnVoIlDMSMDnCGsnR/0ln9tOohU+HfRXZIvv8vKRv6EzmKckHccpwhhNnn
JDC/FtLSlHaxTTHWLBkTa+SBoCdHkw3zLu1plcVN3NIKcs/+4AeKUeUZ5RU9TteV
wWYD/DYgYCMkVaF/8Z84
=6G9U
-----END PGP SIGNATURE-----

Verification

Verify Clearsigned Document

gpg2 --verify myFile.txt.asc

You will get a message saying gpg: WARNING: not a detached signature; file 'test.txt' was NOT verified! which is true, you verified the signed document at test.txt.asc, not test.txt.

Verify External Signature

gpg2 \
  --verify myFile.txt.asc \
  myFile.txt

The .asc file in this case is the external signature.

References

Last updated: 17th February 2024
First published: 16th August 2018