git-annex mostly does not use encryption. Anyone with access to a git repository can see all the filenames in it, its history, and can access any annexed file contents.
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 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 use encryption, you run
git-annex initremote
in one of these ways:
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 ...
git annex initremote newremote type=... encryption=sharedpubkey keyid=KEYID ...
hybrid encryption keys (encryption=hybrid)
The hybrid key design allows additional encryption keys to be added on to a special remote later. Due to this flexibility, 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=id@joeyh.name" 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
it 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 for other security risks associated with encryption.
shared encryption key (encryption=shared)
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 (encryption=pubkey)
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 disadvantage is that it 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.)
(A cipher still needs to be generated (and is encrypted to the given key IDs). It is only used for HMAC encryption of filenames.)
regular public key encryption with shared filename encryption (encryption=sharedpubkey)
This is a variation on encryption=pubkey which lets anyone who has access to the gpg public keys store files in the special remote. But, only owners of the corresponding private keys can retrieve the files from the special remote.
git annex initremote newremote type=... encryption=sharedpubkey keyid=KEYID ...
This might be useful if you want to let others drop off files for you in a special remote, so that only you can access them.
The filenames used on the special remote are encrypted using HMAC, which prevents the special remote from seeing the filenames. But, anyone who can clone the git repository can access the HMAC cipher; it's stored unencrypted in the git repository.
MAC algorithm
The default MAC algorithm to be applied on the filenames is HMACSHA1. A
stronger one, for instance HMACSHA512, 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.
I have a gcrypt special remote encrypted in hybrid mode, when I try to add a keyid using:
I get this error:
this is my git-annex version info:
am I doing something wrong? thank you Giovanni
@Giovanni, git is complaining that there is already a remote named "myremote" enabled in the current repository. Perhaps you have reused this name for a different remote.
(This seems to have nothing to do with the page the comment was posted to, which is a bit annoying. Please post questions in the forum and not attached to random other pages.)
Run "git annex info specialremote" and it will describe the encryption settings of the remote, including gpg keys where applicable.
Needs a fairly recent git-annex.
git show git-annex:remote.log
can also be used.In shared mode, is a single key used to encrypt every file in the repository? Or is a new key created for each file?
Shared mode has the properties I need - getting access to the git repo should give you access to all the content. BUT, if one loses access to updates to the git repo, they should not have access to files added after they lost access.
@gavinwahl, it's a single shared key that any clone of the repository provides access to.
If you use the tahoe special remote, storing files in tahoe-lafs does result in a new capability (a kind of key) being stored in the git repo. So someone with an old clone can't access the files from tahoe-lafs. Tahoe is unique in providing that ability.