Alpine Linux on WSL

Sign your commits on Github

Or, Configuring Keychain for SSH and GPG keys

Personal update

I have been self-abducted for the last 3 months in a dark closet writing code for the U.S. Gov’t, that closet being my home in Brooklyn. As you can imagine, I was so engrossed in my work that my writing in Medium took a heavy hit.

I’m happy to be back in form today with a new story about adding GPG signatures to Git commits. As most things in this publication for the last 2–3 years, this story is relevant if you (like me) are one of the niche users of Alpine Linux in Windows Subsystem for Linux (WSL).

Maybe I should write more articles aimed towards more generic topics such as JavaScript, Drupal, and Ubuntu!

Either way, I hope after a few tumultuous years of pandemic and lock downs everyone’s staying mentally and physically safe out there. Seriously, please take care of yourselves and those around you!!

Without further ado…

Install system dependencies

The GPG package is not available in Alpine v3.14 or below. It is currently only available in Alpine v3.15 and above.

To add GPG in Alpine, type sudo apk add gpg:

Install the Alpine gpg package

Similar to an SSH key, which can also be used to authenticate to Github, GPG keys are easier to use if managed using an agent and a keychain. The purpose of the agent is to load SSH or GPG keys. The purpose of the keychain is to manage the agent, and to ensure only one agent is running at once.

For GPG keys in Alpine Linux, the gpg-agent package takes care of loading the keys from disk into memory. The keychain package takes care of managing agents for both SSH and GPG keys.

Running sudo apk add keychain gpg-agent will take care of installing these two packages.

Configure keychain in Bash

Since the keychain package manages the agents, you only need to invoke the keychain binary, no need to invoke either GPG or SSH agents. All you need in your .bashrc or equivalent is the following template:

/usr/bin/keychain \
--dir ~/.ssh/.keychain \
--gpg2 --agents gpg,ssh \
<path to your ssh key> \
<path to your gpg key>
source ~/.ssh/.keychain/$HOST-sh
source ~/.ssh/.keychain/$HOST-sh-gpg
# Set GPG environment.
export GPG_TTY=$(tty)

Opening a new window will execute your .bashrc, which will then execute the keychain binary with the above parameters. When both SSH and GPG agents are being invoked by the keychain, the output should look something similar to this:

Starting gpg-agent and ssh-agent

In this example keychain does not give any output about adding GPG keys because I haven’t added any yet, creating a GPG key and adding it to the agent is the next step.

Creating a new GPG key

To create a new GPG key use the command gpg --full-generate-key --expert:

Select option #9 for ECC and ECC

Select option #9, ECC and ECC, then select option #1, Curve 25519:

Select option #1 for Curve 25519 (ECC)

If you run into an error that says gpg: failed to start agent , it means that you haven’t installed the GPG agent package correctly, and should visit the previous section of this story.

You must construct additional pylons!

After selecting your elliptic curve algorithm above, GPG is going to ask for a few more details such as your name and email. Once you’ve filled those the key is generated and the output should be similar to the one below:

Output after a new master key is created

Congratulations, you have created your new GPG key!

But wait, there’s more!

When you create a new GPG key for the first time, a master key is created. That master key should be used to create additional keys (called sub keys) for different roles.

To add a sub key for signing commits sent to Github, Bitbucket, etc., you can use the command:

gpg --expert --edit-key <your master key id>

Once you enter that command, you are presented with a gpg> prompt:

Once you type addkey in the prompt, GPG is going to ask you what kind of sub key you want to create. In this case I’m only interested in creating a key for signing Git commits, so I will select option #10: ECC (sign only).

Option #10: Create a sub key for signing only using ECC

Then select option #1, Curve 25519 :

