From aa4b80db7fd8b3b46a8331bde66d3525712f46a7 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 14 Feb 2013 00:00:00 +0000 Subject: [PATCH] Update README so it can generate a man page with rst2man --- README.rst | 154 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 101 insertions(+), 53 deletions(-) diff --git a/README.rst b/README.rst index 9841e6f..b5402a4 100644 --- a/README.rst +++ b/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://` 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:// 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 > - git config gcrypt.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: ++ `fieldvalue`, extends until newline. - + ``, 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 +