From 1843104015c3b7ca15b93e48dc52b6b61a4dd30e Mon Sep 17 00:00:00 2001 From: Darayus Nanavati Date: Sun, 16 Jun 2013 22:20:03 +1000 Subject: [PATCH] convert documentation files to markdown * format section headings, links and code snippets * add .md file extension to trigger pretty rendering on Github * standardize on lowercase typesetting for git-crypt --- INSTALL.md | 40 ++++++++++++++++++ NEWS.md | 21 ++++++++++ README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 INSTALL.md create mode 100644 NEWS.md create mode 100644 README.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..fc868f9 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,40 @@ +Dependencies +------------ + +To use git-crypt, you need: + +* Git 1.6.0 or newer +* OpenSSL +* For decrypted git diff output, Git 1.6.1 or newer +* For decrypted git blame output, Git 1.7.2 or newer + +To build git-crypt, you need a C++ compiler and OpenSSL development +headers. + + +Building GIT-CRYPT +------------------ + +The Makefile is tailored for g++, but should work with other compilers. + + make + cp git-crypt /usr/local/bin/ + +It doesn't matter where you install the git-crypt binary - choose wherever +is most convenient for you. + + +BUILDING A DEBIAN PACKAGE + +Debian packaging can be found in the 'debian' branch of the project +Git repository. The package is built using git-buildpackage as follows: + + $ git checkout debian + $ git-buildpackage -uc -us + + +INSTALLING ON MAC OS X + +Using the brew package manager, simply run: + + $ brew install git-crypt diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..062c7d5 --- /dev/null +++ b/NEWS.md @@ -0,0 +1,21 @@ +News +==== + +######v0.3 (2013-04-05) +* Fix 'git-crypt init' on newer versions of Git. Previously, + encrypted files were not being automatically decrypted after + running 'git-crypt init' with recent versions of Git. +* Allow 'git-crypt init' to be run even if the working tree contains + untracked files. +* 'git-crypt init' now properly escapes arguments to the filter + commands it configures, allowing both the path to git-crypt and the + path to the key file to contain arbitrary characters such as spaces. + +######v0.2 (2013-01-25) +* Numerous improvements to 'git-crypt init' usability. +* Fix gitattributes example in README: the old example showed a colon + after the filename where there shouldn't be one. +* Various build fixes and improvements. + +######v0.1 (2012-11-29) +* Initial release. diff --git a/README.md b/README.md new file mode 100644 index 0000000..cb0086f --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +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 . +For more information, see . + + +Building git-crypt +------------------ +See the INSTALL file. + + +Using git-crypt +--------------- + +Generate a secret key: + + git-crypt keygen /path/to/keyfile + +Configure a repository to use encryption: + + cd repo + git-crypt init /path/to/keyfile + +Specify files to encrypt by creating a .gitattributes file: + + 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. Make sure you don't accidentally encrypt the +.gitattributes file itself! + +Cloning a repository with encrypted files: + + git clone /path/to/repo + cd repo + git-crypt init /path/to/keyfile + +That's all you need to do - after running `git-crypt init`, you can use +git normally - encryption and decryption happen transparently. + + +Current Status +-------------- + +The latest version of git-crypt is 0.3, released on 2013-04-05. +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. + +Development on git-crypt is currently focused on improving the user +experience, especially around setting up repositories. There are also +plans to add additional key management schemes, such as passphrase-derived +keys and keys encrypted with PGP. + + +Security +-------- + +git-crypt is more secure that 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 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. + +The AES key is stored unencrypted on disk. The user is responsible for +protecting it and ensuring it's safely distributed only to authorized +people. A future version of git-crypt may support encrypting the key +with a passphrase. + + +Limitations +----------- + +git-crypt is not designed to encrypt an entire repository. Not only does +that defeat the aim of git-crypt, which is the ability to selectively +encrypt files and share the repository with less-trusted developers, there +are probably better, more efficient ways to encrypt an entire repository, +such as by storing it on an encrypted filesystem. Also note that +git-crypt is somewhat of an abuse of git's smudge, clean, and textconv +features. Junio Hamano, git's maintainer, has said not to do this +, +though his main objection ("making a pair of similar 'smudged' contents +totally dissimilar in their 'clean' counterparts.") does not apply here +since git-crypt uses deterministic encryption. + +git-crypt does not itself provide any authentication. It assumes that +either the master copy of your repository is stored securely, or that +you are using git's existing facilities to ensure integrity (signed tags, +remembering commit hashes, etc.). + + +MAILING LISTS + +To stay abreast of, and provide input to, git-crypt development, consider +subscribing to one or both of our mailing lists: + +Announcements: http://lists.cloudmutt.com/mailman/listinfo/git-crypt-announce +Discussion: http://lists.cloudmutt.com/mailman/listinfo/git-crypt-discuss