document encryption

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/encryption.mdwn b/doc/encryption.mdwn
new file mode 100644
index 000000000..0f83bb7f9
--- /dev/null
+++ b/doc/encryption.mdwn
@@ -0,0 +1,35 @@
+git-annex mostly does not use encryption. Anyone with access to a git
+repository can see all the filenames in it, its history, and can access
+any annexed file contents.
+
+Encryption is needed when using [[special_remotes]] like Amazon S3, where
+file content is sent to an untrusted party who does not have access to the
+git repository.
+
+Such an encrypted remote uses strong GPG encryption on the contents of files,
+as well as HMAC hashing of the filenames. The size of the encrypted files,
+and access patterns of the data, should be the only clues to what is
+stored in such a remote.
+
+You should decide whether to use encryption with a special remote before
+any data is stored in it. So, `git annex initremote` requires you
+to specify "encryption=none" when first setting up a remote in order
+to disable encryption.
+
+If you want to use encryption, run `git annex initremote` with
+"encryption=USERID". The value will be passed to `gpg` to find encryption keys.
+Typically, you will say "encryption=2512E3C7" to use a specific gpg key.
+Or, you might say "encryption=joey@kitenet.net" to search for matching keys.
+
+The [[encryption_design|design/encryption]] allows additional encryption keys
+to be added on to a special remote later. Once a key is added, it is able
+to access content that has already been stored in the special remote.
+To add a new key, just run `git annex initremote` again, specifying the
+new encryption key:
+
+	git annex initremote myremote encryption=788A3F4C
+
+Note that once a key has been given access to a remote, it's not
+possible to revoke that access, short of deleting the remote. See
+[[encryption_design|design/encryption]] for other security risks
+associated with encryption.