Mastering GPG: Secure Code Signing with Separate Subkeys Across Multiple Machines

One of my friend, Sadeq, asked a question a few days ago about creating and using GPG keys for signing code commits. he said:

“I have a personal laptop at home that i trust. I want to create a GPG key on it, then, i want to create a separate subkey associated with my work email. I would like to take this subkey to my workplace to sign my code commits without needing to transfer the primary key, which is on my home machine and associated with my personal email, to the work computer. Is this possible? If so, how can I do it?

I have seen several guides, but they seem to suggest that I need to have some part of the primary private key on the work computer to sign with the subkey.”

To answer this question, we need to consider a few things first.

In this post, I aim to guide you through creating a secure key and ensuring its safety. Special thanks to Forud for his insights in his blog post. feel free to suggest improvements.

What is GPG or PGP?

GPG, or GNU Privacy Guard, is a tool for secure communication and data storage. It’s based on PGP (Pretty Good Privacy), an encryption program that provides cryptographic privacy and authentication. Technically, PGP is the encryption algorithm, but I use the open-source GPG program to manage it. You might often hear people say “my GPG key,” but technically, it’s a PGP key managed by GPG.

First, ensure you have the latest version of GPG installed. As of writing this post, the latest official version is 2.4.5.

To check your version, use:

gpg --version

You should see something like:

gpg (GnuPG) 2.4.5 libgcrypt 1.11.0 ... Supported algorithms: Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH, CAMELLIA128, CAMELLIA192, CAMELLIA256 Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224 Compression: Uncompressed, ZIP, ZLIB, BZIP2

GPG works with a pair of keys: a public key and a private key. The public key is meant to be shared widely, while the private key must remain confidential, ideally stored on an isolated system with no internet access. But how do you use the key securely if it’s isolated? For instance, I sign all my Git commits, and transferring each commit to the isolated machine for signing would be impractical. I’ll explain how to keep your key secure while using it seamlessly.

Step-by-Step Key creation and security

Creating a Secure Key. to create a key, use:

gpg --full-gen-key

The process involves selecting an algorithm (the default RSA is usually fine) and setting the key size — opt for a size larger than the default 2048 for better security. Next, you’ll decide on the key’s validity period; I choose “no expiration” for the primary key but set a shorter period for subkeys.

After providing your personal information and email, GPG will prompt you for a passphrase. This step might differ depending on your system’s configuration.

Tip: perform resource-intensive tasks, like disk optimization, while generating the key. The increased system activity enhances the randomness of the generated key, making it more secure.

Adding a Subkey

If you plan to use your key on a less secure system (like a company machine) or if your laptop is stolen, it’s best to create a subkey. A subkey allows you to use your key without exposing the master key.

To add a subkey:

1. Open your key for editing:

gpg --edit-key your@email.com

2. Add a subkey:

addkey

3. Choose the type of subkey (e.g., RSA for signing) and set an expiration date.

Finally, save your changes. Now, when signing commits, you’ll use the subkey instead of the master key.

Note:

No need to separately associate the email you give to the master key with the subkey. When you create a subkey, it automatically gets linked to the master key and uses the identity (including the email) of the master key. So the email defined on the master key is sufficient and valid for the subkey as well. In other words, subkeys inherit the identity of the master key, and there’s no need to set a separate email for each subkey.

Creating a Revocation Certificate

If your key is compromised, a revocation certificate allows you to invalidate it. Create this certificate immediately after generating your key:

gpg --output revoke-cert.asc --gen-revoke your@email.com

Store the revocation certificate securely, away from your key. Consider printing it and hiding it in a safe place.

Exporting Keys

1. Export your public key to share it:

gpg --export --armor your@email.com > public-key.asc

2. Export your private key (keep this file secure):

gpg --export-secret-keys --armor your@email.com > private-key.asc

If you want to use a subkey and remove the master key from your system:

3. Export the subkey:

gpg --export-secret-subkeys your@email.com > subkey.asc

4. Delete the master key:

gpg --delete-secret-key your@email.com

3. Import the subkey:

gpg --import subkey.asc

4. Securely delete the subkey file.

You can verify the result with:

gpg --list-secret-keys

The sec# indicates the master key is not present.

Publishing Your Key

To make your public key accessible, publish it to a keyserver:

gpg --send-keys KEY_ID --keyserver hkp://subkeys.pgp.net

Alternatively, you can manually upload it to a service like MIT PGP.

Signing Commits Across Different Machines

1. Generate a GPG Key Pair

On your personal computer, generate a new GPG key pair:

gpg --full-generate-key

Choose appropriate options (e.g., key type, size, expiration).

2. Create a Subkey for Signing

Create a subkey dedicated to signing:

gpg --edit-key <YOUR-KEY-ID>

Then:

gpg> addkey

Select Sign as the key type, and complete the prompts.

3. Export the Subkey

Export the private part of the subkey:

gpg --export-secret-subkeys <YOUR-KEY-ID> > secret-subkeys.asc

Transfer this file securely to your work computer.

4. Import and Use the Subkey on Your Work Computer

On your work computer:

1. Install GPG if not already installed.
2. Import the Subkey:

gpg --import secret-subkeys.asc

3. Configure Git to Use the Subkey:

git config --global user.signingkey <SUBKEY-ID> git config --global commit.gpgSign true

Replace <SUBKEY-ID> with the ID of your subkey.

4. Ensure the Key is Trusted:
Make sure that the imported subkey is marked as trusted. You can do this by opening the GPG console, selecting your key, and setting the trust level with the trust command.

follow these steps to set the trust level:

1. Open GPG and select your key:

gpg --edit-key your@email.com

2. Enter the trust command:

gpg> trust

3. Choose your desired trust level. To fully trust the key, select level 5:

Your decision? 5 (I trust ultimately)

4. Finally, save the changes and exit (save, quit)

gpg> save

Note:

GPG by default uses the last created subkey for signing in older versions. If this is your problem, you need to append an exclamation mark to your key’s ID.

git config - global user.signingKey <id>\!

if you want to use a new and hence last created subkey to sign your commits. remove your current GPG key and then add it again. This may look scary, especially given the warning that “any commits you signed with this key will become unverified after removing it”. However, don’t worry, as we are adding this same key back, those commits will all become verified again. even the commits I made since starting to use subkeys suddenly became verified as well. This same trick works on GitLab. In fact, When a new subkey is added to an existing PGP key on an account, it currently has to be removed and added back to the account to update it on our side.

Signing Git Commits

Git allows you to sign commits with your GPG key, providing verification of the commit’s authenticity. Ensure your GPG key’s email matches your Git identity:

git config --global user.name
git config --global user.email

To sign a commit:

git commit -S -m "Your commit message"

For convenience, you can configure Git to sign all commits by default:

git config --global commit.gpgsign true

Security Considerations

• Protect Your Private Key: Ensure the subkey is kept secure on your work computer.
• Secure Transfer: Use secure methods to transfer the subkey file.
• Backup: Keep backups of your keys in a safe location.
• Revoking Keys: If you revoke your primary key, all subkeys associated with it will become invalid. However, subkeys can be revoked individually without affecting others.
• Email Association: Subkeys are not directly associated with email addresses. Instead, they are linked through the User IDs (UIDs) of the primary key, which include the associated email addresses.

Final Thoughts

At the end of this process, you should have four key files: a public key, a private key with the master key, a private key without the master key, and a revocation certificate. Store them securely, especially keeping the private key and revocation certificate offline.

Managing GPG keys can be complex, but taking these steps will ensure your data remains secure.