mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

reword docs

Browse source
This commit is contained in:
Joey Hess 2013-09-04 20:11:25 -04:00
parent 6e09893160
commit b30a322093
1 changed files with 74 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

138
doc/encryption.mdwn
View file

@ -15,14 +15,81 @@ remote.
You should decide whether to use encryption with a special remote before You should decide whether to use encryption with a special remote before
any data is stored in it. So, `git annex initremote` requires you 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 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 * `git annex initremote newremote type=... encryption=hybrid keyid=KEYID ...`
encrypt file contents, run `git annex initremote` with * `git annex initremote newremote type=... encryption=shared`
"encryption=hybrid keyid=USERID". The value will be passed to `gpg` to * `git annex initremote newremote type=... encryption=pubkey keyid=KEYID ...`
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 ## hybrid encryption keys
for matching 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 ...
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, 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 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 The default MAC algorithm to be applied on the filenames is HMACSHA1. A
stronger one, for instance HMACSHA512, one can be chosen upon creation stronger one, for instance HMACSHA512, one can be chosen upon creation
@ -30,60 +97,3 @@ of the special remote with the option `mac=HMACSHA512`. The available
MAC algorithms are HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and MAC algorithms are HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and
HMACSHA512. Note that it is not possible to change algorithm for a HMACSHA512. Note that it is not possible to change algorithm for a
non-empty remote. non-empty remote.
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:
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:
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 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
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.