GPG 101

This article is also posted on my blog, feel free refer to it for the latest revisions: gpg-101

GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880(also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications.

This article I will introduce the basic usage of GPG.

What is GPG?

When it comes to GPG, you should know the PGP first. The PGP is a protocol that provides encryption and digital signature services(Pretty Good Privacy). The GPG is the implementation of the PGP protocol. PGP can support many kinds of encryption algorithms, such as AES, RSA, ECC, etc.

And you can add it to your Github to make every commit to your repository is signed.

Do not upload any message to the public key servers, it’s not secure! Do not do any operation related to public key servers! In this article, I will not mention any operation related to public key servers! The public key servers is a centralized service, and will not delete any messages even you have revoked the public key.

Some abbreviations

Usage

A => Authentication (eg. ssh)
C => Certify (Only the primary key have this capability)
E => Encrypt
S => Sign (eg. sign the commit)
? => Unknown capability

Type

sec => Secret Primary Key
ssb => Secret Subkey
pub => Public Primary Key
sub => Public Subkey

Format

• armored: asc
• binary: pgp

Fingerprint

Each key or subkey has a line of 10 groups of 4 characters. This is the SHA-1 hash of the entire key, which is 160 bits, 20 bytes, and is usually represented as 40 hexadecimal numbers. This fingerprint can be used to uniquely identify a key pair.

Key ID

Format:

• Long: the last 16 characters of the fingerprint.
• Short: the last 8 characters of the fingerprint.

UID

UID is the user id which contains the username, comment and email. Name (Comment) <Email>

1. One secret key can have multiple UIDs.
2. UID is used for the whole keys not just for specific subkey.
3. The uid can add easily, but the existing uid cannot be adjusted, only can be revoked.

Validity

When import a key, it will default to [unknown]. You can check the fingerprint and the owner’s claim to verify the key.

Trust network

Trust levels:

• ultimate: Normally you should only ultimately trust your own keys. The root of the trust chain.
• full: Full trust the key, also contains the keys signed by this key.
• marginal: Trust the key, but not fully trust. If three people trust the key, then I trust it.
• never: Never trust the key along with the keys signed by this key.

How to use it?

Installation

brew install gpg

Generate Key

You have to do the following steps quickly. If the process is timeout, you will need to re-do the steps.

gpg --full-generate-key
# 1. Then select the key type, it's fine by default.
# 2. Then select the key expiration, I choose `3y`, because you can renew the key later, and that's make sure you cn still control the key. Expired keys are only invalid for new encryption and signing. But you can still decrypt and verify the existing information, just will be marked as expired.
# 3. Then enter you name(uid), I don't recommend you to use your real name, you can instead of your username.
# 4. Then enter your email, make sure to use the verified email in Github, it's highly recommended to use the `no-reply` email provided by Github to avoid spam.
# 5. Then enter the passphrase, it's used to encrypt the key.
# 6. After a rondom move, your key is generated.

Generate subkey

It is recommended to generate a subkey for the key. And just use the primary key to sign the new subkeys.
Each subkey has its own application scenario.

# Enter the primary key interactive mode
gpg --edit-key yourNameInprimaryKey(uid or keyid)
gpg > addkey
# Then the process is the same as the previous steps. This time I choose the RSA(sign only).
# Btw, before generate the subkey, it will ask you to enter the passphrase of the primary key.
# After the subkey is generated, don't forget to save the key.
gpg > save

Genrate a revocation certificate

Imagine you forget the passphrase of the key, or you lose the control, you can use the revocation certificate to revoke the public key. If not, you will need to notify your friends that you don’t use the key anymore. That will be a big problem. Thus it is necessary to generate a revocation certificate.

gpg --gen-revoke -ao revoke.pgp uid(or keyid)
# Make choices based on your situation

Then you will get a revoke.pgp file, you can use it to revoke the key.

list the keys

gpg --list-keys # list the public keys, you can also use `gpg -k`
gpg --list-secret-keys # list the secret keys, you can also use `gpg -K`

The common usage

# The most common usage! -k or -K
gpg -K --with-fingerprint --with-subkey-fingerprint --keyid-format long

Besides, there are some parameters that you may need to use:

--with-fingerprint # print the fingerprint of the key
--with-subkey-fingerprint # print the fingerprint of the subkey
--with-sig-list # print the signature of keys

Export the key

gpg -ao public-key.txt --export uid(or keyid) # export the public key
# It is better to add your secure path before the secret-key, it will export to the machine directly.
gpg -ao secret-key --export-secret-key primarykeyid! # export the primary secret key, remember to add the `!` to export the single key, or you will export the whole secret keys.
gpg -ao sign-subkey --export-secret-subkeys subkeyid! # export the sign sub secret key.[S]
gpg -ao encrypt-subkey --export-secret-subkeys encryptkeyid! # export the encrypt sub secret key.[E]

Most usage

Besides, GPG private key exported as an ASCII armored version or its base64 encoding (often).

gpg --export-secret-key --armor keyid > secret-key.asc

Delete the key

After Export the keys, you can delete then from the machine.

gpg --delete-secret-keys uid(or keyid) # delete the secret key
gpg --delete-keys uid(or keyid) # delete the public key

As we know, the keys is stored in the machine in plaintext, it will not delete the keys completely, you can use the wipe or other tools to assist. But there is still the risk of restoring the keys. If you really want to generate and delete the keys in the most secure way, you can try Tails(boum.org).

Import the key

Strongly discourage any operation related to public key servers!

gpg --import yourkeysfile(your secret key or others public key)
# output
# the `#` means the primary key is not imported, so it's safe.
# sec#   rsa3072/keyid 2021-01-11 [SC] 
# ...
# the `#` means the subkey is imported.
# ssb #    rsa3072/keyid 2021-01-11 [E]

Sign and verify

# Sign
# 1. generate the binary signature file
gpg --sign input.txt
# 2. generate the ASCII signature file
gpg --clearsign input.txt
# 3. generate the signature file and original file separately.
gpg --armor --detach-sign input.txt

# verify
gpg --verify input.txt.asc input.txt

Encrypt and decrypt

# encrypt
# uid(or keyid) is the uid or keyid of the recipient which means you have to import the public key of the recipient in advance.
gpg --encrypt --recipient uid(or keyid) input.txt --output output.txt
# a simple version
gpg -se -o encrypt.txt -r uid(or keyid) input.txt

# decrypt
gpg --decrypt encrypt.txt --output decrypt.txt

Revoke

Even you have revoke the key, if there is still someone sent you message by the outdated public key, you can decrypt the message as well as the hacker can. This operation import the revocation certificate which will make the whole keys invalid. The revoked key is only invalid for new encryption and signing. But you can still decrypt and verify the existing information, but it will be marked as revoked.

Imagine the scenario, Alice’s secret key is leaked, she will send a key revocation certificate, but the distribution is not centralized, so she cannot make sure everyone has received the message. Besides, the key revocation certificate is need to be signed by the secret key of the Alice, so if the secret key is lost, she will not be able to revoke the key.

So once you have revoked the key, you should push the revoked public key to where you publish the key always, and notify your friends.

# revoke the primary key
# import the public key first
gpg --import gpg-linus.asc
# then import the revoke certificate which will make the public key invalid directly.
gpg --import revoke
# gpg -k to check the key is revoked. eg.[revoked: 2024-01-01]

# revoke the subkey
gpg --edit-key uid(or keyid)
# then select the subkey you want to revoke
gpg > list
gpg > key 1 # 1 is the index of the subkey
gpg > revoke
gpg > save

Config your git

Refer to Github docs and Github docs

Reference

• Github docs
• GnuPG docs
• ulyc blog
• Ruanyifeng blog
• GaoWeiX blog