reword docs

1 files changed, 64 insertions, 54 deletions

diff --git a/doc/encryption.mdwn b/doc/encryption.mdwn
index 2069ee3bb..cea46045e 100644
--- a/doc/encryption.mdwn
+++ b/doc/encryption.mdwn
@@ -15,75 +15,85 @@ 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.
+to disable encryption. To use encryption, you run 
+run `git-annex initremote` in one of these ways:
 
-If you want to generate a cipher that will be used to symmetrically
-encrypt file contents, run `git annex initremote` with
-"encryption=hybrid keyid=USERID".  The value will be passed to `gpg` to
-find encryption keys.  Typically, you will say "keyid=2512E3C7" to use a
-specific gpg key.  Or, you might say "keyid=joey@kitenet.net" to search
-for matching keys.
+* `git annex initremote newremote type=... encryption=hybrid keyid=KEYID ...`
+* `git annex initremote newremote type=... encryption=shared`
+* `git annex initremote newremote type=... encryption=pubkey keyid=KEYID ...`
 
-The default MAC algorithm to be applied on the filenames is HMACSHA1. A
-stronger one, for instance HMACSHA512, one can be chosen upon creation
-of the special remote with the option `mac=HMACSHA512`. The available
-MAC algorithms are HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and
-HMACSHA512. Note that it is not possible to change algorithm for a
-non-empty remote.
+## hybrid encryption 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 enableremote` specifying the
-new encryption key:
+The [[hybrid_key_design|design/encryption]] allows additional
+encryption keys to be added on to a special remote later. Due to this
+flexability, it is the default and recommended encryption scheme.
+ 
+	git annex initremote newremote type=... [encryption=hybrid] keyid=KEYID ...
+
+Here the KEYID(s) are passed to `gpg` to find encryption keys. 
+Typically, you will say "keyid=2512E3C7" to use a specific gpg key.
+Or, you might say "keyid=joey@kitenet.net" to search for matching keys.
+
+To add a new key and allow it to access all the content that is stored
+in the encrypted special remote, just run `git annex
+enableremote` specifying the new encryption key:
 
 	git annex enableremote myremote keyid+=788A3F4C
 
-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:
+While a key can later be removed from the list, note that
+that will **not** necessarily prevent the owner of the key
+from accessing data on the remote (which is by design impossible to prevent,
+short of deleting the remote). In fact the only sound use of `keyid-=` is
+probably to replace a revoked key:
 
 	git annex enableremote myremote keyid-=2512E3C7 keyid+=788A3F4C
 
 See also [[encryption_design|design/encryption]] for other security
 risks associated with encryption.
 
-## shared cipher mode
+## shared encryption key
 
 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 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
-stored in the special remote.
-
-To use shared encryption, specify "encryption=shared" when first setting
-up a special remote.
-
-## strict public-key encryption
-
-Special remotes can also be configured to encrypt file contents using
-public-key cryptography. It is significatly slower than symmetric
-encryption, but is also generally considered more secure. Note that
-because filenames are MAC'ed, a cipher needs to be generated (and
-encrypted to the given key ID).
-
-A disavantage is that is not possible to give/revoke anyone's access to
-a non-empty remote. Indeed, although the parameters `keyid+=` and
-`keyid-=` still apply, they have **no effect** on files that are already
-present on the remote. In fact the only sound use of `keyid+=` and
-`keyid-=` is probably, as `keyid-=` for "encryption=hybrid", to replace
-a (sub-)key by another.
-
-Also, since already uploaded files are not re-encrypted, one needs to
-keep the private part of removed keys (with `keyid-=`) to be able to
-decrypt these files. On the other hand, if the reason for revocation is
+clone of the git repository. 
+	
+	git annex initremote newremote type=... encryption=shared
+
+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 stored in the special remote.
+
+## regular public key encryption
+
+This alternative simply encrypts the files in the special remotes to one or
+more public keys. It might be considered more secure due to its simplicity
+and since it's exactly the way everyone else uses gpg.
+
+	git annex initremote newremote type=.... encryption=pubkey keyid=KEYID ...
+
+A disavantage is that is not easy to later add additional public keys
+to the special remote. While the `enableremote` parameters `keyid+=` and
+`keyid-=` can be used, they have **no effect** on files that are already
+present on the remote. Probably the only use for these parameters is 
+to replace a revoked key:
+
+	git annex enableremote myremote keyid-=2512E3C7 keyid+=788A3F4C
+
+But even in this case, since the files are not re-encrypted, the revoked
+key has to be kept around to be able to decrypt those files.
+(Of course, if the reason for revocation is
 that the key has been compromised, it is **insecure** to leave files
-encrypted using that old key, and the user should re-encrypt everything.
+encrypted using that old key, and the user should re-encrypt everything.)
+
+(Because filenames are MAC'ed, a cipher still needs to be
+generated (and encrypted to the given key IDs).)
+
+## MAC algorithm
 
-To use strict public-key encryption, specify "encryption=pubkey
-keyid=USERID" when first setting up a special remote.
+The default MAC algorithm to be applied on the filenames is HMACSHA1. A
+stronger one, for instance HMACSHA512, one can be chosen upon creation
+of the special remote with the option `mac=HMACSHA512`. The available
+MAC algorithms are HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and
+HMACSHA512. Note that it is not possible to change algorithm for a
+non-empty remote.