Skip to content
An S/MIME signing utility for use with Git
Branch: master
Clone or download
Latest commit 7e96b8b May 7, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
windows-installer sign installer Oct 1, 2018
.appveyor.yml add back the v for the tag name May 2, 2019
.gitignore appveyor: generate resource.syso file before build to be embedded in … Sep 18, 2018
.travis.yml fix release naming May 2, 2019
CODE_OF_CONDUCT.md add code of conduct Sep 10, 2018
CONTRIBUTING.md add contributing docs Sep 10, 2018
LICENSE.md rename. add readme. add license Nov 29, 2017
MAINTAINING.md Create MAINTAINING.md Apr 3, 2019
README.md Update README with windows installation step Jan 15, 2019
command_sign.go add var f definition Apr 2, 2019
command_sign_test.go include chain minus root by default Sep 5, 2018
command_verify.go
compiler_error_linux.go try to get a better compiler error on linux Oct 31, 2018
go.mod use go modules instead of dep May 1, 2019
go.sum use go modules instead of dep May 1, 2019
list_keys_command.go separate listed identities with newlines instead of em dashes Nov 28, 2018
main.go appveyor: generate resource.syso file before build to be embedded in … Sep 18, 2018
main_test.go Merge branch 'master' into include-certs Sep 5, 2018
parse_user_id.go get signing working Nov 22, 2017
status.go output signature info to stderr May 7, 2019
utils.go implement --list-keys command Nov 29, 2017

README.md

smimesign (S/MIME Sign) Windows Build Status MacOS Build Status

Smimesign is an S/MIME signing utility for macOS and Windows that is compatible with Git. This allows developers to sign their Git commits and tags using X.509 certificates issued by public certificate authorities or their organization's internal certificate authority. Smimesign uses keys and certificates already stored in the macOS Keychain or the Windows Certificate Store.

This project is pre-1.0, meaning that APIs and functionality may change without warning.

Contributing

Different organizations do PKI differently and we weren't able to test everyone's setup. Contributions making this tool work better for your organization are welcome. See the contributing docs for more information on how to get involved.

Git Signing, GnuPG, PKI, and S/MIME

Git allows developers to sign their work using GnuPG. This is a form of public key cryptography whereby the notion of trust is distributed. The party verifying a signature may directly know of the signer's identity and public key, or the signer's identity may be vouched for by a third party known to the verifier. Through layers of "vouching", a web-of-trust is established.

Such a model is well suited to an unstructured environment. In hierarchical environments though, such as a corporation or other large organizations, a simpler approach is for digital identities to be issued and vouched for by a centralized authority. With this approach — known as Public Key Infrastructure, or PKI — an organization's certificate authority (CA) issues signed certificates that identify subjects such as people or computers. Embedded in these certificates is the identity's public key, allowing others who trust the CA to verify that identity's signatures.

PKI is used in a variety of applications for encrypting or authenticating communications. Secure Mime (S/MIME) standardized a protocol for encrypting and signing emails using PKI. While protecting email was the original intent, S/MIME can protect any type of data, including Git commits and tags. Signing Git data with S/MIME provides the same protections as GnuPG while allowing for the more hierarchical trust model of PKI.

Installation

macOS

You can install smimesign using Homebrew:

brew install smimesign

You can also download a prebuilt macOS binary here. Put the binary on your $PATH, so Git will be able to find it.

Windows

You can install smimesign using scoop:

scoop install smimesign

You can download prebuilt Windows binaries here. Put the appropriate binary on your %PATH%, so Git will be able to find it.

Building from source

  • Make sure you have the Go compiler installed.
  • You'll probably want to put $GOPATH/bin on your $PATH.
  • Run go get github.com/github/smimesign

Configuring Git

Git needs to be told to sign commits and tags using smimesign instead of GnuPG. This can be configured on a global or per-repository level. The Git configuration directives for changing signing tools was changed in version 2.19.

Git versions 2.19 and newer

Configure Git to use smimesign for a single repository:

$ cd /path/to/my/repository
$ git config --local gpg.x509.program smimesign
$ git config --local gpg.format x509

Configure Git to use smimesign for all repositories:

$ git config --global gpg.x509.program smimesign
$ git config --global gpg.format x509

Git versions 2.18 and older

Configure Git to use smimesign for a single repository:

$ cd /path/to/my/repository
$ git config --local gpg.program smimesign

Configure Git to use smimesign for all repositories:

$ git config --global gpg.program smimesign

Configuring smimesign

No configuration is needed to use smimesign. However, you must already have a certificate and private key in order to make signatures. Furthermore, to sign Git commits or tags, it is best to have a certificate that includes your Git email address.

Find your Git email address:

$ git config --get user.email

List available signing identities

$ smimesign --list-keys

Smart cards (PIV/CAC/Yubikey)

Many large organizations and government agencies distribute certificates and keys to end users via smart cards. These cards allow applications on the user's computer to use private keys for signing or encryption without giving them the ability to export those keys. The native certificate stores on both Windows and macOS can talk to smart cards, though special drivers or middleware may be required.

If you can find your certificate in the Keychain Access app on macOS or in the Certificate Manager (certmgr) on Windows, it will probably work with smimesign. If you can't find it, you may need to install some drivers or middlware.

Yubikey

Many Yubikey models support the PIV smart card interface. To get your operating system to discover certificates and keys on your Yubikey, you may have to install the OpenSC middleware. On macOS avoid installing OpenSC using homebrew, as it omits an important component. Instead use the installer provided by OpenSC or use the homebrew-cask formula.

Additionally, to manage the manage certificates and keys on the Yubikey on macOS, you'll need the Yubikey PIV Manager (GUI) or the Yubikey PIV Tool (command line).

Yubikey PIV Keychain in macOS Keychain Access app

You can’t perform that action at this time.