search

AGWA / git-crypt

Transparent file encryption in git
https://www.agwa.name/projects/git-crypt/
GNU General Public License v3.0
8.18k stars 475 forks source link

Confused about the underlying encryption workflow. Can you add some documentation? #138

Open mnieber opened 6 years ago

mnieber commented 6 years ago

Hi, I'm trying to understand how git-crypt actually encrypts and decrypts files. I have 2 questions:

  1. after calling git-crypt init -k FOO there is no .git-crypt directory yet, but I see the FOO key in .git/git-crypt/keys. I have the impression that git-crypt will (eventually) encrypt my files with the .git/git-crypt/keys/FOO key, but that I can optionally protect the FOO key by calling git-crypt add-gpg-user -k FOO MY_GPG_USER_ID. Is that correct? This means that there are 2 different keys in play: MY_GPG_USER_ID is the gpg-key that protects the FOO key, right?

  2. Alternatively, I can export the .git/git-crypt/keys/FOO key (which simply means making a copy of this file), and then any collaborator can use it in a call to git-crypt unlock /path/to/key. If the collaborator copies the exported key to their own .git/git-crypt/keys directory (instead of specifying it in the call to git-crypt unlock), will that work too?

Imho it would help a lot to document these basic mechanism underlying git-crypt. For some reason, the sentence that confused me the most was "Share the repository with others (or with yourself) using GPG" (it somehow gave me the impression that the GPG key itself was used for the encryption of files in the repository).

ps I would also document the global gpg.program git option

robertknight commented 6 years ago

I had similar confusion and after reading through parts of the code and issues here wrote a blog post about git-crypt which explains the basics as I understand them, mostly for the benefit of my team at Hypothesis. I hope this is useful and any feedback is appreciated.

. This means that there are 2 different keys in play: MY_GPG_USER_ID is the gpg-key that protects the FOO key, right?

Yes, there are two keys in play. There is a symmetric AES key that encrypts the actual files in your repository, plus copies of this key that are encrypted using the public key of collaborators added using git crypt add-gpg-user. This issue about how to implement removing collaborators gives a good insight into the consequences of this.