Commit Signing

It's possible to configure git with any name and email, enabling bad actors to spoof commits and impersonate whomever they want. GitHub supports several ways to digitally sign git commits, verifying that they came from someone with access to a previously configured private key.

For example, on 3 August 2022, Stephen Lacy shared on Twitter how he uncovered a massive malware attack on GitHub by noticing unverified commits (i.e. commits that were not digitally signed).

To protect against commit spoofing, all Bitwarden contributors are encouraged to digitally sign their commits.

Setting up commit signing

Github supports commit signing with GPG, SSH and S/MIME.

tip

If you're unsure what to use, we recommend you create a commit signing key using SSH. Remember to protect the key with a strong passphrase or password. Alternatively set up your yubikey as your signing key.

# path to save your private signing key
KEY_FILE=~/.ssh/bw-signing
ssh-keygen -f $KEY_FILE -C "$(git config --global --get user.email)" -t ed25519

Configuration

1. Configure git to sign using SSH.

   git config --global gpg.format ssh
   git config --global user.signingkey "${KEY_FILE}.pub"

2. Follow the Github documentation to configure commit signing

3. Configure your preferred git tool below

4. Push a test commit to Github and ensure that the "Verified" badge appears next to the commit description:

   

Command Line

• After configuring commit signing, you can sign a commit by using the -S flag:

  git commit -S

• To avoid using the -S flag every time, you can sign all commits and tags by default:

  git config --global commit.gpgSign true
  git config --global tag.gpgSign true

Hardware-backed SSH Keys

For contributors who want maximum security, hardware-backed SSH keys using FIDO2/U2F security keys (like YubiKeys) provide superior protection by storing private keys on hardware that cannot be extracted or copied.

Benefits of Hardware-backed Keys

• Physical presence required: Each signing operation requires touching the hardware key
• Locked private keys: Private keys are generated on and never leave the hardware
• Tamper-resistant: Hardware provides protection against physical and software attacks
• Multi-factor authentication: Combines something you have (the key) with something you know (PIN)

Setting up sk-ed25519 Keys

macOS Users

On macOS, you'll need to install OpenSSH via Homebrew as the system's built-in OpenSSH lacks proper FIDO2 support:

brew install openssh

After installation, restart your terminal to ensure the Homebrew version is used. If it's not then fully qualify the path to the homebrew version of ssh-keygen in the example, like /opt/homebrew/bin/ssh-keygen [everything else].

1. Generate an sk-ed25519 key for commit signing:

   # Generate hardware-backed signing key
   ssh-keygen -t ed25519-sk -f ~/.ssh/bw-signing-sk -C "$(git config --global --get user.email)"

   note

   You'll need to touch your security key when prompted during key generation and each time you sign a commit.

2. Configure git to use your hardware-backed key:

   git config --global gpg.format ssh
   git config --global user.signingkey ~/.ssh/bw-signing-sk.pub
   git config --global commit.gpgSign true
   git config --global tag.gpgSign true

3. Add the public key to your GitHub account following the GitHub documentation

Hardware Key Requirements

• FIDO2/U2F compatible security key (YubiKey 5 series, SoloKeys, etc.)
• OpenSSH 8.2+ with FIDO2 support (on macOS, install via Homebrew: brew install openssh)
• Physical access to the security key for each signing operation

Fallback Strategy

When going the yubikey route it is important to make sure you have the infrastructure set up to recover from the lose of a yubikey. At least one backup plan should be set up. Some ideas:

• Create and configure multiple yubikeys
• Generate both a hardware-backed key and a traditional SSH key:
  • Use the hardware-backed key for day-to-day development
  • Keep a traditional SSH key as a secure backup for emergency situations

Visual Studio Code

Enable commit signing in Preferences -> Settings -> search "commit signing".

macOS: GPG Key Passphrase Prompt Issue

Some macOS users have had issues with VS Code and the gpg-agent not prompting for the GPG Key Passphrase in order to sign commits when using the VS Code git GUI. This is illustrated by VS Code displaying an error popup message: Git: gpg failed to sign the data.

A workaround for this issue is to configure your gpg-agent to use pinentry for macOS in order to force a secure prompt. Run the following in a terminal of your choice:

1. brew install pinentry-mac
2. echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
3. killall gpg-agent

Note: Note: you might have to restart VS Code for this to take effect, but you should now be prompted for your GPG Key Passphrase as needed. If this does not solve your issue, please follow the Troubleshooting guide below.

SourceTree

Refer to Setup GPG to sign commits within SourceTree.

Troubleshooting

• If you receive the error message "error: gpg failed to sign the data", make sure you added export GPG_TTY=$(tty) to your ~/.zshrc (or ~/.bashrc if you're using bash) and restarted your terminal. Refer to this troubleshooting document for more help with this error