Skip to content

Instantly share code, notes, and snippets.

@johnfedoruk

johnfedoruk/gpg_user_guide.md

Last active February 17, 2025 16:01
Show Gist options
  • Save johnfedoruk/7f156d844af54cc91324dff4f54b11ce to your computer and use it in GitHub Desktop.
Save johnfedoruk/7f156d844af54cc91324dff4f54b11ce to your computer and use it in GitHub Desktop.
Download ZIP
A simple GPG user guide
Raw
gpg_user_guide.md

GPG User Guide

Author: John A. Fedoruk <[email protected]>
Key ID: 8937446102D51067EB90DB6AB229A6E87086AD48
Date: 2019-07-03

Overview

GPG is an implementation of PGP (Pretty Good Privacy). This is an open standard for encryption schemes. GPG stands for Gnu Privacy Guard.

This document will serve to go through some scenarios where GPG is utilized for: generating key pairs, perform a manual key exchange through secure channels, generate key signatures, and encrypt and decrypt files. Your name is now Bob and your friend's name is Alice. Let's get started!

Table of Contents

Installing GPG

MacOS

brew install gpg

Linux

sudo apt-get install gnupg

Getting Started

Generating a Key Pair

gpg --full-generate-key

Note

You will want to use consider using the following options when prompted by the above command:

Listing Keys in Keyring

gpg --list-keys

Note

This will likely output something like the following:

/Users/bob/.gnupg/pubring.kbx
-------------------------------
pub   rsa4096 2019-07-04 [SC]
      C1C47AA57701C1C9BB87DF8E9BAFE10A939CFFB6
uid           [ultimate] Bob Builder <[email protected]>
sub   rsa4096 2019-07-04 [E]

Key Exchange

You will want to perform a key exchange with people in order to make use of encryption - that's what it is all about, really!

By receiving a person's public key, you can encrypt files and messages for them. Having received your key, they have the ability to verify the signature of the encrypted file you've sent them to ensure it was actually sent by you (or by somebody with control of your key...). This also works in reverse, where you can receive an encrypted file and verify the signature of the sender.

Exporting Your Public GPG Key

In order to send a key, we will manually export it so it can be send to them through a secure channel.

gpg --armor --export [email protected] > ./[email protected]

Share the file ./[email protected].

Importing a Third-Party Public GPG Key

After receiving a GPG key file ./[email protected] which you want to import for signature verification, you will run the following command:

gpg --import ./[email protected]

Fingerprinting a Third-Party Public GPG Key

gpg --fingerprint [email protected]

Note

This will likely output something like the following:

pub   rsa2048 2019-07-04 [SC]
      F476 4480 49BA 78F0 2133  C965 52F7 78CF EAAE 2FC5
uid           [  unknown  ] Alice <[email protected]>
sub   rsa2048 2019-07-04 [E]

Key Trust

Key trusts are an important concept in the world of PGP, but a lengthy topic. In short, it's the level of trust you put in somebody to sign other's keys. See the chapter on Key Trust in the GnuPG manual for more information.

Levels of Trust

Below is the GPG levels of trust:

  • unknown
    • Nothing is known about the owner's judgement in key signing. Keys on your public keyring that you do not own initially have this trust level.
  • none
    • The owner is known to improperly sign other keys.
  • marginal
    • The owner understands the implications of key signing and properly validates keys before signing them.
  • full
    • The owner has an excellent understanding of key signing, and his signature on a key would be as good as your own.
  • ultimate
    • Reserved for keys you own and fully trust.

Trusting an Imported Third-Party GPG Key

Now you need to trust the key you imported from Alice. Use the following command to trust it:

gpg --edit-key [email protected]

Note

  • You will need to type trust and hit [ENTER].
  • Now select the level of trust you wish to assign to the key sent to you. Refer to the section on levels of trust.
  • Type quit and [ENTER] to exit the --edit-key shell.

Key Signing

If you trust a key, you may want to sign it. This builds a web of trust. Additionally, it will add immediate signature validity for communications between you and the owner of that key.

Signing a Third-Party Key

