Update doc

README.md

@@ -5,6 +5,8 @@ Belenios
 Compilation
 -----------
 
+### Dependencies
+
 To run basic command-line tools, you will need:
 
  * [OCaml](http://caml.inria.fr/)
@@ -27,6 +29,18 @@ To run the web server, you will additionally need:
 
  * [Eliom](http://ocsigen.org/eliom/) version 3
 
+In general, using [OPAM](http://opam.ocamlpro.com/) should work on any
+Unix-based system.
+
+To generate HTML files from `.md` ones, you will need:
+
+ * [Markdown](http://daringfireball.net/projects/markdown/)
+
+There are two Makefile targets corresponding to the two levels of
+dependencies: `minimal` (default) and `all`.
+
+### Debian-specific instructions
+
 On Debian and its derivatives, you can find the list of packages to
 install in the `stuff/belenios-deps-*.control` files. You can also
 create meta-packages with `equivs` by using the following commands:
@@ -41,13 +55,37 @@ install` to install missing dependencies.
 
 NOTE: `equiv-build` should not be run from a NFS directory!
 
-There are two Makefile targets corresponding to the two levels of
-dependencies: `minimal` (default) and `all`.
+
+Voter's guide
+-------------
+
+During an election, you should have access to the following files:
+
+ * `election.json`: election parameters
+ * `public_keys.jsons`: trustees' public keys
+ * `public_creds.txt`: the public keys associated to valid credentials
+ * `ballots.jsons`: accepted ballots
+
+Note that the last two are dynamic, and evolve during the election. At
+the end of the election, they are frozen and a `result.json` file will
+be published.
+
+If you put these files in a directory `/path/to/election`, the following
+command will perform all possible verifications, depending on existing
+files:
+
+    ./stuff/election-tool.sh --dir /path/to/election
+
+For example, during the election, you can check if some candidate
+ballot is acceptable by putting it alone in `ballots.jsons`, and
+running the command above.
 
 
 Trustee's guide
 ---------------
 
+### Key generation
+
 To generate a keypair, run:
 
     make trustee-keygen
@@ -57,6 +95,19 @@ containing respectively the public and the private key. Send the
 public key file to the server administrator, and keep the private key
 with extreme care.
 
+### Partial decryption
+
+To compute your decryption share, set `/path/to/election` up as
+described in the _Voter's guide_ section above, and run:
+
+    ./stuff/election-tool.sh --dir /path/to/election --decrypt /path/to/privkey > partial_decryption.json
+
+and send `partial_decryption.json` to the election
+administrator.
+
+Note: be sure to authenticate all your input files when you use your
+private key!
+
 
 Credential authority's guide
 ----------------------------
@@ -116,10 +167,13 @@ A sample web server can be run with the `tests/run-server.sh` script.
 Here is an excerpt of the sample configuration file:
 
     <eliom module="_build/src/web/server.cma">
+      <admin hash="XXX"/>
       <log file="_RUNDIR_/log/security.log"/>
       <data dir="tests/data"/>
     </eliom>
 
+The `admin` tag indicates the SHA256 of the admin password.
+
 The `log` tag indicates a file where some security-sentive events will
 be logged. The `data` tag indicates a directory with election
 data. This directory must contain one subdirectory per election, and
@@ -168,3 +222,24 @@ In the following, we assume `ocsigenserver` is properly configured.
  9.  Save the file with public credentials generated by the credential
      authority into `public_creds.txt`.
  10. Launch `ocsigenserver`.
+
+### Update a credential
+
+ 1. Go to `/login-admin` on the live server and log in using the admin
+    password.
+ 2. Go to `/election/update-cred?uuid=UUID`, and fill in the form.
+
+### Tally
+
+ 1. Go to the election directory, which must contain `election.json`,
+    `public_keys.jsons`, `public_creds.txt` and `ballots.jsons`.
+ 2. Concatenate the `partial_decryption.json` received from each
+    trustee into a `partial_decryptions.jsons`, in the same order as in
+    `public_keys.jsons`.
+ 3. Run `$BELENIOS/stuff/election-tool.sh`.  It will create
+    `result.json`. Publish this file, along with the files listed in
+    the first step above. The whole set will enable universal
+    verifiability.
+
+Note: `partial_decryptions.jsons` is a temporary file whose contents
+is embedded in `result.json`, so there is no need to keep it.