reword docs
This commit is contained in:
Joey Hess
parent
6e09893160
commit
b30a322093
1 changed files with 74 additions and 64 deletions
|
|
@ -15,14 +15,81 @@ 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 ...`
|
||||
|
||||
## 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 ...
|
||||
|
||||
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
|
||||
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
|
||||
HMACSHA512. Note that it is not possible to change algorithm for a
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue