README.html

   1 <h1>Automated encryption and decryption in Git repositories</h1>
   2
   3 <p>It is possible to use automated encryption and decryption in Git repositories
   4 because of the filter drivers that consist of a clean command and a smudge
   5 command. Where the clean "command is used to convert the contents of worktree
   6 file[s] upon checkin" in a similar way to how the smudge "command is fed the
   7 blob object from its standard input, and its standard output is used to update
   8 the worktree file." (The quotes are from gitattributes(5).)</p>
   9
  10 <h2>Working with OpenSSL symmetric-key encrypted files in a repository</h2>
  11
  12 <p><strong>1)</strong> If one does not know the password to the encrypted files, the workflow is
  13 the same as always: work on the unencrypted files and commit the changes, etc.</p>
  14
  15 <p><strong>2)</strong> This is not always the case, though. If you are one of the lucky ones
  16 and know the password and the cipher, and want to take part of the encrypted
  17 content (here ending with the file extension ".senc" (symmetric-key
  18 encrypted)), the following commands will do the job:</p>
  19
  20 <pre><code>git clone git://example.com/repository.git
  21 cd repository
  22 git config filter.crypt_sym.clean "openssl CIPHER -a -nosalt -pass pass:PASSWORD"
  23 git config filter.crypt_sym.smudge "openssl CIPHER -a -nosalt -d -pass pass:PASSWORD"
  24 git config diff.crypt_sym.command PATH_TO_crypt_diff
  25 echo '*.senc filter=crypt_sym diff=crypt_sym' &gt;&gt; .git/info/attributes
  26 </code></pre>
  27
  28 <p>Then finally checkout the files that you want to decrypt:</p>
  29
  30 <pre><code>git checkout -- FILE.senc FILE2.senc
  31 </code></pre>
  32
  33 <p>and work on them as usual.</p>
  34
  35 <p><strong>Notice</strong> 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.</p>
  41
  42 <p><strong>3)</strong> 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 <code>git add</code>. The same procedure is also used
  45 when initializing a new repository, except that <code>git init</code> should be run before
  46 the <code>git add</code> and that the two first steps are also skipped (<code>git clone</code> and
  47 <code>cd</code>) in the process above.</p>
  48
  49 <h2>Working with GnuPG public-key encrypted files in a repository</h2>
  50
  51 <p><strong>1)</strong> Same as in the previous subsection.</p>
  52
  53 <p><strong>2)</strong> Same as in the previous subsection, except that the lucky one, in this
  54 case, is having the private key corresponding to the public key NAME (remember to
  55 change it below). (<strong>Notice</strong> that the "-r" option can be given multiple times,
  56 which leads to broadcast encryption.) Changes made, in the above instructions,
  57 are presented below.</p>
  58
  59 <pre><code>git config filter.crypt_pub.clean "gpg -ea -q --batch --no-tty -r NAME"
  60 git config filter.crypt_pub.smudge "gpg -d -q --batch --no-tty"
  61 git config diff.crypt_pub.command PATH_TO_crypt_diff
  62 echo '*.penc filter=crypt_pub diff=crypt_pub' &gt;&gt; .git/info/attributes
  63 </code></pre>
  64
  65 <p>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.</p>
  68
  69 <p><strong>3)</strong> 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".</p>
  72
  73 <p><strong>CAVEAT</strong>: 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.</p>
  78
  79 <h2>See also</h2>
  80
  81 <p><a href="http://www.gnupg.org/documentation/manpage.en.html">gpg(1)</a>, <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=openssl&amp;apropos=0&amp;sektion=1&amp;manpath=OpenBSD+Current&amp;arch=i386&amp;format=html">openssl(1)</a>, <a href="http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html">gitattributes(5)</a></p>
  82
  83 <p><b><i>The README is from commit 96b05a8f09b64cde71d33fcea09b3c620383bec0.
  84 For the latest version, check the Git repository.</i></b></p>
  85 <p><b><i>In order to contact Je, add your message to the file CONTACT in the
  86 Git repository on the mob branch which is <a
  87 href="http://repo.or.cz/h/mob.html">writable by everyone</a>.</i></b></p>