diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/encryption.mdwn | 44 | ||||
| -rw-r--r-- | doc/git-annex.mdwn | 21 |
2 files changed, 52 insertions, 13 deletions
diff --git a/doc/encryption.mdwn b/doc/encryption.mdwn index 6463827af..2069ee3bb 100644 --- a/doc/encryption.mdwn +++ b/doc/encryption.mdwn @@ -6,21 +6,23 @@ 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 -[[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. +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. -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. +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. The default MAC algorithm to be applied on the filenames is HMACSHA1. A stronger one, for instance HMACSHA512, one can be chosen upon creation @@ -61,3 +63,27 @@ 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 +that the key has been compromised, it is **insecure** to leave files +encrypted using that old key, and the user should re-encrypt everything. + +To use strict public-key encryption, specify "encryption=pubkey +keyid=USERID" when first setting up a special remote. diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 832a3cd68..fa74f77d7 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -308,9 +308,15 @@ subdirectories). 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. + encryption=none to disable encryption, or encryption=shared to use a + shared cipher (stored clear in the git repository), or + encryption=hybrid to encrypt the cipher to an OpenPGP key, or + encryption=pubkey to encrypt file contents using public-key + cryptography. In the two last cases, you also need to specify which + key can access the encrypted special remote, which is done by + specifiying keyid= (gpg needs to be to be able to find a public key + matching that specification, which can be an OpenPGP key ID or an + e-mail address for instance). Note that with encryption enabled, a cryptographic key is created. This requires sufficient entropy. If initremote seems to hang or take @@ -320,7 +326,7 @@ subdirectories). 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 ...] @@ -352,6 +358,13 @@ subdirectories). git annex enableremote mys3 keyid-=revokedkey keyid+=newkey + Also, note that for encrypted special remotes using strict 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 unless the private material of the old and new + access list is all owned by the same (group of) person. + * trust [repository ...] Records that a repository is trusted to not unexpectedly lose |