GPGit

Introduction

As we all know, today more than ever before, it is crucial to be able to trust our computing environments. One of the main difficulties that package maintainers of GNU/Linux distributions face, is the difficulty to verify the authenticity and the integrity of the source code. With GPG signatures it is possible for packagers to verify source code releases quickly and easily.

Overview of the required tasks:

• Create and/or use a 4096-bit RSA/Ed25519 ECC keypair for the file signing
• Use a strong, unique, secret passphrase for the key
• Upload the public key to a key server and publish the full fingerprint
• Sign every new Git commit and tag
• Create signed, compressed release archives
• Upload a strong message digest of the archive
• Configure HTTPS for your download server

<a href="https://www.buymeacoffee.com/nicohood" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>

GPGit

GPGit is meant to bring GPG to the masses. It is not only a shell script that automates the process of creating new signed Git releases with GPG, but also includes a quick-start-guide for learning how to use GPG. GPGit integrates perfectly with the Github Release API for uploading. It can even automatically add a Keep A Changelog formatted changelog to the release.

The security status of GNU/Linux projects will be tracked in the Linux Security Database. If you have any further questions, do not hesitate to contact me personally. Thanks for your help in making GNU/Linux projects more secure by using GPG signatures.

Index

• Introduction
• GPGit Documentation
• GPG Quick Start Guide

GPGit Documentation

Installation

Arch Linux

GPGit is available as official Arch Linux distribution package:

sudo pacman -S gpgit
# Optional dependencies for Github API uploading
sudo pacman -S curl jq

Debian

First install the following dependencies, then follow the manual installation instruction.

# Install dependencies
sudo apt-get install bash gnupg2 git tar xz-utils coreutils gawk grep sed util-linux
# Optional dependencies
sudo apt-get install gzip bzip lzip zstd file jq curl

MacOS

First install the following dependencies with Homebrew, then follow the manual installation instructions.

# Install dependencies
brew install bash git xz gnu-getopt coreutils
# Install a GPG suite, such as https://gpgtools.org/
brew install --cask gpg-suite
# Optional dependencies
brew install gzip bzip2 lzip zstd jq curl

Manual Installation

Dependencies

• bash
• gnupg2
• git
• tar
• xz
• grep
• sed
• gnu awk
• gnu getopt (util-linux)
• gnu date (coreutils)

Optional Dependencies

• gzip (Compression option)
• zstd (Compression option)
• bzip (Compression option)
• lzip (Compression option)
• file (Github API upload)
• jq (Github API upload)
• curl (Github API upload)
• shellcheck (Development: make test)

Installation Instructions

# Download and verify source
VERSION=1.5.0
wget "https://github.com/NicoHood/gpgit/releases/download/${VERSION}/gpgit-${VERSION}.tar.xz"
wget "https://github.com/NicoHood/gpgit/releases/download/${VERSION}/gpgit-${VERSION}.tar.xz.asc"
gpg2 --keyserver hkps://keyserver.ubuntu.com --recv-keys 97312D5EB9D7AE7D0BD4307351DAE9B7C1AE9161
gpg2 --verify "gpgit-${VERSION}.tar.xz.asc" "gpgit-${VERSION}.tar.xz"

# Extract, install and run GPGit
tar -xf "gpgit-${VERSION}.tar.xz"
sudo make -C "gpgit-${VERSION}" PREFIX=/usr/local install
gpgit --help

Script Usage

The script guides you through all 5 steps of the GPG quick start guide. Run GPGit with the tag name as parameter. All other options will get auto detected. When running the script for the first time GPGit runs in interactive (-i) mode and guide you through all steps of secure source code signing.

If you add and commit a CHANGELOG.md file to your Git with the Keep a Changelog format, GPGit will autodetect that file and add the corresponding changelog section to the tag message and Github release notes.

Sample Usage

Parameters and Configuration

$ gpgit --help
Usage: gpgit [options] <tagname> [<commit> | <object>]

GPGit 1.5.0 https://github.com/NicoHood/gpgit
A shell script that automates the process of signing Git sources via GPG.

Mandatory arguments:
  <tagname>                The name of the tag to create.

Optional arguments:
  -h, --help               Show this help message and exit.
  -m, --message <msg>      Use the given <msg> as the commit message.
                           If multiple -m options are given, their values are
                           concatenated as separate paragraphs.
  -C, --directory <path>   Run as if GPGit was started in <path> instead of the
                           current working directory.
  -u, --local-user <keyid> Use the given GPG key (same as --signingkey).
  -o, --output <path>      Safe all release assets to the specified <path>.
  -a, --asset              Add additional Github assets, e.g. software bundles.
  -t, --title              Custom Github release title (instead of tag name).
  -p, --pre-release        Flag as Github pre-release.
  -f, --force              Force the recreation of Git tag and release assets.
  -i, --interactive        Run in interactive mode, step-by-step.
      --<option>           Temporary set a 'gpgit.<option>' from config below.
  <commit>, <object>       The object that the new tag will refer to.

Examples:
  gpgit 1.0.0
  gpgit -p -m "First alpha release." 0.1.0 --hash "sha256 sha512"
  gpgit -C git/myproject/ -o /tmp/gpgit -n -m "Internal test release." 0.0.1

Configuration options:
  gpgit.signingkey <keyid>, user.signingkey <keyid>
  gpgit.output <path>
  gpgit.token <token>
  gpgit.compression <xz | gzip | bzip2 | lzip | zstd | zip>
  gpgit.hash <sha512 | sha384 | sha256 | sha1 | md5>
  gpgit.changelog <auto | true | false>
  gpgit.github <auto | true | false>
  gpgit.githubrepo <username/projectname>
  gpgit.project <projectname>
  gpgit.keyserver <keyserver>

Examples:
  git config --global gpgit.output ~/gpgit
  git config --local user.signingkey 97312D5EB9D7AE7D0BD4307351DAE9B7C1AE9161
  git config --local gpgit.compression "xz zip"

GPG Quick Start Guide

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. Strong, unique, secret passphrase
   2. Key generation
2. Publish your key
   1. Send GPG key to a key server
   2. Publish full fingerprint
   3. Associate GPG key with Github
3. Use Git with GPG
   1. Configure Git GPG key
   2. Enble commit signing
   3. Create signed Git tag
4. Create a signed release archive
   1. Create compressed archive
   2. Sign the archive
   3. Create the message digest
5. Upload the release
   1. Configure HTTPS download server
   2. Upload to Github

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:

• Creating a strong password
• How to Create a Secure Password
• Mooltipass
• Keepass, KeepassXC
• PasswordCard

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/platf