1GIT-REMOTE-GCRYPT(1) GIT-REMOTE-GCRYPT(1)
2
6 git-remote-gcrypt - GNU Privacy Guard-encrypted git remote
7
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 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 There is also an experimental rclone:// backend for early adoptors only
20 (you have been warned).
21 The aim is to provide confidential, authenticated git storage and col‐
23 laboration using typical untrusted file hosts or services.
24 Installation
26 · apt-get install git-remote-gcrypt on Debian and Ubuntu systems
27 · run the supplied install.sh script on other systems
29 Quickstart
31 Create an encrypted remote by pushing to it:
32 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
42 The following git-config(1) variables are supported:
43 remote.<name>.gcrypt-participants
45 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 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 The gcrypt-participants setting on the remote takes precedence
56 over the repository variable gcrypt.participants.
57 remote.<name>.gcrypt-publish-participants
59 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 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 gcrypt.gpg-args
70 The contents of this setting are passed as arguments to gpg.
71 E.g. --use-agent.
72 remote.<name>.gcrypt-signingkey
74 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
83 GCRYPT_FULL_REPACK
84 This environment variable forces a full repack when pushing.
85
87 How to set up a remote for two participants:
88 git remote add cryptremote gcrypt::rsync://example.com:repo
90 git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
91 git push cryptremote master
92 How to use a git backend:
94 # 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 The URL fragment (#next here) indicates which backend branch is used.
101
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 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 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 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 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 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 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 The rclone backend is considered experimental and is for early
146 adoptors only. You have been warned.
147 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 B: branch list
154 L: list of the hash (Hi) and key (Ki) for each packfile
155 R: Remote ID
156 To write the repository:
158 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 To read the repository:
164 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 Ki → P then open P with git
171 Manifest file
174 Example manifest file (with ellipsis for brevity):
175 $ 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 Each item extends until newline, and matches one of the following:
185 <sha-1> <gitref>
187 Git object id and its ref
188 pack :<hashtype>:<hash> <key>
190 Packfile hash (Hi) and corresponding symmetric key (Ki).
191 keep :<hashtype>:<hash> <generation>
193 Packfile hash and its repack generation
194 repo <id>
196 The remote id
197 extn <name> ...
199 Extension field, preserved but unused.
200
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 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
211 Every git push effectively has --force. Be sure to pull before push‐
212 ing.
213 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 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
224 git-remote-helpers(1), gpg(1)
225
227 The original author of git-remote-gcrypt was GitHub user bluss.
228 The de facto maintainer in 2013 and 2014 was Joey Hess.
230 The current maintainer, since 2016, is Sean Whitton <‐
232 spwhitton@spwhitton.name>.
233
235 This document and git-remote-gcrypt are licensed under identical terms,
236 GPL-3 (or 2+); see the git-remote-gcrypt file.
237 GIT-REMOTE-GCRYPT(1)