Merge branch 'encryption'

1 files changed, 43 insertions, 15 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 269588add..7afe5fd13 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -307,19 +307,30 @@ subdirectories).
   types of special remotes need different configuration values. The
   command will prompt for parameters as needed.
 
-  All special remotes support encryption. You must either specify
-  encryption=none to disable encryption, or use encryption=keyid
-  (or encryption=emailaddress) to specify a gpg key that can access
-  the encrypted special remote.
-
-  Note that with encryption enabled, a gpg key is created. This requires
-  sufficient entropy. If initremote seems to hang or take a long time
-  while generating the key, you may want to ctrl-c it and re-run with --fast,
-  which causes it to use a lower-quality source of randomness.
+  All special remotes support encryption. You can either specify
+  `encryption=none` to disable encryption, or specify 
+  `encryption=hybrid keyid=$keyid ...` to specify a gpg key id (or an email
+  address accociated with a key.
+
+  There are actually three schemes that can be used for management of the
+  encryption keys. When using the encryption=hybrid scheme, additional
+  gpg keys can be given access to the encrypted special remote easily
+  (without re-encrypting everything). When using encryption=shared,
+  a shared key is generated and stored in the git repository, allowing
+  anyone who can clone the git repository to access it. Finally, when using
+  encryption=pubkey, content in the special remote is directly encrypted
+  to the specified gpg keys, and additional ones cannot easily be given
+  access.
+
+  Note that with encryption enabled, a cryptographic key is created.
+  This requires sufficient entropy. If initremote seems to hang or take
+  a long time while generating the key, you may want to ctrl-c it and
+  re-run with --fast, which causes it to use a lower-quality source of
+  randomness.
 
   Example Amazon S3 remote:
 
-	git annex initremote mys3 type=S3 encryption=me@example.com datacenter=EU
+	git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU
 
 * enableremote name [param=value ...]
 
@@ -335,11 +346,28 @@ subdirectories).
   For example, the directory special remote requires a directory= parameter.
 
   This command can also be used to modify the configuration of an existing
-  special remote, by specifying new values for parameters that were originally
-  set when using initremote. For example, to add a new gpg key to the keys
-  that can access an encrypted remote:
-
-	git annex enableremote mys3 encryption=friend@example.com
+  special remote, by specifying new values for parameters that were
+  originally set when using initremote. (However, some settings such as
+  the as the encryption scheme cannot be changed once a special remote
+  has been created.)
+
+  The gpg keys that an encrypted special remote is encrypted to can be
+  changed using the keyid+= and keyid-= parameters. These respectively
+  add and remove keys from the list. However, note that removing a key
+  does NOT necessarily prevent the key's owner from accessing data
+  in the encrypted special remote
+  (which is by design impossible, short of deleting the remote).
+
+  One use-case of keyid-= is to replace a revoked key with
+  a new key:
+
+	git annex enableremote mys3 keyid-=revokedkey keyid+=newkey
+
+  Also, note that for encrypted special remotes using plain public-key
+  encryption (encryption=pubkey), adding or removing a key has NO effect
+  on files that have already been copied to the remote. Hence using
+  keyid+= and keyid-= with such remotes should be used with care, and
+  make little sense except in cases like the revoked key example above.
 
 * trust [repository ...]