diff options
Diffstat (limited to 'doc/encryption.mdwn')
| -rw-r--r-- | doc/encryption.mdwn | 112 |
1 files changed, 78 insertions, 34 deletions
diff --git a/doc/encryption.mdwn b/doc/encryption.mdwn index d93bee9d2..cea46045e 100644 --- a/doc/encryption.mdwn +++ b/doc/encryption.mdwn @@ -6,50 +6,94 @@ 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. +Such an encrypted remote uses strong ([[symmetric|design/encryption]] or +asymmetric) 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. +to disable encryption. To use encryption, you run +run `git-annex initremote` in one of these ways: -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. +* `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 [[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 ... -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: +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. - git annex enableremote myremote encryption=788A3F4C +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: -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. + git annex enableremote myremote keyid+=788A3F4C -## shared cipher mode +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 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 amoung 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. +**unencrypted** in the git repository. So it's shared among every +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.) + +(Because filenames are MAC'ed, a cipher still needs to be +generated (and encrypted to the given key IDs).) + +## MAC algorithm + +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. |