• About
  • How?
  • Why?
• Usage
  • Example
• Install
  • Download
  • Build
• GitHub Verification

vaultsign is a small CLI that can be used to sign (and verify) git commits and tags using HashiCorp’s Vault.

It works both with the out-of-the-box transit backend and LeSuisse’s GPG plugin.

NOTE: You will want the latter for those GitHub ✔️ verified feels.

vaultsign implements just enough of the GPG CLI interface and status protocol to proxy the git originating sign and verify requests onwards to your specified Vault backend endpoint.

Vault’s signature related backends are useful for realising code provenance in regulated and other high security environments.

You might, for example, build and sign software binaries using CI and Vault infrastructure you control, then store them in an artefact repository (such as GitHub’s Releases), and later verify those binaries again with Vault during deployment to cryptographically prove they were built on your terms without tampering.

This works well for deployable artefacts like binaries but gets a little more awkward when some of related deployment collateral is say, IaC files (such as Terraform) living on a VCS branch or tag.

One option here is to tarball up this deployment collateral and sign/store/verify that.

Another is to make use of vaultsign.

With it, the CI process can sign a git commit or, more commonly, a release tag at the same time as it signs the just-cut binaries. Subsequently, they can all be verified together during a deployment.

Doing all of this in your CI/CD infrastructure with Vault removes much of the need to deal with individual employee GPG keys or X.509 certificates (for S/Mime) to achieve code provenance at the VCS level.

There is a built-in help that you may find useful:

vaultsign --help

vaultsign 1.0.0
Martin Baillie <[email protected]>
Sign/verify git commits using HashiCorp Vault.

USAGE:
    vaultsign [FLAGS] [OPTIONS] <--sign|--verify> [FILE]...

FLAGS:
    -a, --armor          Create ASCII armored output
    -b, --detach-sign    Make a detached signature
    -h, --help           Prints help information
    -s, --sign           Make a signature
    -V, --version        Prints version information
    -v, --verify         Verify a signature

OPTIONS:
        --keyid-format <keyid_format>           Select how to display key IDs [possible values: long]
    -u, --local-user <local_user>               USER-ID to sign or decrypt
        --status-fd <status_fd>                 Write special status strings to the file descriptor n. [possible values:
                                                1, 2]
        --vault_addr <vault_addr>               Vault address to use for sign and verify actions [env: VAULT_ADDR]
                                                [default: http://127.0.0.1:8200]
        --vault_sign_path <vault_sig_path>      The Vault path to use for sign actions [env: VAULT_SIGN_PATH]  [default:
                                                transit/sign/test/sha2-256]
        --vault_verify_path <vault_ver_path>    The Vault path to use for verify actions [env: VAULT_VERIFY_PATH]
                                                [default: transit/verify/test]

ARGS:
    <FILE>...

NOTE:
    The vaultsign CLI implements just enough of the full GPG CLI interface
    for happy-path git sign and verify operations to function correctly.

Mostly, though, you just need to tell your git CLI to use vaultsign:

git config --local gpg.program /path/to/vaultsign

And set some Vault related environment variables:

# The location of your Vault. Mandatory always.
export VAULT_ADDR=https://vault.your.corp:8200

# The signing backend endpoint (transit or gpg) and optionally hashing function
# to use. Mandatory for signing.
export VAULT_SIGN_PATH=transit/sign/test/sha2-256
export VAULT_SIGN_PATH=gpg/sign/test/sha2-256

# The verify backend endpoint (transit or gpg). Mandatory for verifying.
export VAULT_VERIFY_PATH=transit/verify/test
export VAULT_VERIFY_PATH=gpg/verify/test

# The SNI to present during the TLS handshake (if different from the Vault HTTP
# host name). Useful when your Vault is exposed through an AWS private link for
# example. Optional.
export VAULT_TLS_SERVER_NAME=hostname.to.use.for.sni.com

NOTE: vaultsign will discover an existing Vault token from either the environment or the home directory using HashiCorp’s established naming (VAULT_TOKEN) and path (~/.vault-token). The environment takes precedence here.

# Login to your vault.
export VAULT_ADDR=http://127.0.0.1:8200
vault login

# Tell git to use vaultsign.
git config --local gpg.program /path/to/vaultsign

# Sign a commit and tag.
export VAULT_SIGN_PATH=transit/sign/test/sha2-256
git commit -m "test signed commit" -S
git tag -m "test signed tag" -s test

# Verify the same commit and tag.
export VAULT_VERIFY_PATH=transit/verify/test
git verify-commit HEAD
git log -1 --show-signature
git verify-tag test

You can either download a signed static binary release or compile from source for your target architecture.

Always download and verify the latest stable release from the GitHub releases section.

# Import my key.
curl -sS https://github.com/martinbaillie.gpg | gpg --import -

# Verify the authenticity.
gpg --verify SHA256SUMS.sig SHA256SUMS

# Verify the integrity.
shasum -a 256 -c SHA256SUMS

If you are a Nix user then you can take advantage of the shell.nix to provide a functional development environment for compilation and tests.

nix-shell --pure --run "make release"

Otherwise, any sufficiently modern Rust toolchain should be able to compile vaultsign.

NOTE: regarding OpenSSL.

If you are compiling from source, vaultsign links against your system’s native OpenSSL distribution. Ensure you have the dependencies listed in shell.nix.

If you are using the pre-compiled Darwin version from the releases section then it is not static so ensure you have OpenSSL version 1.1 installed.

If you want that coveted GitHub green verified tick for your Vault-signed commits and tags then you must use LeSuisse’s GPG plugin in Vault. GitHub does not know how to verify Vault transit backend signatures.

With that done, you just have to ensure the GPG key email and VCS author email match, i.e.:

• GPG Private key generated/imported in Vault has a real name and email (see here).
• GPG Public key is added to the GitHub user doing the VCS operation, with those same details.