README

   1 Automated encryption and decryption in Git repositories
   2 =======================================================
   3
   4 It is possible to use automated encryption and decryption in Git repositories
   5 because of the filter drivers that consist of a clean command and a smudge
   6 command. Where the clean "command is used to convert the contents of worktree
   7 file[s] upon checkin" in a similar way to how the smudge "command is fed the
   8 blob object from its standard input, and its standard output is used to update
   9 the worktree file." (The quotes are from gitattributes(5).)
  10
  11 Working with OpenSSL symmetric-key encrypted files in a repository
  12 ------------------------------------------------------------------
  13
  14 **1)** If one does not know the password to the encrypted files, the workflow is
  15 the same as always: work on the unencrypted files and commit the changes, etc.
  16
  17 **2)** This is not always the case, though. If you are one of the lucky ones
  18 and know the password and the cipher, and want to take part of the encrypted
  19 content (here ending with the file extension ".senc" (symmetric-key
  20 encrypted)), the following commands will do the job:
  21
  22         git clone git://example.com/repository.git
  23         cd repository
  24         git config filter.crypt_sym.clean "openssl CIPHER -a -nosalt -pass pass:PASSWORD"
  25         git config filter.crypt_sym.smudge "openssl CIPHER -a -nosalt -d -pass pass:PASSWORD"
  26         git config diff.crypt_sym.command PATH_TO_crypt_diff
  27         echo '*.senc filter=crypt_sym diff=crypt_sym' >> .git/info/attributes
  28
  29 Then finally checkout the files that you want to decrypt:
  30
  31         git checkout -- FILE.senc FILE2.senc
  32
  33 and work on them as usual.
  34
  35 **Notice** that you must replace CIPHER with the actual cipher that is used, in
  36 this repository "example.senc" is encrypted using aes-256-cbc. The same is with
  37 the PASSWORD, where it is "writecode" in this case. Also PATH\_TO\_crypt\_diff
  38 must be replaced with the path to the shell script crypt\_diff, that is located
  39 in this repository, in order to be able to view plaintext diffs between the
  40 encrypted blob files and the plaintext worktree files.
  41
  42 **3)** To encrypt new files, all you have to do is to create them with the correct
  43 file extension (if not a sole wildcard is used instead of "*.senc" in
  44 .git/info/attributes) and later run `git add`. The same procedure is also used
  45 when initializing a new repository, except that `git init` should be run before
  46 the `git add` and that the two first steps are also skipped (`git clone` and
  47 `cd`) in the process above.
  48
  49 Working with GnuPG public-key encrypted files in a repository
  50 -------------------------------------------------------------
  51
  52 **1)** Same as in the previous subsection.
  53
  54 **2)** Same as in the previous subsection, except that the lucky one, in this
  55 case, is having the private key corresponding to the public key NAME (remember to
  56 change it below). (**Notice** that the "-r" option can be given multiple times,
  57 which leads to broadcast encryption.) Changes made, in the above instructions,
  58 are presented below.
  59
  60         git config filter.crypt_pub.clean "gpg -ea -q --batch --no-tty -r NAME"
  61         git config filter.crypt_pub.smudge "gpg -d -q --batch --no-tty"
  62         git config diff.crypt_pub.command PATH_TO_crypt_diff
  63         echo '*.penc filter=crypt_pub diff=crypt_pub' >> .git/info/attributes
  64
  65 It is recommended to use a specific key pair only for this very repository and
  66 to make sure that it is passwordless as the process is supposed to be
  67 automatic.
  68
  69 **3)** Same as in the previous subsection, except that the file extension for
  70 the encrypted files, in this example, is ".penc" (public-key encrypted) instead
  71 of ".senc".
  72
  73 **CAVEAT**: Two GnuPG public-key encrypted versions of the same file are
  74 different (because of the randomly-generated session keys), which leads to the
  75 fact that Git will track these sort of "unreal changes" that usually occur when
  76 one reverts a change. This is not the case with OpenSSL symmetric-key
  77 encryption when salt is disabled.
  78
  79 See also
  80 --------
  81
  82 [gpg(1)][2], [openssl(1)][3], [gitattributes(5)][4]
  83
  84 [1]: http://stackoverflow.com/questions/1557183/is-it-possible-to-include-a-file-in-your-gitconfig/1558141#1558141
  85 [2]: http://www.gnupg.org/documentation/manpage.en.html
  86 [3]: http://www.openbsd.org/cgi-bin/man.cgi?query=openssl&apropos=0&sektion=1&manpath=OpenBSD+Current&arch=i386&format=html
  87 [4]: http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html