1GIT-REMOTE-GCRYPT(1)                                      GIT-REMOTE-GCRYPT(1)
2
3
4

NAME

6       git-remote-gcrypt - GNU Privacy Guard-encrypted git remote
7

DESCRIPTION

9       git-remote-gcrypt  is a git remote helper to push and pull from reposi‐
10       tories encrypted with GnuPG, using a custom format.  This remote helper
11       handles URIs prefixed with gcrypt::.
12
13       Supported  backends  are local, rsync:// and sftp://, where the reposi‐
14       tory is stored as a set of files, or instead any <giturl> where  gcrypt
15       will  store  the  same representation in a git repository, bridged over
16       arbitrary git transport.  See "Performance" below for backends compari‐
17       son.
18
19       There is also an experimental rclone:// backend for early adoptors only
20       (you have been warned).
21
22       The aim is to provide confidential, authenticated git storage and  col‐
23       laboration using typical untrusted file hosts or services.
24
25   Installation
26       · apt-get install git-remote-gcrypt on Debian and Ubuntu systems
27
28       · run the supplied install.sh script on other systems
29
30   Quickstart
31       Create an encrypted remote by pushing to it:
32
33          git remote add cryptremote gcrypt::rsync://example.com:repo
34          git push cryptremote master
35          > gcrypt: Setting up new repository
36          > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
37          > [ more lines .. ]
38          > To gcrypt::[...]
39          > * [new branch]      master -> master
40

CONFIGURATION

42       The following git-config(1) variables are supported:
43
44       remote.<name>.gcrypt-participants
45
46       gcrypt.participants
47              Space-separated  list  of  GPG  key  identifiers.  The remote is
48              encrypted to these participants and only signatures  from  these
49              are accepted.  gpg -k lists all public keys you know.
50
51              If  this  option  is not set, we encrypt to your default key and
52              accept any valid signature. This behavior can also be  requested
53              explicitly by setting participants to simple.
54
55              The  gcrypt-participants  setting on the remote takes precedence
56              over the repository variable gcrypt.participants.
57
58       remote.<name>.gcrypt-publish-participants
59
60       gcrypt.publish-participants
61              By default, the gpg key ids of the participants are obscured  by
62              encrypting  using  gpg  -R. Setting this option to true disables
63              that security measure.
64
65              The problem with using gpg -R is that to decrypt, gpg tries each
66              available  secret key in turn until it finds a usable key.  This
67              can result in unnecessary passphrase prompts.
68
69       gcrypt.gpg-args
70              The contents of this setting are passed  as  arguments  to  gpg.
71              E.g. --use-agent.
72
73       remote.<name>.gcrypt-signingkey
74
75       user.signingkey
76              (The  latter  from regular git configuration) The key to use for
77              signing.  You should set user.signingkey if your default signing
78              key  is  not  part  of  the  participant  list.  You may use the
79              per-remote version to sign  different  remotes  using  different
80              keys.
81

ENVIRONMENT VARIABLES

83       GCRYPT_FULL_REPACK
84              This environment variable forces a full repack when pushing.
85

EXAMPLES

