201 lines
6 KiB
ReStructuredText
201 lines
6 KiB
ReStructuredText
=================
|
|
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`, `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.
|
|
|
|
The aim is to provide confidential, authenticated git storage and
|
|
collaboration using typical untrusted file hosts or services.
|
|
PLEASE help us evaluate how well we meet this design goal!
|
|
|
|
.. NOTE:: This is a development version -- Repository format MAY CHANGE.
|
|
|
|
Quickstart
|
|
..........
|
|
|
|
* Install ``git-remote-gcrypt`` by running the supplied ``install.sh`` script.
|
|
|
|
* Create an encrypted remote by pushing to it:
|
|
|
|
::
|
|
|
|
git remote add cryptremote gcrypt::rsync://example.com:repo
|
|
git push cryptremote master
|
|
> gcrypt: Setting up new repository
|
|
> gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
|
|
> [ more lines .. ]
|
|
> To gcrypt::[...]
|
|
> * [new branch] master -> master
|
|
|
|
Configuration
|
|
=============
|
|
|
|
The following ``git-config(1)`` variables are supported:
|
|
|
|
``remote.<name>.gcrypt-participants``
|
|
..
|
|
``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.
|
|
|
|
When not set we encrypt to your default key and accept any valid
|
|
signature. This behavior can also be requested explicitly by
|
|
setting participants to ``simple``.
|
|
|
|
The ``gcrypt-participants`` setting on the remote takes precedence
|
|
over the repository variable ``gcrypt.participants``.
|
|
|
|
``user.signingkey``
|
|
(From regular git configuration) The key to use for signing.
|
|
You should set ``user.signingkey`` if your default signing key is
|
|
not part of the participant list.
|
|
|
|
Environment Variables
|
|
=====================
|
|
|
|
*GCRYPT_FULL_REPACK*
|
|
This environment variable forces full repack when pushing.
|
|
|
|
Examples
|
|
========
|
|
|
|
::
|
|
|
|
git config gcrypt.participants YOURKEYID
|
|
git remote add cryptremote gcrypt::rsync://example.com:repo
|
|
git push cryptremote HEAD
|
|
|
|
How to use a git backend::
|
|
|
|
# notice that the target repo must already exist and its
|
|
# `next` branch will be overwritten!
|
|
git remote add gitcrypt gcrypt::git@example.com:repo#next
|
|
git push gitcrypt HEAD
|
|
|
|
The URL fragment (`#next` here) indicates which branch is used.
|
|
|
|
Notes
|
|
=====
|
|
|
|
Collaboration
|
|
The encryption of the manifest is updated for each push to match the
|
|
participant configuration. Each pushing user must have the public
|
|
keys of all collaborators and correct participant config. You can
|
|
commit a keyring to the repo; further key management features do not
|
|
yet exist.
|
|
|
|
Dependencies
|
|
``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:``
|
|
respectively. The main executable is a script for any
|
|
POSIX-compliant shell supporting ``local``.
|
|
|
|
GNU Privacy Guard
|
|
GPG 1.4 or 2 are both supported. You need a configured personal
|
|
keypair. GPG configuration applies to algorithm choices for
|
|
public-key encryption, symmetric encryption, and signing. See
|
|
``man gpg`` for more information.
|
|
|
|
Remote ID
|
|
The generated Remote ID is not secret, it only exists to ensure that
|
|
two repositories signed by the same user can be distinguished. You
|
|
will see a warning if the Remote ID changes, which should
|
|
only happen if the remote was re-created.
|
|
|
|
Repository Format
|
|
.................
|
|
|
|
``EncSign(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 ``P'`` = ``Encrypt(Ki, P)`` in filename ``Hi``
|
|
| where ``Ki`` is a new random string and ``Hi = Hash(P')``
|
|
| Store ``EncSign(B || L || R)`` in the manifest
|
|
|
|
|
| To read the repository:
|
|
|
|
|
| Decrypt and verify manifest 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
|
|
|
|
|
| Only packs mentioned in ``L`` are downloaded.
|
|
|
|
Manifest file
|
|
.............
|
|
|
|
::
|
|
|
|
$ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
|
|
542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
|
|
3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
|
|
pack :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 z8YoAnFpMlWPIYG8wo1adewd4Fp7Fo3PkI2mND49P1qm
|
|
pack :SHA256:a6e17bb4c042bdfa8e38856ee6d058d0c0f0c575ace857c4795426492f379584 82+k2cbiUn7i2cW0dgXfyX6wXGpvVaQGj5sF59Y8my5W
|
|
keep :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 1
|
|
repo :id:OYiSleGirtLubEVqJpFF
|
|
|
|
Each item extends until newline, and matches one of the following forms:
|
|
|
|
``<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 repository id
|
|
|
|
``extn <name> ...``
|
|
Extension field, preserved but unused.
|
|
|
|
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
|
|
|