================= 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 `` 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..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: `` `` Git object id and its ref ``pack :: `` Packfile hash (`Hi`) and corresponding symmetric key (`Ki`). ``keep :: `` Packfile hash and its repack generation ``repo `` The repository id ``extn ...`` 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