add gcrypt tip

2 files changed, 100 insertions, 0 deletions

diff --git a/doc/special_remotes/gcrypt.mdwn b/doc/special_remotes/gcrypt.mdwn
index 063d1fb58..06ac3c23e 100644
--- a/doc/special_remotes/gcrypt.mdwn
+++ b/doc/special_remotes/gcrypt.mdwn
@@ -4,6 +4,9 @@ remote allows git-annex to also store its files in such repositories.
 Naturally, git-annex encrypts the files it stores too, so everything
 stored on the remote is encrypted.
 
+See [[tips/fully_encrypted_git_repositories_with_gcrypt]] for some examples
+of using gcrypt.
+
 ## configuration
 
 These parameters can be passed to `git annex initremote` to configure
diff --git a/doc/tips/fully_encrypted_git_repositories_with_gcrypt.mdwn b/doc/tips/fully_encrypted_git_repositories_with_gcrypt.mdwn
new file mode 100644
index 000000000..4ac9b3b17
--- /dev/null
+++ b/doc/tips/fully_encrypted_git_repositories_with_gcrypt.mdwn
@@ -0,0 +1,97 @@
+[git-remote-gcrypt](https://github.com/blake2-ppc/git-remote-gcrypt/)
+adds support for encrypted remotes to git. The git-annex 
+[[gcrypt special remote|special_remotes/gcrypt]] allows git-annex to
+also store its files in such repositories. Naturally, git-annex encrypts
+the files it stores too, so everything stored on the remote is encrypted.
+
+Here are some ways you can use this awesome stuff..
+
+## prerequisites
+
+* Install
+[git-remote-gcrypt](https://github.com/blake2-ppc/git-remote-gcrypt/)
+* Install git-annex version 4.20130909 or newer.
+
+## encrypted backup drive
+
+Let's make a USB drive into an encrypted backup repository. It will contain
+both the full contents of your git repository, and all the files you
+instruct git-annex to store on it, and everything will be encrypted so that
+only you can see it.
+
+First, you need to set up a gpg key. You might consider generating a
+special purpose key just for this use case, since you may end up wanting to
+put the key on multiple machines that you would not trust with your
+main gpg key. You need to tell git-annex the keyid of the key.
+
+	git init --bare /mnt/encryptedbackup
+	git annex initremote encryptedbackup type=gcrypt gitrepo=/mnt/encryptedbackup keyid=$mykey
+	git annex sync encryptedbackup
+	git annex copy --to encryptedbackup ...
+
+Note that if you lose your gpg key, it will be *impossible* to get the
+data out of your encrypted backup. You need to find a secure way to store a
+backup of your gpg key. Printing it out and storing it in a safe deposit box,
+for example.
+
+You can actually specifiy keyid= as many times as you like to allow any one
+of a set of gpg keys to access this repository. So you could add a friend's
+key, or another gpg key you have.
+
+To restore from the backup, just plug the drive into any machine that has
+the gpg key used to encrypt it, and then:
+
+	git clone /mnt/encryptedbackup restored
+	cd restored
+	git annex enableremote encryptedbackup gitrepo=/mnt/encryptedbackup
+	git annex get --from encryptedbackup
+
+## encrypted git-annex repository on a ssh server
+
+If you have a ssh server that has git-annex and rsync installed, you can
+set up an encrypted repository there. Works just like the encrypted drive
+except without the cable.
+
+First, on the server, run:
+
+	git init --bare encryptedrepo
+
+Now, in your existing git-annex repository:
+
+	git annex initremote encryptedrepo type=gcrypt gitrepo=ssh://my.server/home/me/encryptedrepo keyid=$mykey
+	git annex sync encryptedrepo
+	git annex copy --to encryptedrepo ...
+
+If you're going to be sharing this repository with others, be sure to also
+include their keyids, by specifying keyid= repeatedly.
+
+Now that the repo is set up, anyone who has access to it and has one of the keys
+used to encrypt it can check it out:
+
+	git clone ssh://my.server/home/me/encryptedrepo myrepo
+	cd myrepo
+	git annex enableremote encryptedrepo gitrepo=ssh://my.server/home/me/encryptedrepo
+	git annex get --from encryptedrepo
+
+## private encrypted git remote on hosting site
+
+You can use gcrypt to store your git repository in encrypted form on any
+hosting site that supports git. Only you can decrypt its contents.
+Using it this way, git-annex does not store large files on the hosting site; it's
+only used to store your git repository itself.
+
+	git remote add encrypted gcrypt::ssh://hostingsite/myrepo.git
+	git config git push encrypted master git-annex
+
+Now you can carry on using git-annex with your new repository. For example,
+`git annex sync` will sync with it.
+
+## multiuser encrypted git remote on hosting site
+
+Suppose two users want to share an encrypted git remote. Both of you
+need to set up the remote, and configure gcrypt to encrypt it so that both
+of you can see it.
+	
+	git remote add sharedencrypted gcrypt::ssh://hostingsite/myrepo.git
+	git config remote.sharedencrypted.gcryt-participants "$mykey $friendkey"
+	git config git push sharedencrypted master git-annex