Select the sub key’s algorithm (option #1)

Once the new sub key is created, you will notice that the master key will gain a new entry with the specified usage S which, stands for signing:

A new signing key is added

Make sure to type save in the gpg> prompt or otherwise your changes will be thrown out!

Export GPG key to Github

After the sub key is created, use this command to print the sub key in a format that you can paste into Github:

# gpg --armor --export <your signing sub key id here>
gpg --armor --export AAB64F7FBD193141

For example:

Copy your public GPG key

Then go to github.com/settings/profile and click where it says SSH and GPG keys:

From the SSH and GPG keys page select New GPG key:

You will get a text box where you can paste the output from the GPG export command above:

Configure Git to use GPG key

Once you save your signing key into your Git provider, you will want to configure your local Git to use your GPG key for signing commits.

This is something that you can do globally (use the same key for all projects), or on a per-repository basis. I for example might use one signing key for verifying my employer’s commits, and another signing key for all my open source contributions into Drupal or NPM.

The following commands will configure my local Git to use signing key AAB64F7FBD193141 for all my local Git projects, since the majority of my projects are employer related:

git config --global user.email "rallen@bctpartners.com"
git config --global user.name "Richard Allen"
git config --global user.signingkey AAB64F7FBD193141

Important: you need to make sure that the name and email you specified when previously creating the GPG key matches the user.email and user.name parameters you will enter into git config, otherwise Git might not be able to sign your commits.

Push your changes to your repo !

With GPG up and running, next time you push to your remote Github repo, you will see that your commits are being signed:

Github confirms commits are Verified

If you click on the Verified button next to each commit, a pop up will show you the details about who signed that particular commit, and which GPG key was used for the signature:

Github identifies what key was used for signing each commit

Troubleshooting

GPG agent giving you grief? I’ve replicated these steps with decent success:

# kill and restart the gpg agent
gpgconf --kill gpg-agent
# restart Alpine on WSL
wsl.exe -t Alpine

If the agent doesn’t want to talk to you:

Error connecting to agent: Connection refused

Check again your .bashrc or equivalent configuration file. Depending on the Windows version, you may have to change the following lines:

source ~/.ssh/.keychain/$HOSTNAME-sh
source ~/.ssh/.keychain/$HOSTNAME-sh-gpg

In Windows 10, the correct environment variable is $HOST , whereas in Windows 11, $HOSTNAME is valid and $HOST does not exist.

I forgot what keys do I have:

gpg --list-keys

I want to list the public keys currently available:

gpg -k --keyid-format LONG

Same, but using fingerprints:

gpg -k --keyid-format LONG --fingerprint

Conclusion

Signing commits or tags is not something necessarily for everyone to partake on, and every developer or organization should weight the advantages and disadvantages prior to integrating it to their development workflow. There has definitely been healthy amount of discussion for the last 20 years regarding the subject, but here’s a list I compiled to get you started if you fancy to dig deeper into the subject:

• Emily Williams Cryptography 101: Symmetric Encryption story, based on Stanford University’s Cryptography I course on Coursera.
• A case against using GPG and signing commits by Dan Lorenc from Chainguard (a Kubernetes and Docker security provider): Should You Sign Git Commits?
• Fellow Medium writer Risan Bagja’s article on switching to ECC algorithm Ed25519.
• Current GNU Privacy Guard 2 (GPG) release on Alpine (Edge), version 2.2.x.
• GNU Privacy Guard homepage.
• ECC (Elliptic Curve Cryptography) is supported starting in GPG version 2.1. Release notes for GPG 2.1.
• GPG 2.1 release notes regarding ECC support.
• RFC 6637 Elliptic Curve Cryptography (ECC) in OpenPGP, June 2012.
• Stack Overflow, ECC in (Open)PGP, asked in 2013. Another S.O. question, asked in 2013: How can I use GnuPG with ECDSA keys?
• Some of the configuration files I use my Alpine WSL instances.
• Github: Adding a new GPG key to your GitHub account.
• Git Handbook: 7.4 Git Tools — Signing Your Work
• Another article: How (and why) to sign Git commits.
• On a deeper and more philosophical end: What are the advantages and disadvantages of cryptographically signing commits and tags in Git?
• A Git Horror Story: Repository Integrity With Signed Commits