We know Alice is legit. We have seen Alice's government issued identification and she provided us with her Key ID in person. Having imported her key, we will validate her key with

gpg --sign-key [email protected]

Exporting a Third-Party Signed Key

You can export your signature for a key to share it with the key's owner. By doing this, your signature can be imported by the key owner then shared with those who trust you to validate the authenticity of the signed key.

For example, you can export a signature of Alice's key. When you send it to her, she can import it back into her keyring. Meanwhile, Eve trusts you fully. Alice sends her public key to Eve, though Eve does not really know Alice. Eve can validate Alice's authenticity through her trust with you.

Let's now export Alice's key signature. In addition to exporting it, we will encrypt it and sign it. Alice will be able to decrypt it and then import it without issue, as we know she should own the private key in question.

gpg --armor --export [email protected] | gpg -aes -r [email protected] > [email protected][email protected]

Send the file ./[email protected][email protected] to Alice.

Importing Your Signed Key

Your key has been signed and exported by Alice. She sent you the encrypted signature file ./[email protected][email protected]. Let's decrypt it and import the signature into our keychain.

gpg -d ./[email protected][email protected] | gpg --import

You now have your key signed by Alice! People's trust in her will allow others to authenticate your key more easily.

Cryptographic Messages

Let's get to the meat and potatoes.

Encryption

Let's send some secrets to Alice. We will start by sending a secret message, and then look at sending an encrypted tarball.

Encrypting Simple Messages

Let's encrypt the message Hello, world and send it to Alice. We will produce a file called ./secret_message.asc.

echo "Hello, world" | gpg -aes -r [email protected] -u [email protected] > secret_message.asc

Now send ./secret_message.asc to Alice.

Encrypting Files

You have an directory ./secrets with two files inside: passwords and ch3@t_c0d3z. You need to send these to Alice. You can use the following command to generate a gpg tarball.

Note that this will not use the armor flag -a, as we will want to keep this generated file in binary format to preserve space. As such, the convention is to name the file with a .gpg extension.

tar czvf - secrets/ | gpg -es -r [email protected] -u [email protected] > secrets.tar.gz.gpg

Note

This will likely output something like the following:

a secrets
a secrets/passwords
a secrets/ch3@t_c0d3z

Now send ./secrets.tar.gz.gpg to Alice.

Decryption

Alice will send us the same encrypted files as we sent her in the encrypted section. Let's decrypt them.

Decrypting Simple Messages

Alice sent you a secret message, ./secret_message.asc. Let's decrypt it and see what's in it!

gpg -d ./secret_message.asc

Note

This will likely output something like the following:

gpg: encrypted with 4096-bit RSA key, ID C1C47AA57701C1C9, created 2018-08-19
      "Bob Builder <[email protected]>"
Hello, world
gpg: Signature made Wed Jul  3 21:55:08 2019 CDT
gpg:                using RSA key F476448049BA78F02133C96552F778CFEAAE2FC5
gpg:                issuer "[email protected]"
gpg: Good signature from "Alice <[email protected]>" [full]

We can see the message said Hello, world and the signature was good!

Decrypting Files

Alice sent you a file ./secrets.tar.gz.gpg. It is an encrypted tarball, which contains a directory ./secrets with two files inside: passwords and ch3@t_c0d3z. This should be easy.

gpg -d secrets.tar.gz.gpg | tar xvzf -

Note

This will likely output something like the following:

gpg: encrypted with 4096-bit RSA key, ID C1C47AA57701C1C9, created 2018-08-19
      "Bob Builder <[email protected]>"

x secrets/passwords
x secrets/ch3@t_c0d3z
gpg: Signature made Wed Jul  3 21:55:08 2019 CDT
gpg:                using RSA key F476448049BA78F02133C96552F778CFEAAE2FC5
gpg:                issuer "[email protected]"
gpg: Good signature from "Alice <[email protected]>" [full]

You know have the following directory contents:

.
├── secrets
│   ├── ch3@t_c0d3z
│   └── passwords
└── secrets.tar.gz.gpg

Further Reading

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment