From cffc483f9fb2a0b7529e3b80adb766cbf907becc Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Wed, 4 Sep 2013 20:11:25 -0400 Subject: reword docs --- doc/encryption.mdwn | 118 ++++++++++++++++++++++++++++------------------------ 1 file changed, 64 insertions(+), 54 deletions(-) (limited to 'doc/encryption.mdwn') 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. -- cgit v1.2.3