87       How to set up a remote for two participants:
88
89          git remote add cryptremote gcrypt::rsync://example.com:repo
90          git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
91          git push cryptremote master
92
93       How to use a git backend:
94
95          # notice that the target git repo must already exist and its
96          # `next` branch will be overwritten!
97          git remote add gitcrypt gcrypt::git@example.com:repo#next
98          git push gitcrypt master
99
100       The URL fragment (#next here) indicates which backend branch is used.
101

NOTES

103       Collaboration
104              The encryption of the manifest is updated for each push to match
105              the participant configuration. Each pushing user must  have  the
106              public keys of all collaborators and correct participant config.
107
108       Dependencies
109              rsync,  curl  and  rclone  for remotes rsync:, sftp: and rclone:
110              respectively. The main  executable  requires  a  POSIX-compliant
111              shell that supports local.
112
113       GNU Privacy Guard
114              Both  GPG  1.4 and 2 are supported. You need a personal GPG key.
115              GPG configuration applies to algorithm  choices  for  public-key
116              encryption,  symmetric  encryption, and signing. See man gpg for
117              more information.
118
119       Remote ID
120              The Remote ID is not secret; it only ensures that two  reposito‐
121              ries signed by the same user can be distinguished.  You will see
122              a warning if the Remote ID changes, which should only happen  if
123              the remote was re-created.
124
125       Performance
126              Using an arbitrary <giturl> or an sftp:// URI requires uploading
127              the entire repository history with each push.  If  your  reposi‐
128              tory  history is large or you are pushing over a slow link, con‐
129              sider using the rsync:// transport, which  performs  incremental
130              pushes.  Note that the latter won't work with a repository host‐
131              ing service like Gitolite, GitHub or GitLab.
132
133       rsync URIs
134              Note that the URI format for the rsync backend  is,  regretably,
135              non-standard.    git-remote-gcrypt  uses  rsync://user@host:path
136              whereas   plain   rsync   uses    either    user@host:path    or
137              rsync://user@host/path.
138
139       rclone backend
140              In  addition  to  adding the rclone backend as a remote with URI
141              like gcrypt::rclone://remote:subdir, you must add the remote  to
142              the rclone configuration too.  This is typically done by execut‐
143              ing rclone config.  See rclone(1).
144
145              The rclone backend is considered experimental and is  for  early
146              adoptors only.  You have been warned.
147
148   Repository format
149       EncSign(X):   Sign and Encrypt to GPG key holder
150       Encrypt(K,X): Encrypt using symmetric-key algorithm
151       Hash(X):      SHA-2/256
152
153       B: branch list
154       L: list of the hash (Hi) and key (Ki) for each packfile
155       R: Remote ID
156
157       To write the repository:
158
159       Store each packfile P as Encrypt(Ki, P)P' in filename Hi
160         where Ki is a new random string and Hash(P')Hi
161       Store EncSign(B || L || R) in the manifest
162
163       To read the repository:
164
165       Get manifest, decrypt and verify using GPG keyring → (B, L, R)
166       Warn if R does not match previously seen Remote ID
167       for each Hi, Ki in L:
168         Get file Hi from the server → P'
169         Verify Hash(P') matches Hi
170         Decrypt P' using KiP then open P with git
171
172
173   Manifest file
174       Example manifest file (with ellipsis for brevity):
175
176          $ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
177          542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
178          3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
179          pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
180          pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
181          keep :SHA256:f2ad50316...cd4ba67092dc4 1
182          repo :id:OYiSleGirtLubEVqJpFF
183
184       Each item extends until newline, and matches one of the following:
185
186       <sha-1> <gitref>
187              Git object id and its ref
188
189       pack :<hashtype>:<hash> <key>
190              Packfile hash (Hi) and corresponding symmetric key (Ki).
191
192       keep :<hashtype>:<hash> <generation>
193              Packfile hash and its repack generation
194
195       repo <id>
196              The remote id
197
198       extn <name> ...
199              Extension field, preserved but unused.
200

DETECTING GCRYPT REPOS

202       To detect if a git url is a gcrypt repo, use: git-remote-gcrypt --check
203       url Exit status is 0 if the repo exists and can be decrypted, 1 if  the
204       repo uses gcrypt but could not be decrypted, and 100 if the repo is not
205       encrypted with gcrypt (or could not be accessed).
206
207       Note that this has to fetch the repo contents into the local git repos‐
208       itory, the same as is done when using a gcrypt repo.
209

KNOWN ISSUES

211       Every  git  push effectively has --force.  Be sure to pull before push‐
212       ing.
213
214       git-remote-gcrypt can decide to  repack  the  remote  without  warning,
215       which  means that your push can suddenly take significantly longer than
216       you were expecting, as your whole history has to be  reuploaded.   This
217       push might fail over a poor link.
218
219       git-remote-gcrypt  might  report  a  repository as "not found" when the
220       repository does in fact exist, but git-remote-gcrypt is having  authen‐
221       tication, port, or network connectivity issues.
222

SEE ALSO

224       git-remote-helpers(1), gpg(1)
225

CREDITS

227       The original author of git-remote-gcrypt was GitHub user bluss.
228
229       The de facto maintainer in 2013 and 2014 was Joey Hess.
230
231       The    current   maintainer,   since   2016,   is   Sean   Whitton   <‐
232       spwhitton@spwhitton.name>.
233

LICENSE

235       This document and git-remote-gcrypt are licensed under identical terms,
236       GPL-3 (or 2+); see the git-remote-gcrypt file.
237
238
239
240
241                                                          GIT-REMOTE-GCRYPT(1)
Impressum