Edit README
This commit is contained in:
root
parent
85e65ca48e
commit
aeb3135bcb
1 changed files with 47 additions and 51 deletions
98
README.rst
98
README.rst
|
|
@ -32,17 +32,15 @@ Quickstart
|
|||
|
||||
* 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
|
||||
> gcrypt: Setting up new repository
|
||||
> gcrypt: Remote ID is :id:7VigUnLVYVtZx8oir34R
|
||||
> [ more lines .. ]
|
||||
> To gcrypt::[...]
|
||||
> * [new branch] master -> master
|
||||
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
|
||||
=============
|
||||
|
|
@ -50,47 +48,47 @@ 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.
|
||||
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``.
|
||||
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``.
|
||||
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.
|
||||
(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.
|
||||
This environment variable forces full repack when pushing.
|
||||
|
||||
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 push cryptremote HEAD
|
||||
git remote add cryptremote gcrypt::rsync://example.com:repo
|
||||
git config remote.cryptremote.gcrypt-participants "KEY1 KEY2"
|
||||
git push cryptremote master
|
||||
|
||||
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!
|
||||
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
|
||||
=====
|
||||
|
|
@ -104,20 +102,20 @@ Collaboration
|
|||
|
||||
Dependencies
|
||||
``rsync`` and ``curl`` for remotes ``rsync:`` and ``sftp:``
|
||||
respectively. The main executable is a script for any
|
||||
POSIX-compliant shell supporting ``local``.
|
||||
respectively. The main executable requires a POSIX-compliant shell
|
||||
that supports ``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.
|
||||
Both GPG 1.4 and 2 are supported. You need a personal GPG key. 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.
|
||||
The Remote ID is not secret; it only ensures 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
|
||||
.................
|
||||
|
|
@ -139,15 +137,15 @@ Repository Format
|
|||
|
|
||||
| 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 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:
|
||||
|
|
||||
| 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``:
|
||||
| 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
|
||||
|
|
@ -157,17 +155,17 @@ Repository Format
|
|||
Manifest file
|
||||
.............
|
||||
|
||||
::
|
||||
Example manifest file (with ellipsis for brevity)::
|
||||
|
||||
$ gpg -d 91bd0c092128cf2e60e1a608c31e92caf1f9c1595f83f2890ef17c0e4881aa0a
|
||||
542051c7cd152644e4995bda63cc3ddffd635958 refs/heads/next
|
||||
3c9e76484c7596eff70b21cbe58408b2774bedad refs/heads/master
|
||||
pack :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 z8YoAnFpMlWPIYG8wo1adewd4Fp7Fo3PkI2mND49P1qm
|
||||
pack :SHA256:a6e17bb4c042bdfa8e38856ee6d058d0c0f0c575ace857c4795426492f379584 82+k2cbiUn7i2cW0dgXfyX6wXGpvVaQGj5sF59Y8my5W
|
||||
keep :SHA256:f2ad50316fbca42c553810aec3709c24974585ec1b34aae77d5cd4ba67092dc4 1
|
||||
pack :SHA256:f2ad50316...cd4ba67092dc4 z8YoAnFpMlW...3PkI2mND49P1qm
|
||||
pack :SHA256:a6e17bb4c...426492f379584 82+k2cbiUn7...dgXfyX6wXGpvVa
|
||||
keep :SHA256:f2ad50316...cd4ba67092dc4 1
|
||||
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>``
|
||||
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
|
||||
(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
|
||||
|
||||
.. vim: ft=rst tw=72 sts=4
|
||||
|
|
|
|||
Loading…
Reference in a new issue