mirror of
https://github.com/AGWA/git-crypt.git
synced 2025-12-12 15:49:32 -08:00
1c905faeb5
Since the git-crypt mailing lists have barely been used, and mailing lists seem to be falling out of fashion for open source projects, I've decided to shut down the git-crypt mailing lists in favor of functionality provided by GitHub. For announcements of new releases, you can watch the git-crypt repository (https://github.com/AGWA/git-crypt) for new releases. For bug reports, you can file an issue: https://github.com/AGWA/git-crypt/issues For discussions, you can use GitHub's new discussions feature: https://github.com/AGWA/git-crypt/discussions
161 lines
6.5 KiB
Plaintext
161 lines
6.5 KiB
Plaintext
ABOUT GIT-CRYPT
|
|
|
|
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 <agwa@andrewayer.name>. For more
|
|
information, see <https://www.agwa.name/projects/git-crypt>.
|
|
|
|
|
|
BUILDING GIT-CRYPT
|
|
|
|
See the INSTALL 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 <https://spwhitton.name/tech/code/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 <https://jira.atlassian.com/browse/SRCTREE-2511>
|
|
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
|