jigen/git-remote-gcrypt
1
0
Fork 0
Code Issues 1 Pull requests Releases Wiki Activity

Edit README

Browse source
This commit is contained in:
root 2013-01-20 19:22:44 +08:00
parent 85e65ca48e
commit aeb3135bcb
1 changed files with 47 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
README.rst
View file

@ -32,17 +32,15 @@ Quickstart
* Install ``git-remote-gcrypt`` by running the supplied ``install.sh`` script. * Install ``git-remote-gcrypt`` by running the supplied ``install.sh`` script.
* Create an encrypted remote by pushing to it: * Create an encrypted remote by pushing to it::
:: git remote add cryptremote gcrypt::rsync://example.com:repo
git push cryptremote master
git remote add cryptremote gcrypt::rsync://example.com:repo > gcrypt: Setting up new repository
git push cryptremote master > gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
> gcrypt: Setting up new repository > [ more lines .. ]
> gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R > To gcrypt::[...]
> [ more lines .. ] > * [new branch] master -> master
> To gcrypt::[...]
> * [new branch] master -> master
Configuration Configuration
============= =============
@ -50,47 +48,47 @@ Configuration
The following ``git-config(1)`` variables are supported: The following ``git-config(1)`` variables are supported:
``remote.<name>.gcrypt-participants`` ``remote.<name>.gcrypt-participants``
.. ..
``gcrypt.participants`` ``gcrypt.participants``
Space-separated list of GPG key identifiers. The remote is Space-separated list of GPG key identifiers. The remote is encrypted
encrypted to these participants and only signatures from these to these participants and only signatures from these are accepted.
are accepted. ``gpg -k`` lists all public keys you know. ``gpg -k`` lists all public keys you know.
When not set we encrypt to your default key and accept any valid When not set we encrypt to your default key and accept any valid
signature. This behavior can also be requested explicitly by signature. This behavior can also be requested explicitly by setting
setting participants to ``simple``. participants to ``simple``.
The ``gcrypt-participants`` setting on the remote takes precedence The ``gcrypt-participants`` setting on the remote takes precedence
over the repository variable ``gcrypt.participants``. over the repository variable ``gcrypt.participants``.
``user.signingkey`` ``user.signingkey``
(From regular git configuration) The key to use for signing. (From regular git configuration) The key to use for signing. You
You should set ``user.signingkey`` if your default signing key is should set ``user.signingkey`` if your default signing key is not
not part of the participant list. part of the participant list.
Environment Variables Environment Variables
===================== =====================
*GCRYPT_FULL_REPACK* *GCRYPT_FULL_REPACK*
This environment variable forces full repack when pushing. This environment variable forces full repack when pushing.
Examples Examples
======== ========
:: How to set up a remote for two participants::
git config gcrypt.participants YOURKEYID git remote add cryptremote gcrypt::rsync://example.com:repo
git remote add cryptremote gcrypt::rsync://example.com:repo git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
git push cryptremote HEAD git push cryptremote master
How to use a git backend:: How to use a git backend::
# notice that the target repo must already exist and its # notice that the target git repo must already exist and its
# `next` branch will be overwritten! # `next` branch will be overwritten!
git remote add gitcrypt gcrypt::git@example.com:repo#next git remote add gitcrypt gcrypt::git@example.com:repo#next
git push gitcrypt HEAD git push gitcrypt master
The URL fragment (`#next` here) indicates which branch is used. The URL fragment (`#next` here) indicates which backend branch is used.
Notes Notes
===== =====
@ -104,20 +102,20 @@ Collaboration
Dependencies Dependencies
``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:`` ``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:``
respectively. The main executable is a script for any respectively. The main executable requires a POSIX-compliant shell
POSIX-compliant shell supporting ``local``. that supports ``local``.
GNU Privacy Guard GNU Privacy Guard
GPG 1.4 or 2 are both supported. You need a configured personal Both GPG 1.4 and 2 are supported. You need a personal GPG key. GPG
keypair. GPG configuration applies to algorithm choices for configuration applies to algorithm choices for public-key
public-key encryption, symmetric encryption, and signing. See encryption, symmetric encryption, and signing. See ``man gpg`` for
``man gpg`` for more information. more information.
Remote ID Remote ID
The generated Remote ID is not secret, it only exists to ensure that The Remote ID is not secret; it only ensures that two repositories
two repositories signed by the same user can be distinguished. You signed by the same user can be distinguished. You will see
will see a warning if the Remote ID changes, which should a warning if the Remote ID changes, which should only happen if the
only happen if the remote was re-created. remote was re-created.
Repository Format Repository Format
................. .................
@ -139,15 +137,15 @@ Repository Format
| |
| To write the repository: | To write the repository:
| |
| Store each packfile ``P`` as ``P'`` = ``Encrypt(Ki, P)`` in filename ``Hi`` | Store each packfile ``P`` as ``Encrypt(Ki, P) -> P'`` in filename ``Hi``
| where ``Ki`` is a new random string and ``Hi = Hash(P')`` | where ``Ki`` is a new random string and ``Hash(P') -> Hi``
| Store ``EncSign(B || L || R)`` in the manifest | Store ``EncSign(B || L || R)`` in the manifest
| |
| To read the repository: | To read the repository:
| |
| Decrypt and verify manifest using GPG keyring ``-> (B, L, R)`` | Decrypt and verify manifest using GPG keyring ``-> (B, L, R)``
| Warn if ``R`` does not match previously seen Remote ID | Warn if ``R`` does not match previously seen Remote ID
| ``for each Hi, Ki in L``: | for each ``Hi, Ki in L``:
| Get file ``Hi`` from the server ``-> P'`` | Get file ``Hi`` from the server ``-> P'``
| Verify ``Hash(P')`` matches ``Hi`` | Verify ``Hash(P')`` matches ``Hi``
| Decrypt ``P'`` using ``Ki`` -> ``P`` then open ``P`` with git | Decrypt ``P'`` using ``Ki`` -> ``P`` then open ``P`` with git
@ -157,17 +155,17 @@ Repository Format
Manifest file Manifest file
............. .............
:: Example manifest file (with ellipsis for brevity)::
$ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a $ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next 542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master 3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
pack :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 z8YoAnFpMlWPIYG8wo1adewd4Fp7Fo3PkI2mND49P1qm pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
pack :SHA256:a6e17bb4c042bdfa8e38856ee6d058d0c0f0c575ace857c4795426492f379584 82+k2cbiUn7i2cW0dgXfyX6wXGpvVaQGj5sF59Y8my5W pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
keep :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 1 keep :SHA256:f2ad50316...cd4ba67092dc4 1
repo :id:OYiSleGirtLubEVqJpFF repo :id:OYiSleGirtLubEVqJpFF
Each item extends until newline, and matches one of the following forms: Each item extends until newline, and matches one of the following:
``<sha-1> <gitref>`` ``<sha-1> <gitref>``
Git object id and its ref Git object id and its ref
@ -195,7 +193,5 @@ License
git-remote-gcrypt is licensed under the terms of the GNU GPL version 2 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/ (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 .. this document generates a man page with rst2man
.. vim: ft=rst tw=72 sts=4