A Developer's Guide to PGP Keys - Create, Use, Back Up, and Restore
PGP (Pretty Good Privacy) refers to the OpenPGP standard for cryptographic encryption that can be used to sign, encrypt, and authenticate messages.
The GnuPG (GNU Privacy Guard) software implements the standard that provides the tool called gpg for PGP-related operations.
PGP is widely used in free software projects. Developers sign their commit messages, maintainers sign the tags, and the projects often include PGP signatures with release archives (such as tarballs) so end users can verify the integrity of the code, ensuring it hasn’t been altered.
A PGP key serves as your digital identity in the open-source software world. As long as you (and only you) have your PGP key, you will preserve your identity and verify it is actually you, even if you change organizations, email addresses, or modes of communication.
This guide will help you generate PGP keys (main key and subkeys), and provide instructions on backing them up and restoring them.
Generate PGP keys
Generate certification key
Certification key is the main key. As long as you have the certification key, you can always generate subkeys and alter as many identities as you want.
To generate the certification key, run the following command:
1
gpg --quick-generate-key 'Full Name <your@email.id>' rsa4096 cert
You should enter your complete name and email address in the command, which will serve as your user identity (uid). Below is an example of how to do this:
1
gpg --quick-generate-key 'Nayab Sayed <basha@example.org>' rsa4096 cert
When prompted, enter a strong passphrase to secure your key, as it is essential for encrypting the private key. The directory ~/.gnupg stores these encrypted keys. Ensure you securely note down this certification key passphrase, as you will frequently need it.
Record the 40-character fingerprint from the command output, which appears like this: 4B8CA236D7EBA46185EDC6AFD7CC4C93DF8938E1. Alternatively, you can run the following command to view the fingerprint. This fingerprint is required for all PGP-related operations.
1
gpg --list-keys | grep "pub rsa4096" -A 1 | awk 'NR == 2{$1=$1;print}'
Add additional UIDs
A PGP key can contain multiple UIDs, typically consisting of a full name and email address. You can set up distinct UIDs for personal and professional use.
To add an additional uid, run the following:
1
gpg --quick-add-uid [fingerprint] 'Nayab Sayed <nayab@example.com>'
Replace [fingerprint] with the 40 character fingerprint obtained from above. Do the same for the rest of the post.
You can check the list of UIDs added with the following command:
1
gpg --list-key [fingerprint] | grep ^uid
Generate subkeys
Let’s create PGP subkeys for encryption, signing, and authentication. Generating subkeys requires many random bytes from a random number generator. Moving your mouse around during this process can expedite generation.
1
2
3
gpg --quick-add-key [fingerprint] cv25519 encr # subkey for encryption
gpg --quick-add-key [fingerprint] ed25519 sign # subkey for signing
gpg --quick-add-key [fingerprint] ed25519 auth # subkey for authentication
You can view the subkeys info from the following command:
1
gpg --list-secret-keys
Here is the sample output:
1
2
3
4
5
6
7
8
9
/home/nsd/.gnupg/pubring.kbx
-------------------------------
sec rsa4096 2024-12-15 [C] [expires: 2027-12-15]
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uid [ unknown] Nayab Sayed <XXXXXXXXX@xxxxxxx.xxx>
uid [ultimate] Nayab Sayed <XXXXXXXXXXX@xxxxxx.xxxx>
ssb cv25519 2024-12-15 [E]
ssb ed25519 2024-12-15 [S]
ssb ed25519 2024-12-15 [A]
You can see the indicators [C], [E], [S], [A] representing certification key, encryption key, signing key and authentication key respectively.
Upload keys to the keyservers
Sharing your public key on a keyserver allows other developers to locate it using your email address, download it, and verify your code’s integrity.
Let’s upload our public keys to the following key servers:
- Github
- OpenPGP keyserver
- Ubuntu keyserver
Upload keys to GitHub
Execute the command below and copy the output. Then, navigate to https://github.com/settings/keys, select ‘GPG keys’, and choose ‘New GPG key’ to paste the output.
1
gpg --export --armor [fingerprint]
Upload keys to https://keys.openpgp.org
1
gpg --export <primary@email.id> | curl -T - https://keys.openpgp.org
Here is an example:
1
gpg --export basha@example.org | curl -T - https://keys.openpgp.org
The previous step uploads your keys to https://keys.openpgp.org. Remember to verify your email addresses by clicking the link provided in the command output. Without this verification, others will not be able to find you through your email addresses.
Upload keys to https://keyserver.ubuntu.com
Run the following command to export keys to Ubuntu keyserver.
1
gpg --send-keys --keyserver keyserver.ubuntu.com [fingerprint]
Using the PGP keys
PGP integration with git
With your PGP keys configured and published to keyservers, you’re all set to sign your Git commits and tags.
Signing
To sign a tag, run:
1
git tag -s <tag_name> -m "Message"
To sign a commit, run:
1
git commit -S
Verifying
To verify a commit, run:
1
git verify-commit <hash>
To verify a tag, run:
1
git verify-tag <tagname>
When dealing with mailing lists for patch submissions, using signed commits can be impractical because signatures are stripped when sending mail. Instead, consider using a tool like b4 to submit your signed patches through mailing lists.
Backup and Restore PGP keys
It’s crucial to back up your PGP keys and ensure their security. Here are two methods for backing up and restoring your keys.
Backup/Restore GnuPG directory
By default, GnuPG stores all encrypted keys and configuration files in the ~/.gnupg directory. Ensure you back up this directory to an offline encrypted storage. Refer to this guide for instructions on backing up and restoring PGP keys using an encrypted USB flash drive.
Print a hard copy of certification key
You can use a tool known as paperkey to extract the secret data from your certification key, apply a password for protection, and print it out on paper. Follow this guide to back up and restore your PGP key using paperkey.
Use the security key hardware
There is always a risk of subkey exposure due to malware or other vulnerabilities. Transferring your subkeys to an external security key enhances protection, as the cryptographic processes occur within the security key itself, preventing the operating system from accessing the subkeys. Follow this guide to transfer your subkeys to secure hardware.
Configure PGP password cache interval
If the password is expired from ccache, you need to enter again. You can change how often you have to enter passphrase with the following settings in the ~/.gnupg/gpg-agent.conf file.
1
2
default-cache-ttl 1800 # 30 min
max-cache-ttl 7200 # 2 hours
Change expiry date of keys
The certification key has the default expiry period of 2 years. You can change the expiry date of certification with the following command:
1
gpg --quick-set-expire [fingerprint] 2035-01-01
Send updated keys to servers with the following command:
1
gpg --send-key [fingerprint]
Miscellanous
Change primay UID
1
gpg --quick-set-primary-uid [fingerprint] 'Nayab Sayed <other@email.id'