Transparent file encryption in git

Last update: Dec 30, 2022

Related tags

Overview

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.

git-crypt was written by Andrew Ayer ([email protected]). For more information, see https://www.agwa.name/projects/git-crypt.

Building git-crypt

See the INSTALL.md file.

Using git-crypt

Configure a repository to use git-crypt:

cd repo
git-crypt init

Specify files to encrypt by creating a .gitattributes file:

secretfile filter=git-crypt diff=git-crypt
*.key filter=git-crypt diff=git-crypt
secretdir/** filter=git-crypt diff=git-crypt

Like a .gitignore file, it can match wildcards and should be checked into the repository. See below 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!

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.

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

After cloning a repository with encrypted files, unlock with GPG:

git-crypt unlock

Or with a symmetric key:

git-crypt unlock /path/to/key

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.

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 is provably semantically secure 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).

git-crypt does not support revoking access to an encrypted repository which was previously granted. This applies to both multi-user GPG mode (there's no del-gpg-user command to complement add-gpg-user) and also symmetric key mode (there's no support for rotating the key). This is because it is an inherently complex problem in the context of historical data. For example, even if a key was rotated at one point in history, a user having the previous key can still access previous repository history. This problem is discussed in more detail in https://github.com/AGWA/git-crypt/issues/47.

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.

Files encrypted with git-crypt cannot be patched with git-apply, unless the patch itself is encrypted. To generate an encrypted patch, use git diff --no-textconv --binary. Alternatively, you can apply a plaintext patch outside of git using the patch command.

git-crypt does not work reliably with some third-party git GUIs, such as Atlassian SourceTree and GitHub for Mac. Files might be left in an unencrypted state.

Gitattributes File

The .gitattributes file is documented in the gitattributes(5) man page. The file pattern format is the same as the one used by .gitignore, as documented in the gitignore(5) man page, with the exception that specifying merely a directory (e.g. /dir/) is not sufficient to encrypt all files beneath it.

Also note that the pattern dir/* does not match files under sub-directories of dir/. To encrypt an entire sub-tree dir/, use dir/**:

dir/** filter=git-crypt diff=git-crypt

The .gitattributes file must not be encrypted, so make sure wildcards don't match it accidentally. If necessary, you can exclude .gitattributes from encryption like this:

.gitattributes !filter !diff

Comments

[CI/CD] Add github actions to build windows & linux executables
I created github actions to automate builds for windows and linux. It will be triggered on each change

on: push:

or pull request

on: pull_request:

If the branch or tag contains release, a new release draft will be created.

- name: Create Release if: contains(github.ref, 'release') id: create_release with: draft: true

Since it creates only a draft, the release needs to be published by the owner or a maintainer manually.

Build outputs will be added to this release draft as a zip file.

- name: Upload Release Asset if: contains(github.ref, 'release')
opened by thebino 18
Improve usability/documentation with untrusted GPG keys
Hey @AGWA having a weird issue when I'm trying to add my GPG key, i get the following

gpg: <Key ID>: There is no assurance this key belongs to the named user gpg: [stdin]: encryption failed: Unusable public key git-crypt: GPG error: Failed to encrypt

Any ideas on that one matey?
opened by BrendanThompson 17

git-crypt unlock failing

I have a git repo on bitbucket. I was able to configure git-crypt add secure files lock and unlock. I recently tried cloning the repo and the running git-crypt unlock and it is failing.

> git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

> git-crypt unlock

You need a passphrase to unlock the secret key for
user: "Russell Simpkins (Russ) <[email protected]>"
4096-bit RSA key, ID 065C5B7A, created 2015-04-20 (main key ID 3B3F5A08)

git-crypt: error: encrypted file has been tampered with!
error: external filter "git-crypt" smudge failed 1
error: external filter "git-crypt" smudge failed
fatal: files/secure/appstack/app.properties: smudge filter git-crypt failed
Error: 'git checkout' failed
git-crypt has been set up but existing encrypted files have not been decrypted

Here is my current config

> cat .gitattributes 
files/secure/**/* filter=git-crypt diff=git-crypt

> git-crypt status |grep files/secure
    encrypted: files/secure/appstack/app.properties
    encrypted: files/secure/jenkins/id_jenkins

I thought maybe having the wildcards was causing an issue. I tried pointing at the files e.g.

> cat .gitattributes 
files/secure/appstack/app.properties filter=git-crypt diff=git-crypt
files/secure/jenkins/id_jenkins filter=git-crypt diff=git-crypt

But that did not make a difference.

I'm working on Yosemite 10.10.3. Git-crypt installed using brew to install version 0.4.2

Any thoughts on this? Is it possibly related to bitbucket?

opened by russellsimpkins 14

Clarification on .gitattribute files.
I just tried the new git-crypt version, with asymmetric crypto, I ran git-crypt init on my new repo, and edited the .git-crypt/.gitattributes file to add the specs I wanted. However, I can't get git-crypt to actually encrypt the files. Am I supposed to move the .gitattributes file to the root dir of the repo?

