Update README

diff --git a/README b/README
deleted file mode 100644 (file)
index 74b61df..0000000
--- a/README
+++ /dev/null
@@ -1,87 +0,0 @@
-# git-remote-gcrypt
-# Copyright 2013  by Ulrik Sverdrup
-# License: GPLv2 or any later version, see http://www.gnu.org/licenses/
-# Use GnuPG to use encrypted git remotes
-
-WARNING: Repository format MAY STILL change, incompatibly
-
-INTRODUCTION
-
-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::
-
-    git remote add gcryptrepo gcrypt::ssh://hostname.com:MyNewRepo
-     ( or maybe:
-       git remote add gcryptrepo gcrypt::gitception://git://host.com/repo.git
-     )
-    git push --all gcryptrepo
-
-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!
-
-CONFIGURATION
-
- + You must set up a small gpg keyring for the repository::
-
-     gpg --export KEYID1 > <path-to-keyring>
-     git config gcrypt.keyring <path-to-keyring>
-
-   New repositories will be set up to allow access for the keys in
-   `gcrypt.keyring`. The keyring is used to verify the authenticity of the
-   repository when it is read or written to.
-
- + NOTE: We use the user's gnupg configuration for `cipher-algo` and so on!
-         Configure your gnupg to use strong crypto -- see `man gpg`.
-
-
-REPOSITORY FORMAT
-
- + The manifest is signed+encrypted using `gpg -se` (with hidden recipients)
-   and stored on the remote.
- + The manifest contains the list of branches and packfiles.
-
-    $ cd MyCryptedRemote
-    $ ls 
-    -rw-- 11K 00ef27cc2c5b76365e1a46479ed7429e16572c543cdff0a8bf745c7c
-    -rw-- 41K b934d8d6c0f48e71b9d7a4d5ea56f024a9bed4f6f2c6f8e688695bee
-    -rw-- 577 manifest
-    
-    $ gpg -d manifest
-    T+pCUr/1FxbBC93ABIiIgG36EgqaxvgdNYjdmRSueGkgGETc4Qs7di+/yIsq2R5GysiqFaR0 \
-    bGSWf9omsoAH84hmED/kR/ZQiOGT/vg2Pg7CGI0xzdlW9GQjeFBAo4vsDDDBxrn5L7F9E532 \
-    LOnnPLSIZD7BpmyY/oZiXoP5Vlw=
-    b4a4a39365d19282810c19d0f3f24d04dd2d179f refs/tags/something
-    1d323ddadf4cf1d80fced447e637ab3766b168b7 refs/heads/master
-    pack :SHA224:00ef27cc2c5b76365e1a46479ed7429e16572c543cdff0a8bf745c7c
-    pack :SHA224:b934d8d6c0f48e71b9d7a4d5ea56f024a9bed4f6f2c6f8e688695bee
-
-
- + Protocol sketch
-
-   EncSign(X) is sign+encrypting to a PGP key holder
-   Encrypt(K,X) is symmetric encryption
-
-   K: master key, generated once, 128 bytes
-   B: branch list
-   L: list of packfiles and hashes
-   
-   Store Manifest as EncSign(K || B || L)
-   Each packfile P is stored as P' = Encrypt(K,P) and named SHA224(P')
-   L is the list of names of P'.
-
-
-   To read the repository
-
-   decrypt+verify Manifest using private key -> (K, B, L)
-   for each packfile P' in L:
-       verify  P' matches its hash
-       decrypt P' using K -> P -> open P with git
-
-   Only packs mentioned in L are downloaded.
-

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..880285f
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,106 @@
+
+:Command:       git-remote-gcrypt
+
+: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
+
+.. warning:: Repository format MAY STILL change, incompatibly
+
+Introduction
+------------
+
+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.
+
+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 99b45a84a13168fc5efe
+    > gcrypt: Repository URL is gcrypt::ssh://example.com:repo/G/99b45a84a13168fc5efe
+    > gcrypt: (configuration for cryptremote updated)
+    > [ more lines .. ]
+    > To gcrypt::[...]
+    > * [new branch]      master -> master
+
+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.
+
+Share the updated Repository URL with everyone in the keyring.
+
+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!
+
+Configuration
+-------------
+
++ You must set up a small gpg keyring for the repository::
+
+    gpg --export KEYID1 > <path-to-keyring>
+    git config gcrypt.keyring <path-to-keyring>
+
++ NOTE: We use the user's gnupg configuration for `cipher-algo` and so on!
+        Check your keys and key preferences, 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.
+
+
+Repository Format
+-----------------
+
++ Protocol sketch::
+
+    EncSign(X)   is sign+encrypt to a PGP key holder
+    Encrypt(K,X) is symmetric encryption
+    Hash(X)      is SHA-224
+
+    K: master key, generated once, 128 bytes
+    B: branch list
+    L: list of packfile hashes
+    R: Hash(Repository ID)
+    
+    Store Manifest as EncSign(K || B || L || R) in filename R
+    Each packfile P is stored as P' = Encrypt(K,P) in filename Hash(P')
+    L is the list of Hash(P').
+
+    To read the repository
+
+    decrypt+verify Manifest using private key -> (K, B, L, R)
+    verify R matches Hash(Requested Repository ID)
+    for each entry in L:
+        get the entry from the server -> P'
+        verify  Hash(P') matches the entry in L
+        decrypt P' using K -> P -> open P with git
+
+    Only packs mentioned in L are downloaded.
+
++ The manifest looks like this::
+
+     $ gpg -d < 9f42017de5cb482e509ff147d54ceeb0413d6379717f3f0db770f00a
+     T+pCUr/1FxbBC93ABIiIgG36EgqaxvgdNYjdmRSueGkgGETc4Qs7di+/yIsq2R5GysiqFaR0 \
+     bGSWf9omsoAH84hmED/kR/ZQiOGT/vg2Pg7CGI0xzdlW9GQjeFBAo4vsDDDBxrn5L7F9E532 \
+     LOnnPLSIZD7BpmyY/oZiXoP5Vlw=
+     b4a4a39365d19282810c19d0f3f24d04dd2d179f refs/tags/something
+     1d323ddadf4cf1d80fced447e637ab3766b168b7 refs/heads/master
+     pack :SHA224:00ef27cc2c5b76365e1a46479ed7429e16572c543cdff0a8bf745c7c
+     pack :SHA224:b934d8d6c0f48e71b9d7a4d5ea56f024a9bed4f6f2c6f8e688695bee
+     repo 9f42017de5cb482e509ff147d54ceeb0413d6379717f3f0db770f00a
+
+
+.. vim: ft=rst tw=74