git-remote-gcryptGNU Privacy Guard-encrypted git remoteDescriptiongit-remote-gcrypt is a git remote helper to push and pull fromrepositories encrypted with GnuPG, using a custom format. This remotehelper handles URIs prefixed with gcrypt::. Supported backends are local, rsync:// and sftp://, where therepository 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. See "Performance" below forbackends comparison. There is also an experimental rclone:// backend for early adoptorsonly (you have been warned). The aim is to provide confidential, authenticated git storage andcollaboration using typical untrusted file hosts or services. Installation- use your GNU/Linux distribution's package manager -- Debian, Ubuntu,Fedora, Arch and some smaller distros are known to have packages
- run the supplied
install.sh script on other systems
QuickstartCreate an encrypted remote by pushing to it: git remote add cryptremote gcrypt::rsync://example.com:repogit push cryptremote master> gcrypt: Setting up new repository> gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R> [ more lines .. ]> To gcrypt::[...]> * [new branch] master -> master ConfigurationThe following git-config(1) variables are supported: remote.<name>.gcrypt-participants gcrypt.participants Space-separated list of GPG key identifiers. The remote is encryptedto these participants and only signatures from these are accepted.gpg -k lists all public keys you know. If this option is not set, we encrypt to your default key and acceptany valid signature. This behavior can also be requested explicitlyby setting participants to simple . The gcrypt-participants setting on the remote takes precedenceover the repository variable gcrypt.participants . remote.<name>.gcrypt-publish-participants gcrypt.publish-participants By default, the gpg key ids of the participants are obscured byencrypting using gpg -R . Setting this option to true disablesthat security measure. The problem with using gpg -R is that to decrypt, gpg tries eachavailable secret key in turn until it finds a usable key.This can result in unnecessary passphrase prompts. gcrypt.gpg-args - The contents of this setting are passed as arguments to gpg.E.g.
--use-agent . remote.<name>.gcrypt-signingkey user.signingkey - (The latter from regular git configuration) The key to use for signing.You should set
user.signingkey if your default signing key is notpart of the participant list. You may use the per-remote versionto sign different remotes using different keys. remote.<name>.gcrypt-rsync-put-flags gcrypt.rsync-put-flags - Flags to be passed to
rsync when uploading to a remote using thersync:// backend. If the flags are set to a specific remote, theglobal flags, if also set, will not be applied for that remote.
Environment variables- GCRYPT_FULL_REPACK
- When set (to anything), this environment variable forces a full repack when pushing.
ExamplesHow to set up a remote for two participants: git remote add cryptremote gcrypt::rsync://example.com:repogit config remote.cryptremote.gcrypt-participants "KEY1 KEY2"git push cryptremote master How to use a git backend: # notice that the target git repo must already exist and its# `next` branch will be overwritten!git remote add gitcrypt gcrypt::[email protected]:repo#nextgit push gitcrypt master The URL fragment (#next here) indicates which backend branch is used. Notes- Collaboration
- The encryption of the manifest is updated for each push to match theparticipant configuration. Each pushing user must have the publickeys of all collaborators and correct participant config.
- Dependencies
rsync , curl and rclone for remotes rsync: , sftp: andrclone: respectively. The main executable requires a POSIX-compliantshell that supports local .- GNU Privacy Guard
- Both GPG 1.4 and 2 are supported. You need a personal GPG key. GPGconfiguration applies to algorithm choices for public-keyencryption, symmetric encryption, and signing. See
man gpg formore information. - Remote ID
- The Remote ID is not secret; it only ensures that two repositoriessigned by the same user can be distinguished. You will seea warning if the Remote ID changes, which should only happen if theremote was re-created.
- Performance
- Using an arbitrary <giturl> or an sftp:// URI requiresuploading the entire repository history with each push. If yourrepository history is large or you are pushing over a slow link,consider using the rsync:// transport, which performsincremental pushes. Note that the latter won't work with arepository hosting service like Gitolite, GitHub or GitLab.
- rsync URIs
- Note that the URI format for the rsync backend is, regretably,non-standard. git-remote-gcrypt uses
rsync://user@host:path whereas plain rsync uses either user@host:path orrsync://user@host/path . - rclone backend
In addition to adding the rclone backend as a remote with URI likegcrypt::rclone://remote:subdir , you must add the remote to therclone configuration too. This is typically done by executingrclone config . See rclone(1). The rclone backend is considered experimental and is for earlyadoptors only. You have been warned.
Repository formatEncSign(X): Sign and Encrypt to GPG key holder Encrypt(K,X): Encrypt using symmetric-key algorithm Hash(X): SHA-2/256
B: branch list L: list of the hash (Hi) and key (Ki) for each packfile R: Remote ID
To write the repository:
Store each packfile P as Encrypt(Ki, P) → P' in filename Hi where Ki is a new random string and Hash(P') → Hi Store EncSign(B || L || R) in the manifest
To read the repository:
Get manifest, decrypt and verify using GPG keyring → (B, L, R) Warn if R does not match previously seen Remote ID for each Hi, Ki in L: Get file Hi from the server → P' Verify Hash(P') matches Hi Decrypt P' using Ki → P then open P with git Manifest fileExample manifest file (with ellipsis for brevity): $ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/masterpack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qmpack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVakeep :SHA256:f2ad50316...cd4ba67092dc4 1repo :id:OYiSleGirtLubEVqJpFF Each item extends until newline, and matches one of the following: <sha-1> <gitref> - Git object id and its ref
pack :<hashtype>:<hash> <key> - Packfile hash (Hi) and corresponding symmetric key (Ki).
keep :<hashtype>:<hash> <generation> - Packfile hash and its repack generation
repo <id> - The remote id
extn <name> ... - Extension field, preserved but unused.
Detecting gcrypt reposTo detect if a git url is a gcrypt repo, use: git-remote-gcrypt --check url Exit status is 0 if the repo exists and can be decrypted, 1 if the repouses gcrypt but could not be decrypted, and 100 if the repo is notencrypted with gcrypt (or could not be accessed). Note that this has to fetch the repo contents into the local gitrepository, the same as is done when using a gcrypt repo. Known issuesEvery git push effectively has --force . Be sure to pull beforepushing. git-remote-gcrypt can decide to repack the remote without warning,which means that your push can suddenly take significantly longer thanyou were expecting, as your whole history has to be reuploaded.This push might fail over a poor link. git-remote-gcrypt might report a repository as "not found" when therepository does in fact exist, but git-remote-gcrypt is havingauthentication, port, or network connectivity issues. See alsogit-remote-helpers(1), gpg(1) CreditsThe original author of git-remote-gcrypt was GitHub user bluss. The de facto maintainer in 2013 and 2014 was Joey Hess. The current maintainer, since 2016, is Sean Whitton<[email protected]>. LicenseThis document and git-remote-gcrypt are licensed under identical terms,GPL-3 (or 2+); see the git-remote-gcrypt file. |
请发表评论