1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
=================
git-remote-gcrypt
=================
--------------------------------------
GNU Privacy Guard-encrypted git remote
--------------------------------------
:Author: Ulrik Sverdrup
:Manual section: 1
Description
===========
Remote helper programs are invoked by git to handle network transport.
This helper handles gcrypt:: URLs that will access a remote repository
encrypted with GPG, using our custom format.
Supported locations are `local`, `ssh://`, `rsync://` and `sftp`, where
the repository is stored as a set of files, or instead any `<giturl>`
where gcrypt will store the same representation in a git repository,
bridged over arbitrary git transport.
.. NOTE:: Repository format MAY STILL change, incompatibly. We may
not continue to support all types of remote transport.
Quickstart
..........
Install as `git-remote-gcrypt` in `$PATH`.
Configure the list of participant gpg keys:
::
git config --global gcrypt.participants YOURKEYID
Create an encrypted remote by pushing to it:
::
git remote add cryptremote gcrypt::ssh://example.com:repo
git push cryptremote master
> gcrypt: Setting up new repository at ssh://example.com:repo
> gcrypt: Repository ID is KNBr0wKzct52
> gcrypt: Repository URL is gcrypt::ssh://example.com:repo#KNBr0wKzct52
> gcrypt: (configuration for cryptremote updated)
> [ more lines .. ]
> To gcrypt::[...]
> * [new branch] master -> master
Share the updated Repository URL with all participants.
(The generated Repository ID is not secret, it only exists to ensure
that two repositories signed by the same user can not be maliciously
switched around. It incidentally allows multiple repositories to all
share location.)
Design Goals
............
Confidential, authenticated git storage and collaboration on any
untrusted file host or service. The only information we (by necessity)
leak is the approximate size and timing of updates. PLEASE help me
evaluate how well we meet this design goal!
Configuration
=============
*gcrypt.participants*
Space-separated list of GPG key identifiers. The remote is
encrypted to these participants and only signatures from these
are accepted. ``gpg -k`` lists all public keys you know.
You should set *user.signingkey* if your default signing key is not part
of the participant list.
The encryption of the manifest is updated for each push. The pusher must
have the public keys of all collaborators. You can commit a keyring to
the repo, further key management features do not yet exist.
GPG configuration applies to public-key encryption, symmetric
encryption, and signing. See `man gpg` for more information.
Examples
========
::
git config gcrypt.participants YOURKEYID
git remote add cryptremote gcrypt::ssh://example.com:repo
git push cryptremote HEAD
How to use a git backend::
# notice that the target repo must already exist and its
# `master` branch will be overwritten!
git remote add gitcrypt gcrypt::git@example.com:repo
git push gitcrypt HEAD
Notes
=====
Repository Format
.................
::
EncSign(X) is sign+encrypt to a PGP key holder
Encrypt(K,X) is symmetric encryption
Hash(X) is SHA-224
B: branch list
L: list of the hash (Hi) and key (Ki) for each packfile
R: Hash(Repository ID)
Store Manifest as EncSign(B || L || R) in filename R
Store each packfile P as P' = Encrypt(Ki, P) in filename Hi
where Hi = Hash(P') and Ki is a random string
To read the repository
decrypt+verify Manifest using private key -> (B, L, R)
verify R matches Hash(Requested Repository ID)
for Hi, Ki in L:
download file Hi from the server -> P'
verify Hash(P') matches Hi
decrypt P' using Ki -> P then open P with git
Only packs mentioned in L are downloaded.
Manifest file
.............
::
$ gpg -d < 5a191cea8c1021a95d813c4007c14f2cc987a40880c2f669430f1916
b4a4a39365d19282810c19d0f3f24d04dd2d179f refs/tags/version1
1d323ddadf4cf1d80fced447e637ab3766b168b7 refs/heads/master
pack :SHA224:cfdf36515e0d0820554fe5fd9f00a4bee17bcf88ec8a752d851c46ee \
Rc+j8Nv6GOW3mBhWOx6W6jjz3BTX7B6XIJ6RYI+P4TEy
pack :SHA224:a43ccd208d3bd2ea582dbd5407cb8ed6e18b150b1da25c806115eaa5 \
UXR3/R7awFCUJWYdzXzrlkk7E2Acxq/Y4EfEcd62AwGG
repo :SHA224:5a191cea8c1021a95d813c4007c14f2cc987a40880c2f669430f1916 1
+ `field<space>value`, extends until newline.
+ `field` is one of `[0-9a-f]{40}`, `pack`, `repo`, `keep`, `extn`.
`[0-9a-f]{40} <gitref>`
SHA-1 and its git ref
`pack :<hashtype>:<hash> <key>`
Packfile hash (`Hi`) and corresponding symmetric key (`Ki`).
`repo :<hashtype>:<hash> <version>`
The hash of the repository id.
`extn ...`
Extension field, preserved but unused.
`keep ...`
TBD.
Yet to be Implemented
.....................
+ Repacking the remote repository
+ Some kind of simple keyring management
See Also
========
git-remote-helpers(1), gpg(1)
License
=======
git-remote-gcrypt is licensed under the terms of the GNU GPL version 2
(or at your option, any later version). See http://www.gnu.org/licenses/
.. vim: ft=rst tw=72
.. this document generates a man page with rst2man
|
