Signing Commits

All commits on Github must be signed with a GPG key. The information below provides guidance for getting a GPG key, signing commits locally, and adding your GPG public key to your GitHub account.

Obtain and install GnuPG

A note for Mac users. We recommend getting the full GPG suite for Mac. There are some nice features that help with key management. https://gpgtools.org/

First, check to see if you already have GnuPG installed on your system.

gpg --version
 
# On older Ubuntu and similar
gpg2 --version

If you do have it installed, confirm it is the latest version https://www.gnupg.org/download/. If it is not the latest version, update your installation.

If you don't have it, install the latest version from https://www.gnupg.org/download/

Generate private/public key pair

Confirm what keys you already have

gpg --list-keys

If this is your first time using GnuPG or if you do not already have a current RSA 2048 key, then you will need to generate a new ECC key.

Before you get started with the process of generating a new key, create the passphrase you want to associate with the key. This means create the password. You can use whatever method you typically use for creating a strong password. You need to do this first because the key generator may timeout if you take too long to think of one when you must enter it.

Once you know the passphrase you want to use, enter

gpg --expert --full-gen-key

Select "ECC and ECC" for the type of key. Select NIST P-521 for the elliptic curve.

Select 5 years for the expiration date.

Create your user ID

Confirm

Enter your previously created passphrase

Confirm your new key

gpg --list-keys

Step-by-step guide: setup for signing commits

For full instructions on getting set up to sign commits, see this GitHub article. Summary below:

(Ubuntu) fix your gpg.program config setting

Under Ubuntu et al. you'll need to run:

git config --global gpg.program `which gpg2`

Set your key globally

This sets up a scenario will you will be asked to enter you key passphrase with each new commit, except that your passphrase will be cached for strings of commits.

Select the key you want to use (current RSA2048 or ECC)

gpg --list-secret-keys --keyid-format LONG

Add your selected key (Make sure to use the full key id, and not an abbreviation)

git config --global user.signingkey "your key"

Sign commits specific to the CasperLabs/CasperLabs project

Note - If you want to sign commits globally, you can set this as a global config option.

git config --global commit.gpgSign true

Sign git tags

Signing tags

Git tags can also be signed. The following commands can set the git options globally.

git config --global tag.gpgSign true

git config --global tag.forceSignAnnotated true

Add your public GPG key to your GitHub account

List your keys - this shows subkey fingerprints if you are using a subkey

gpg --list-keys --keyid-format LONG

Export your existing key

gpg --armor --export <key id>

In your GitHub account you use for work with CasperLabs, select your profile image and then select Settings.

In the user settings sidebar, select SSH and GPG keys.

Then select Add GPG key.

What to expect in GitHub

If you are opening a PR with signed commits, GitHub displays the commits as "unverified" until you actually open the PR. Opening the PR cues the display of "verified".

Adding an additional email (commits show up unverified) The email in this signature doesn’t match the committer email.

https://help.github.com/articles/associating-an-email-with-your-gpg-key/

ref https://superuser.com/questions/293184/one-gnupg-pgp-key-pair-two-emails

 $ gpg --edit-key <key-id>
  gpg> adduid
  Real Name: <name>
  Email address: <email>
  Comment: <comment or Return to none>
  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
  Enter passphrase: <password>
  gpg> uid <uid>
  gpg> trust
  Your decision? 5
  Do you really want to set this key to ultimate trust? (y/N) y
  gpg> save
$ gpg --send-keys <key-id>