GPGit guides you through 5 simple steps to get your software project ready with GPG signatures. Further details can be found below.

1. Generate a new GPG key

1.1 Strong, unique, secret passphrase

Make sure that your new passphrase for the GPG key meets high security standards. If the passphrase/key is compromised all of your signatures are compromised too.

Here are a few examples how to keep a passphrase strong but easy to remember:

1.2 Key generation

If you don’t have a GPG key yet, create a new one first. You can use RSA (4096 bits) or ECC (Curve 25519) for a strong key. GPG offers you the option to use the most future-proof key algorithm available. Use the most recent version gnupg2, not gnupg1!

Ed25519 ECC GPG keys are still not supported by every software/platform. To generate an RSA key use rsa4096 instead of future-default as parameter.

Make sure that your secret key is stored somewhere safe and use a unique strong password.

Example key generation:

$ gpg2 --quick-generate-key "John Doe <john@doe.com>" future-default default 1y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 2F8E73B1D445CCD3 marked as ultimately trusted
gpg: revocation certificate stored as '/home/john/.gnupg/openpgp-revocs.d/6718A9A63030E182A86FEE152F8E73B1D445CCD3.rev'
public and secret key created and signed.

pub   ed25519 2017-09-24 [SC] [expires: 2018-09-24]
      6718A9A63030E182A86FEE152F8E73B1D445CCD3
uid                      John Doe <john@doe.com>
sub   cv25519 2017-09-24 [E]

The generated key has the fingerprint 6718A9A63030E182A86FEE152F8E73B1D445CCD3 in this example. Share it with others so they can verify your source. [Read more]

If you ever move your installation make sure to backup ~/.gnupg/ as it contains the private key and the revocation certificate. Handle it with care. [Read more]

2. Publish your key

2.1 Send GPG key to a key server

To make the public key widely available, upload it to a key server. Now the user can get your key by requesting the fingerprint from the keyserver: [Read more]

# Publish key
gpg2 --keyserver hkps://keyserver.ubuntu.com --send-keys <fingerprint>

# Import key
# Alternative keyserver: hkps://hkps.pool.sks-keyservers.net
gpg2 --keyserver hkps://keyserver.ubuntu.com --recv-keys <fingerprint>

2.2 Publish full fingerprint

To make it easy for everyone else to find your key it is crucial that you publish the full fingerprint on a trusted platform, such as your website or Github. To give the key more trust other users can sign your key too. [Read more]

2.3 Associate GPG key with Github

To make Github display your commits as “verified” you also need to add your public GPG key to your Github profile. [Read more]

# List keys + full fingerprint
gpg2 --list-secret-keys --keyid-format LONG

# Generate public key
gpg2 --armor --export <fingerprint>

# If you have multiple uids or signatures you can minimize the output:
gpg2 --armor --export --export-filter keep-uid="uid =~ <email>" --export-options export-minimal <fingerprint>

3. Use Git with GPG

3.1 Configure Git GPG key

In order to make Git use your GPG key you need to set the default signing key for Git. [Read more]

# List keys + full fingerprint
gpg2 --list-secret-keys --keyid-format LONG

git config --global user.signingkey <fingerprint>

3.2 Enable commit signing

To verify the Git history, Git commits needs to be signed. You can manually sign commits or enable it by default for every commit. It is recommended to globally enable Git commit signing. [Read more]

git config --global commit.gpgsign true

3.3 Create signed Git tag

Git tags need to be created from the command line and always need a switch to enable tag signing. [Read more]

# Creates a signed tag
git tag -s 1.0.0

# Re-tag an older, unsigned tag
git tag -sf 1.0.0 1.0.0

# Verifies the signed tag
git tag -v 1.0.0

4. Create a signed release archive

4.1 Create compressed archive

You can use git archive to create archives of your tagged Git release. It is highly recommended to use a strong compression which is especially beneficial for those countries with slow and unstable internet connections. [Read more]

# .tar.gz
git archive --format=tar.gz -o gpgit-1.0.0.tar.gz --prefix gpgit-1.0.0/ 1.0.0

# .tar.xz
git archive --format=tar --prefix gpgit-1.0.0/ 1.0.0 | xz > gpgit-1.0.0.tar.xz

4.2 Sign the archive

Type the filename of the tarball that you want to sign and then run:

gpg2 --personal-digest-preferences SHA512 --armor --detach-sign gpgit-1.0.0.tar.xz

Do not blindly sign the Github source downloads unless you have compared its content with the local files via diff. [Read more]

To not need to retype your password every time for signing you can also use gpg-agent.

This gives you a file called gpgit-1.0.0.tar.xz.asc which is the GPG signature. Release it along with your source tarball and let everyone know to first verify the signature after downloading. [Read more]

gpg2 --verify gpgit-1.0.0.tar.xz.asc

4.3 Create the message digest

Message digests are used to ensure the integrity of a file. It can also serve as checksum to verify the download. Message digests do not replace GPG signatures. They rather provide and alternative simple way to verify the source. Make sure to provide message digest over a secure channel like https.

sha512sum gpgit-1.0.0.tar.xz > gpgit-1.0.0.tar.xz.sha512

5. Upload the release

5.1 Configure HTTPS download server

5.2 Upload to Github

Create a new “Github Release” to add additional data to the tag. Then drag the .tar.xz .sig and .sha512 files onto the release.

The script also supports uploading to Github directly. Create a new Github token first and then follow the instructions of the script. How to generate a Github token:

Go to “Settings – Personal access tokens”
Generate a new token with permissions public_repo and admin:gpg_key. In order to access private repositories you must allow access to the whole repo scope.
Store it safely
You can also store the token inside the git config: git config --global gpgit.token <token>

Appendix

Email Encryption

You can also use your GPG key for email encryption with thunderbird.

Update key expire date

After renewing the GPG key expire date make sure to publish your GPG key again to the keyserver and update your website accordingly. A more detailed instruction can be found at G-Loaded Journal.

gpg2 --edit-key <fingerprint>
gpg> expire
gpg> 1y
gpg> key 1
gpg> expire
gpg> 1y
gpg> save