Update README so it can generate a man page with rst2man
This commit is contained in:
root
parent
dc2d0b34b1
commit
aa4b80db7f
1 changed files with 101 additions and 53 deletions
154
README.rst
154
README.rst
|
|
@ -1,72 +1,104 @@
|
|||
=================
|
||||
git-remote-gcrypt
|
||||
=================
|
||||
|
||||
:Command: git-remote-gcrypt
|
||||
--------------------------------------
|
||||
GNU Privacy Guard-encrypted git remote
|
||||
--------------------------------------
|
||||
|
||||
:Copyright: 2013 by Ulrik Sverdrup
|
||||
:License: GPLv2 or any later version, see http://www.gnu.org/licenses/
|
||||
:Decscription: Use GnuPG to use encrypted git remotes
|
||||
: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`, `ssh://`, `sftp://` and
|
||||
`gitception://`. `gcrypt::gitception://<giturl>` allows stacking gcrypt
|
||||
on top of any other git transport.
|
||||
|
||||
.. NOTE:: Repository format MAY STILL change, incompatibly
|
||||
|
||||
Introduction
|
||||
------------
|
||||
Quickstart
|
||||
..........
|
||||
|
||||
Install as `git-remote-gcrypt` in `$PATH`
|
||||
Install as `git-remote-gcrypt` in `$PATH`.
|
||||
|
||||
Supports local, ssh:// and sftp:// remotes at the moment, as well as
|
||||
the special gitception://<giturl> remote type, using any existing git
|
||||
repository as backend.
|
||||
Configure a keyring:
|
||||
|
||||
Example use::
|
||||
::
|
||||
|
||||
gpg --export KEY1 KEY2 > $PWD/.git/keyring.gpg
|
||||
git config --path gcrypt.keyring $PWD/.git/keyring.gpg
|
||||
git remote add cryptremote gcrypt::ssh://example.com:repo
|
||||
git push cryptremote master
|
||||
> gcrypt: Setting up new repository at ssh://example.com:repo
|
||||
> gcrypt: Repository ID is KNBr0wKzct52
|
||||
> gcrypt: Repository URL is gcrypt::ssh://example.com:repo/G.KNBr0wKzct52
|
||||
> gcrypt: (configuration for cryptremote updated)
|
||||
> [ more lines .. ]
|
||||
> To gcrypt::[...]
|
||||
> * [new branch] master -> master
|
||||
gpg --export KEY1 KEY2 > $PWD/.git/keyring.gpg
|
||||
git config --path gcrypt.keyring $PWD/.git/keyring.gpg
|
||||
|
||||
The generated Repository ID is not secret, it only exists to ensure that
|
||||
two repositories signed by the same user can not be (maliciously) switched
|
||||
around. It incidentally allows multiple repositories to all share location.
|
||||
Create an encrypted remote by pushing to it:
|
||||
|
||||
::
|
||||
|
||||
git remote add cryptremote gcrypt::ssh://example.com:repo
|
||||
git push cryptremote master
|
||||
> gcrypt: Setting up new repository at ssh://example.com:repo
|
||||
> gcrypt: Repository ID is KNBr0wKzct52
|
||||
> gcrypt: Repository URL is gcrypt::ssh://example.com:repo/G.KNBr0wKzct52
|
||||
> gcrypt: (configuration for cryptremote updated)
|
||||
> [ more lines .. ]
|
||||
> To gcrypt::[...]
|
||||
> * [new branch] master -> master
|
||||
|
||||
Share the updated Repository URL with everyone in the keyring.
|
||||
|
||||
(The generated Repository ID is not secret, it only exists to ensure
|
||||
that two repositories signed by the same user can not be maliciously
|
||||
switched around. It incidentally allows multiple repositories to all
|
||||
share location.)
|
||||
|
||||
Design Goals
|
||||
------------
|
||||
............
|
||||
|
||||
+ Confidential, authenticated git storage and collaboration on any
|
||||
untrusted file host or service. The only information we (by necessity)
|
||||
leak is the approximate size and timing of updates.
|
||||
PLEASE help me evaluate how well we meet this design goal!
|
||||
leak is the approximate size and timing of updates. PLEASE help me
|
||||
evaluate how well we meet this design goal!
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
=============
|
||||
|
||||
+ You must set up a small gpg keyring for the repository::
|
||||
*gcrypt.keyring*
|
||||
Path to the GPG keyring file containing the public keys of all
|
||||
participants. This file can be created using ``gpg --export``.
|
||||
|
||||
gpg --export KEYID1 > <path-to-keyring>
|
||||
git config gcrypt.keyring <path-to-keyring>
|
||||
git-remote-gcrypt respects the variable *user.signingkey*.
|
||||
|
||||
.. NOTE:: GnuPG's configuration applies. Check your key and general
|
||||
preferences, see `man gpg`.
|
||||
.. NOTE:: GPG configuration applies to public-key encryption, symmetric
|
||||
encryption, and signing. See `man gpg`.
|
||||
|
||||
+ All readers of the repository must have their pubkey included in
|
||||
the keyring used when pushing. All writers must have the complete
|
||||
set of pubkeys available. You can commit the keyring to the repo,
|
||||
further key management features do not yet exist.
|
||||
All readers of the repository must have their pubkey included in the
|
||||
keyring used when pushing. All writers must have the complete set of
|
||||
pubkeys available. You can commit the keyring to the repo, further key
|
||||
management features do not yet exist.
|
||||
|
||||
+ gcrypt obeys `user.signingkey`
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
gpg --export YOURKEYID > $PWD/.git/keyring.gpg
|
||||
git config gcrypt.keyring $PWD/.git/keyring.gpg
|
||||
git remote add cryptremote gcrypt::ssh://example.com:repo
|
||||
git push cryptremote HEAD
|
||||
|
||||
Notes
|
||||
=====
|
||||
|
||||
Repository Format
|
||||
-----------------
|
||||
.................
|
||||
|
||||
+ Protocol sketch::
|
||||
+ Protocol::
|
||||
|
||||
EncSign(X) is sign+encrypt to a PGP key holder
|
||||
Encrypt(K,X) is symmetric encryption
|
||||
|
|
@ -91,29 +123,45 @@ Repository Format
|
|||
|
||||
Only packs mentioned in L are downloaded.
|
||||
|
||||
+ The manifest looks like this::
|
||||
Manifest file
|
||||
.............
|
||||
|
||||
::
|
||||
|
||||
$ gpg -d < 5a191cea8c1021a95d813c4007c14f2cc987a40880c2f669430f1916
|
||||
b4a4a39365d19282810c19d0f3f24d04dd2d179f refs/tags/version1
|
||||
1d323ddadf4cf1d80fced447e637ab3766b168b7 refs/heads/master
|
||||
pack :SHA224:cfdf36515e0d0820554fe5fd9f00a4bee17bcf88ec8a752d851c46ee Rc+j8\
|
||||
Nv6GOW3mBhWOx6W6jjz3BTX7B6XIJ6RYI+P4TEyy+X6p2PB/fsBL9la0Tuc
|
||||
pack :SHA224:a43ccd208d3bd2ea582dbd5407cb8ed6e18b150b1da25c806115eaa5 UXR3/\
|
||||
R7awFCUJWYdzXzrlkk7E2Acxq/Y4EfEcd62AwGGe0o0QxL+s5CwWI/NvMhb
|
||||
pack :SHA224:cfdf36515e0d0820554fe5fd9f00a4bee17bcf88ec8a752d851c46ee \
|
||||
Rc+j8Nv6GOW3mBhWOx6W6jjz3BTX7B6XIJ6RYI+P4TEyy+X6p2PB/fsBL9la0Tuc
|
||||
pack :SHA224:a43ccd208d3bd2ea582dbd5407cb8ed6e18b150b1da25c806115eaa5 \
|
||||
UXR3/R7awFCUJWYdzXzrlkk7E2Acxq/Y4EfEcd62AwGGe0o0QxL+s5CwWI/NvMhb
|
||||
repo :SHA224:5a191cea8c1021a95d813c4007c14f2cc987a40880c2f669430f1916 1
|
||||
|
||||
+ Manifest fields:
|
||||
+ `field<space>value`, extends until newline.
|
||||
|
||||
+ `<fieldname><space><value>`, extends until newline.
|
||||
+ `{0-9a-f}[40]`, `pack`, `repo`, `keep` (planned), `extn` (extension
|
||||
fields, preserved but unused).
|
||||
+ `field` is one of `[0-9a-f]{40}`, `pack`, `repo`, `keep` (planned),
|
||||
`extn` (extension fields, preserved but unused).
|
||||
|
||||
|
||||
Pieces yet to be Implemented
|
||||
----------------------------
|
||||
Yet to be Implemented
|
||||
.....................
|
||||
|
||||
+ Repacking the remote repository
|
||||
+ Deleting remote refs
|
||||
+ Some kind of simple keyring management
|
||||
|
||||
.. vim: ft=rst tw=74
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue