git-annex/doc/encryption.mdwn

[[!toc]]

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|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 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`

To see what encryption is used for a special remote, run
`git annex info $remote` and look for a line like:

	encryption: hybrid (to gpg keys: AEC828149D85C538 C910D9122512E3C8)

## hybrid encryption keys (encryption=hybrid)

The [[hybrid_key_design|design/encryption]] 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

The KEYID is passed to `gpg` to find a gpg key.
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 keyid to add:

	git annex enableremote myremote keyid+=788A3F4C

You can repeat this process to add any number of gpg keys, including
your own gpg keys and any public keys of others who you want to give
access. Anyone with a corresponding secret key will be able to decrypt
all content that is stored in the remote.

While a key can later be removed from the list, note that it will **not**
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 (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. The corresponding private key is needed to store
anything in the remote, or access anything stored in it.
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 encrypted files that
are already stored in the remote. 

So if you need other public keys to also have access, it's best to add them
immediately after initializing the remote:

	git-annex initremote newremote keyid+=788A3F4C

Another 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 gpg 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.

## credentials storage

Special remotes that need some form of credentials, such as a password,
may support embedding the credentials in the git repository, using
embedcreds=yes. See individual special remotes' documentation for details.
When credentials are embedded in the repository, they're also encrypted using
whatever encryption setting has been selected for the repository.

Such credentials are also cached locally in a file only you can read,
in `.git/annex/creds/`. If you prefer to not expose the credentials on disk
in unencrypted form, you can disable this cache, by setting the
`annex.cachecreds` config to `false`.