Jay Taylor's notes
back to listing indexgit-crypt - transparent file encryption in git
[web search]Directory
Download
Latest release: 0.6.0 (2017-11-26)
Mailing Lists
Source Code
git clone https://www.agwa.name/git/git-crypt.git
git clone https://github.com/AGWA/git-crypt.git
You are here: Andrew's Site → Projects → git-crypt
git-crypt - transparent file encryption in git
git-crypt enables transparent encryption and decryption of files in a git repository. Files which you choose to protect are encrypted when committed, and decrypted when checked out. git-crypt lets you freely share a repository containing a mix of public and private content. git-crypt gracefully degrades, so developers without the secret key can still clone and commit to a repository with encrypted files. This lets you store your secret material (such as keys or passwords) in the same repository as your code, without requiring you to lock down your entire repository.
Using git-crypt
Setting up git-crypt
Configure a repository to use git-crypt:
$ cd repo
$ git-crypt init
Specify files to encrypt by creating a .gitattributes file in the repository, like this:
secretfile filter=git-crypt diff=git-crypt
*.key filter=git-crypt diff=git-crypt
Like a .gitignore file, it can match wildcards and should be checked into the repository. See the README for more information about .gitattributes. Make sure you don't accidentally encrypt the .gitattributes file itself (or other git files like .gitignore or .gitmodules). Make sure your .gitattributes rules are in place before you add sensitive files, or those files won't be encrypted!
GPG Mode
Share the repository with others (or with yourself) using GPG:
$ git-crypt add-gpg-user USER_ID
USER_ID can be a key ID, a full fingerprint, an email address, or anything else that uniquely identifies a public key to GPG (see "HOW TO SPECIFY A USER ID" in the gpg man page). Note: git-crypt add-gpg-user will add and commit a GPG-encrypted key file in the .git-crypt directory of the root of your repository.
After cloning a repository with encrypted files, unlock with:
$ git-crypt unlock
Symmetric Mode
Alternatively, you can export a symmetric secret key, which you must securely convey to collaborators (GPG is not required, and no files are added to your repository):
$ git-crypt export-key /path/to/keyfile
After cloning a repository with encrypted files, unlock with:
$ git-crypt unlock /path/to/keyfile
That's all you need to do - after git-crypt is set up (either with git-crypt init or git-crypt unlock), you can use git normally - encryption and decryption happen transparently.
Motivation
I wanted to make a configuration management repository open for others to look at and contribute to (à la Wikimedia's Puppet repository). However, the repository contained secret material, like SSL keys and passwords. git-crypt was developed so the secret material could be protected without having to remove it from the repository (which is what Wikimedia had to do).
Getting git-crypt
Building from Source (latest official release)
Download and extract git-crypt-0.6.0.tar.gz (PGP signature) and run:
$ cd git-crypt-0.6.0
$ make
# make install
To install to a specific location:
# make install PREFIX=/usr/local
Installing from Homebrew (latest official release)
$ brew install git-crypt
Building from Git (development version; less stable and with no compatibility guarantee)
$ git clone https://www.agwa.name/git/git-crypt.git
$ cd git-crypt
$ make
# make install
Verifying the Source
Since version 0.4, all tarballs and Git tags are signed by my PGP key, EF5D 84C1 838F 2EB6 D896 8C04 1037 8EFC 2080 080C.
Dependencies
To use git-crypt, you need:
- Git 1.7.2 or newer (Git 1.8.5 or newer is recommended for best performance)
- OpenSSL
To build git-crypt, you need a C++ compiler, and OpenSSL development headers. The Makefile is tailored for g++, but other compilers should work too.
Current Status
The latest version of git-crypt is 0.6.0, released on 2017-11-26. git-crypt aims to be bug-free and reliable, meaning it shouldn't crash, malfunction, or expose your confidential data. However, it has not yet reached maturity, meaning it is not as documented, featureful, or easy-to-use as it should be. Additionally, there may be backwards-incompatible changes introduced before version 1.0.
Security
git-crypt is more secure than other transparent git encryption systems. git-crypt encrypts files using AES-256 in CTR mode with a synthetic IV derived from the SHA-1 HMAC of the file. This mode of operation provides semantic security under deterministic chosen-plaintext attack. That means that although the encryption is deterministic (which is required so git can distinguish when a file has and hasn't changed), it leaks no information beyond whether two files are identical or not. Other proposals for transparent git encryption use ECB or CBC with a fixed IV. These systems are not semantically secure and leak information.
Limitations
git-crypt relies on git filters, which were not designed with encryption in mind. As such, git-crypt is not the best tool for encrypting most or all of the files in a repository. Where git-crypt really shines is where most of your repository is public, but you have a few files (perhaps private keys named *.key, or a file with API credentials) which you need to encrypt. For encrypting an entire repository, consider using a system like git-remote-gcrypt instead. (Note: no endorsement is made of git-remote-gcrypt's security.)
git-crypt does not encrypt file names, commit messages, symlink targets, gitlinks, or other metadata.
git-crypt does not hide when a file does or doesn't change, the length of a file, or the fact that two files are identical (see "Security" section above).
Files encrypted with git-crypt are not compressible. Even the smallest change to an encrypted file requires git to store the entire changed file, instead of just a delta.
Although git-crypt protects individual file contents with a SHA-1 HMAC, git-crypt cannot be used securely unless the entire repository is protected against tampering (an attacker who can mutate your repository can alter your .gitattributes file to disable encryption). If necessary, use git features such as signed tags instead of relying solely on git-crypt for integrity.
Copyright © 2018 Andrew Ayer. All rights reserved.