Allow revocation of OpenPGP keys.

/!\ It is to be noted that revoking a key does NOT necessarily prevent
the owner of its private part from accessing data on the remote /!\

The only sound use of `keyid-=` is probably to replace a (sub-)key by
another, where the private part of both is owned by the same
person/entity:

    git annex enableremote myremote keyid-=2512E3C7 keyid+=788A3F4C

Reference: http://git-annex.branchable.com/bugs/Using_a_revoked_GPG_key/

* Other change introduced by this patch:

New keys now need to be added with option `keyid+=`, and the scheme
specified (upon initremote only) with `encryption=`. The motivation for
this change is to open for new schemes, e.g., strict asymmetric
encryption.

    git annex initremote myremote encryption=hybrid keyid=2512E3C7
    git annex enableremote myremote keyid+=788A3F4C

3 files changed, 42 insertions, 21 deletions

diff --git a/doc/design/encryption.mdwn b/doc/design/encryption.mdwn
index 6a380abe1..377de476e 100644
--- a/doc/design/encryption.mdwn
+++ b/doc/design/encryption.mdwn
@@ -103,14 +103,16 @@ use the special remote.
 
 ## risks
 
-A risk of this scheme is that, once the symmetric cipher has been obtained, it
-allows full access to all the encrypted content. This scheme does not allow
-revoking a given gpg key access to the cipher, since anyone with such a key
-could have already decrypted the cipher and stored a copy. 
+A risk of this scheme is that, once the symmetric cipher has been
+obtained, it allows full access to all the encrypted content. Indeed
+anyone owning a key that used to be granted access could already have
+decrypted the cipher and stored a copy. While it is in possible to
+revoke a key with `keyid-=`, it is designed for a
+[[completely_different_purpose|encryption]].
 
 If git-annex stores the decrypted symmetric cipher in memory, then there
 is a risk that it could be intercepted from there by an attacker. Gpg
-amelorates these type of risks by using locked memory. For git-annex, note
+ameliorates these type of risks by using locked memory. For git-annex, note
 that an attacker with local machine access can tell at least all the
 filenames and metadata of files stored in the encrypted remote anyway,
 and can access whatever content is stored locally.
diff --git a/doc/encryption.mdwn b/doc/encryption.mdwn
index d93bee9d2..6463827af 100644
--- a/doc/encryption.mdwn
+++ b/doc/encryption.mdwn
@@ -6,8 +6,9 @@ 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,
+Such an encrypted remote uses strong
+[[symmetric_encryptiondesign/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.
 
@@ -34,18 +35,25 @@ to access content that has already been stored in the special remote.
 To add a new key, just run `git annex enableremote` specifying the
 new encryption key:
 
-	git annex enableremote myremote encryption=788A3F4C
+	git annex enableremote myremote keyid+=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.
+While a key can later be removed from the list, it is to be noted that
+it does **not** necessarily prevent the owner of the private material
+from accessing data on the remote (which is by design impossible, short
+of deleting the remote). In fact the only sound use of `keyid-=` is
+probably to replace a (sub-)key by another, where the private part of
+both is owned by the same person/entity:
+
+	git annex enableremote myremote keyid-=2512E3C7 keyid+=788A3F4C
+
+See also [[encryption_design|design/encryption]] for other security
+risks associated with encryption.
 
 ## shared cipher mode
 
 Alternatively, you can configure git-annex to use a shared cipher to
 encrypt data stored in a remote. This shared cipher is stored,
-**unencrypted** in the git repository. So it's shared amoung every
+**unencrypted** in the git repository. So it's shared among every
 clone of the git repository. The advantage is you don't need to set up gpg
 keys. The disadvantage is that this is **insecure** unless you
 trust every clone of the git repository with access to the encrypted data
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 7cac9087d..832a3cd68 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -312,10 +312,11 @@ subdirectories).
   (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.
+  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:
 
@@ -336,10 +337,20 @@ subdirectories).
 
   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
+  set when using initremote. With the exception of some configuration values such
+  as the encryption scheme scheme, which cannot be changed once the
+  remote has been created.
+
+  If encryption is enabled and the remote's access limited to one or
+  more OpenPGP key(s), it is possible to give access to another key ID
+  by specifing the keyid+= parameter. While a key can later be removed
+  from the list, it is to be noted that it does NOT necessarily prevent
+  the owner of the private material from accessing data on the remote
+  (which is by design impossible, short of deleting the remote);
+  however, a fine use-case of keyid-= is to replace a revoked key by
+  a new one superseeding it:
+
+	git annex enableremote mys3 keyid-=revokedkey keyid+=newkey
 
 * trust [repository ...]