21:24:40 $ cat .gitattributes *.secret filter=git-crypt diff=git-crypt *.key filter=git-crypt diff=git-crypt group_vars/*.yml filter=git-crypt diff=git-crypt secret_keys.py filter=git-crypt diff=git-crypt * !filter !diff
opened by skorokithakis 14
.gitattributes pattern of `dirname/*` or `dirname/` does not encrypt contents

Any sub-directories within dirname/ e.g. dirname/subdirname/secrets.txt will insulate the contents of that sudir from encryption. A directory tree must be specified fully/explicitly in the .gitattributes pattern, to the lowest level, to ensure encryption. This can lead to plain-text being unintentionally pushed. A git-crypt status command seems critical for positively identifying files to be encrypted and catch pattern typos or syntax misunderstandings in .gitattributes.

opened by hobson 14

Issue performing interactive rebases

I was wondering if there is a known problem with interactive rebasing? This happens on a freshly-cloned repo containing git-crypt objects:

$ git clone [email protected]:user/somethinghere.git
$ cd somethinghere
$ git checkout some_branch_name
Switched to branch 'some_branch_name'
Your branch is up-to-date with 'origin/some_branch_name'.
$ git status
On branch some_branch_name
Your branch is up-to-date with 'origin/some_branch_name'.
nothing to commit, working directory clean
$ git rebase -i HEAD~5
Cannot rebase: You have unstaged changes.
Please commit or stash them.
$ git status
On branch some_branch_name
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

Unfortunately I can't share the actual repo that has the issue.

Environment:

git-crypt 0.4.2
Mac os 10.10.3
git version 2.4.0

Thanks for your time!

opened by oskarpearson 12

Major issue - Locked but unlock stopped working.

I've recently encrypt all my files using lock and unlock apparently now broken...

gpg: no valid OpenPGP data found. gpg: decrypt_message failed: Unknown system error git-crypt: GPG error: Failed to decrypt

Is there a way to manually unlock using my existing GPG key?

opened by sysbot 12
Add git-crypt merge driver to support secret files merging.

Add git-crypt merge driver to support secret files merging.

Update clean operation to not alter output when it run multiple times, to match recommended behaviour (https://git-scm.com/docs/gitattributes) -

For best results, clean should not alter its output further if it is run twice ("clean→clean" should be equivalent to "clean"), and multiple smudge commands should not alter clean's output ("smudge→smudge→clean" should be equivalent to "clean"). See the section on merging below.

opened by shlomosh 11
git-crypt unlock doesn't decrypt file

We have added 2 gpg's by doing: git-crypt add-gpg-user USER_ID

Decrypting works for the first user, but when he pushes it and I pull and run git-crypt unlock, I get prompted for the passphrase (MacOS, GPG Suite):

You need a passphrase to unlock the secret key for user: ... 4096-bit RSA key, ID ..., created 2015-08-17 (main key ID ...)

The program then finishes (no error message) but the file is still encrypted.

opened by doender 9
No such file or directory error: external filter .... clean' failed

Not sure how to troubleshoot this one.

I'm syncing my repos to a new machine via dropbox.

when i do git status I get the following...

https://gist.github.com/theoryshaw/d22d41300037d399553d58eb0b6b11ca

The old machine had a C:/path, the new one D:/ for the repos.

Anyone have any troubleshooting suggestions?

github repo, if curious: https://github.com/OpeningDesign/Sports_Complex

opened by theoryshaw 8

Getting build error while building git-crypt on a docker based on ubuntu:14.04

g++ -Wall -pedantic -Wno-long-long -O2 -Wno-deprecated-declarations   -c -o crypto-openssl.o crypto-openssl.cpp
crypto-openssl.cpp:74:11: error: field ‘ctx’ has incomplete type ‘HMAC_CTX {aka hmac_ctx_st}’
  HMAC_CTX ctx;
           ^~~
In file included from /usr/include/openssl/evp.h:14:0,
                 from /usr/include/openssl/hmac.h:15,
                 from crypto-openssl.cpp:36:
/usr/include/openssl/ossl_typ.h:102:16: note: forward declaration of ‘HMAC_CTX {aka struct hmac_ctx_st}’
 typedef struct hmac_ctx_st HMAC_CTX;
                ^~~~~~~~~~~
crypto-openssl.cpp: In destructor ‘Hmac_sha1_state::~Hmac_sha1_state()’:
crypto-openssl.cpp:88:27: error: ‘HMAC_cleanup’ was not declared in this scope
  HMAC_cleanup(&(impl->ctx));
                           ^
<builtin>: recipe for target 'crypto-openssl.o' failed

Unfortunately I am not quite sure how to track down a fix.

opened by richtera 8

Cannot build statically-linked binary

I'm trying to build a statically-linked binary as I have that I cannot use git-crypt on Oracle Linux 9.1 (and I have become pretty dependent on it).

I add the CXXFLAGS from the Makefile and add -static and -pthread, but I get these errors:

$ CXXFLAGS='-Wall -pedantic -Wno-long-long -O2 -static -pthread' make
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o git-crypt.o git-crypt.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o commands.o commands.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o crypto.o crypto.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o gpg.o gpg.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o key.o key.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o util.o util.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o parse_options.o parse_options.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o coprocess.o coprocess.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o fhstream.o fhstream.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o crypto-openssl-10.o crypto-openssl-10.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11   -c -o crypto-openssl-11.o crypto-openssl-11.cpp
g++ -Wall -pedantic -Wno-long-long -O2 -static -pthread -std=c++11 -o git-crypt git-crypt.o commands.o crypto.o gpg.o key.o util.o parse_options.o coprocess.o fhstream.o crypto-openssl-10.o crypto-openssl-11.o -lcrypto
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(b_addr.o): in function `BIO_lookup_ex':
(.text+0xcef): warning: Using 'getaddrinfo' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(b_sock.o): in function `BIO_gethostbyname':
(.text+0x71): warning: Using 'gethostbyname' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(dso_dlfcn.o): in function `dlfcn_globallookup':
(.text+0x13): undefined reference to `dlopen'
/usr/bin/ld: (.text+0x26): undefined reference to `dlsym'
/usr/bin/ld: (.text+0x31): undefined reference to `dlclose'
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(dso_dlfcn.o): in function `dlfcn_pathbyaddr':
(.text+0x72): undefined reference to `dladdr'
/usr/bin/ld: (.text+0xe7): undefined reference to `dlerror'
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(dso_dlfcn.o): in function `dlfcn_bind_func':
(.text+0x3f7): undefined reference to `dlsym'
/usr/bin/ld: (.text+0x4c2): undefined reference to `dlerror'
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(dso_dlfcn.o): in function `dlfcn_load':
(.text+0x531): undefined reference to `dlopen'
/usr/bin/ld: (.text+0x5a9): undefined reference to `dlclose'
/usr/bin/ld: (.text+0x5e5): undefined reference to `dlerror'
/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/10/../../../x86_64-linux-gnu/libcrypto.a(dso_dlfcn.o): in function `dlfcn_unload':
(.text+0x6a4): undefined reference to `dlclose'
collect2: error: ld returned 1 exit status
make: *** [Makefile:50: git-crypt] Error 1

What can I do? I'm using Debian/Ubuntu.

opened by eggbean 0

Error: fails to compile with ENABLE_MAN=yes

When I try to compile with the man file I get this error:

$ make ENABLE_MAN=yes
xsltproc --param man.output.in.separate.dir 1 --stringparam man.output.base.dir man/ --param man.output.subdirs.enabled 1 --param man.authors.section.enabled 1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl man/git-crypt.xml
error : Unknown IO error
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
make: *** [Makefile:58: man/man1/git-crypt.1] Error 4

Anything that can be done about this? (xsltproc is installed)

opened by eggbean 0

make git-crypt add-gpg-user -k default fool-proof

Unlike most other keys, the default key is encoded using the name default in the file system, but inside the key name is empty. If one actually stores the key name default inside, the key is rejected by validate_key_name.

If one does git-crypt add-gpg-user without -k, the default key is being used leaving the key name empty and things work. If one specifies -k default however, it actually stores the invalid key name default. The resulting key file is always rejected by validate_key_name.

This commit changes the behaviour of -k default to behave as if no -k were given.

It is not entirely clear to me whether this change would have prevented #230.

opened by helmutg 0

Unlock is failing under Windows and Linux (smudge filter failed).

I installed the official version released (git-crypt-0.7.0-x86_64.exe) for Windows and tried to unlock my repository. It seems it fails with some files. Possible encoding problem? This repo is being used successfully in Unix envs.

PS C:\Users\Edu\Documents\GitHub\zettelkasten> git-crypt-0.7.0-x86_64.exe unlock
git-crypt: error: encrypted file has been tampered with!
error: external filter '"C:\\Program Files\\git-crypt\\git-crypt-0.7.0-x86_64.exe" smudge' failed 1
error: external filter '"C:\\Program Files\\git-crypt\\git-crypt-0.7.0-x86_64.exe" smudge' failed
fatal: Company/secrets/git/README.md: smudge filter git-crypt failed
Error: 'git checkout' failed
git-crypt has been set up but existing encrypted files have not been decrypted

The same error is happening in Ubuntu Linux.

opened by edpichler 3

feature request - unlock - log files that are decrypted

:wave: Was playing about with git crypt in a deployment workflow. Discovered to my surprise it's a little confusing to track down if a key unlocks anything or not. (Especially when using multiple keys.)

To help users troubleshoot, perhaps the unlock subcommand could gain a -v flag to log all files that are decrypted.

opened by winny- 0