Update documentation

AUTHORS

+Main developer:
+- Stéphane Glondu
+
+Comments, review:
+- Pierrick Gaudry
+- Véronique Cortier

CHANGES.md

+1.0 (2016-04-22)
+================
+
+ * Many changes in the web server:
+   + Add election_missing_voters: it now possible to see the list of
+     people who did not vote (new link in election administration
+     page).
+   + Hide the login box when it is not relevant: We do no longer show
+     login links in the top right hand corner of the page. The voter
+     is automatically invited to log in when he is about to cast a
+     vote.
+   + Do no longer show warning when window.cryto is unavailable (this
+     warning appeared on IE8).
+   + In admin page, show tallied elections in a new section.
+   + In admin page, sort (finalized) elections by finalization time.
+   + Add a form to regenerate and mail a password.
+   + Generating trustee keys is more resilient to momentary lack of
+     entropy.
+   + Change default question to make the blank choice explicit.
+   + Print number of accepted ballots on the result pagee
+   + Add the possibility to specify a login attached to an email
+     address. E-mail address and logins must be specified in the
+     following way: foo@example.com,login. When login is not
+     specified, the address is used as login. This feature is useful
+     mainly for CAS authentication.
+   + Voters (and passwords) can be imported from another (finalized)
+     election.
+   + Send a confirmation email after a successful vote.
+   + Add a new notion of "archived" elections.
+   + Pretty page for records.
+   + An e-mail address can be attached to trustees.
+   + Do not propose dummy authentication for new elections.
+
 0.2 (2014-04-09)
 ================
 

INSTALL.md

@@ -35,7 +35,7 @@ If you are unfamiliar with OCaml or OPAM, we provide an
 `opam-bootstrap.sh` shell script that creates a whole, hopefully
 self-contained, OCaml+OPAM install, and then installs all the
 dependencies of Belenios, everything into a single directory. You can
-chose the directory by setting the `BELENIOS_SYSROOT` environment
+choose the directory by setting the `BELENIOS_SYSROOT` environment
 variable, or it will take `~/.belenios` by default. Just run:
 
     ./opam-bootstrap.sh
@@ -210,6 +210,17 @@ This can be worked around with the following steps:
    found in `opam-bootstrap.sh`;
  * follow the instructions given at the end of `opam-bootstrap.sh`.
 
+### Errors while compiling ocsigenserver
+
+If ocsigenserver fails to install because of a SSL-related error:
+
+ * edit `opam-bootstrap.sh` by adding ` ssl=0.5.2` to the `opam
+   install` call;
+ * run `./opam-bootstrap.sh`.
+
+An alternative could be to install aspcud before running
+`opam-bootstrap.sh`.
+
 ### Errors while compiling Belenios itself
 
 If you succeeded installing all dependencies, but you get errors while

README.md

@@ -34,7 +34,7 @@ summarized as follows:
  4. The administrator collects all public credentials and trustees'
     public keys and sets up the election.
  5. The administrator opens the election.
- 6. Each voter vote; the administrator collects, checks and publishes
+ 6. Each voter votes; the administrator collects, checks and publishes
     all the ballots.
  7. The administrator closes the election.
  8. Trustees collectively decrypt the result.

VERSION

-0.2
+1.0

doc/tool.md

@@ -6,19 +6,21 @@ Introduction
 ------------
 
 `belenios-tool` is a command-line tool that can be used to perform
-administrative tasks related to elections, as well as
-verifications. If you do not wish to use the provided web server, a
-whole election can be organized using this tool. As an illustration of
-that, you can have a look at the `demo/demo.sh` script that simulates
-an election.
+administrative tasks related to elections, as well as verifications.
+If you do not wish to use the provided web server, a whole election
+can be organized using this tool. As an illustration of that, you can
+have a look at the `demo/demo.sh` script that simulates an election.
 
 This file documents how to use `belenios-tool`, from the point of view
 of the various roles involved in a election. You can also run it with
-the `--help` option to get more information about a specific option.
+the `--help` option to get more information.
 
 
-Voter's (and everyone's) guide
-------------------------------
+Auditor's guide
+---------------
+
+Note that anyone can be an auditor. Everyone who plays a specific role
+in a election should start by auditing the election data.
 
 During an election, you should have access to the following files:
 
@@ -27,9 +29,9 @@ During an election, you should have access to the following files:
  * `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.
+Note that the last one is dynamic, and evolve during the election. At
+the end of the election, it is 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
@@ -41,6 +43,10 @@ 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.
 
+
+Voter's guide
+-------------
+
 If you put your secret credential in a file `/path/to/credential` and
 your choices in a file `/path/to/choices.json` (as an array of arrays
 of 0/1 in JSON format), the following command will output a raw ballot
@@ -48,10 +54,6 @@ that can be directly submitted:
 
     belenios-tool vote --dir /path/to/election --privcred /path/to/credential --ballot /path/to/choices.json
 
-To get the public key derived from a private credential, run:
-
-    belenios-tool credgen --uuid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX --derive YYYYYYYYYYYYYYY
-
 
 Administrator's guide
 ---------------------
@@ -67,18 +69,18 @@ Administrator's guide
     credentials into `$DIR/public_creds.txt`.
  5. Ask each trustee to generate a keypair. Concatenate all trustee
     public keys into a `$DIR/public_keys.jsons` file.
- 6. Edit `$BELENIOS/demo/templates/election.json`.
- 7. Run: `belenios-tool mkelection --uuid $UUID --group
-    $BELENIOS/demo/groups/default.json --template
-    $BELENIOS/demo/templates/election.json`. It should generate
-    `election.json` in the current directory.
- 8. Create an empty `ballots.jsons` file.
+ 6. Edit `$BELENIOS/demo/templates/questions.json`.
+ 7. Go to `$DIR` and run: `belenios-tool mkelection --uuid $UUID
+    --group $BELENIOS/demo/groups/default.json --template
+    $BELENIOS/demo/templates/questions.json`. It should generate
+    `election.json`.
+ 8. Create an empty `ballots.jsons` file in `$DIR`.
 
 ### Running the election
 
 The contents of `$DIR` should be public.
 
-For each received ballot, add it to `ballots.jsons` and run:
+For each received ballot, append it to `ballots.jsons` and run:
 
     belenios-tool verify --dir $DIR
 
@@ -110,43 +112,32 @@ is embedded in `result.json`, so it can be discarded.
 Credential authority's guide
 ----------------------------
 
-### Pseudonymous credential generation
+### Credential generation
 
-To generate the credentials, run:
+If you have a list of identities in a file `F` with `N` lines, one
+identity per line, run:
 
-    belenios-tool credgen --uuid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX --count N
+    belenios-tool credgen --uuid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX --file F
 
 where `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` is the UUID of the
-election given by the administrator, and `N` the number of credentials
-to generate. It will generate three files with `N` lines:
+election given by the administrator. It will generate three files with
+`N` lines:
 
- * `T.privcreds`: each line of this file contains a unique numeric
-   identifier and a private credential. Assign each identifier to a
-   voter and send him/her the associated credential. Destroy the whole
-   file when you are done;
+ * `T.privcreds`: each line of this file contains an identity and a
+   private credential. Send each voter the associated credential. Keep
+   this file secret, and secure if you want to be able to re-send a
+   credential later (e.g. if a voter lost or did not receive it).
  * `T.pubcreds`: each line of this file contains a public credential.
    Send the whole file to the election administrator; it will be the
-   initial `public_creds.txt` for the election;
+   `public_creds.txt` for the election (and you should check that);
  * `T.hashcreds`: each line of this file contains, for each id in
-   `T.privcreds`, the hash of the corresponding public key. This file
-   is needed if you want to be able to change a credential after the
-   election is set up (e.g. if some voter lost his/her private
-   credential). If you do not want this feature, destroy this file and
-   the association between identifiers and voters.
+   `T.privcreds`, the hash of the corresponding public key. At the
+   moment, this file has no practical purpose (but this might change in
+   the future). Destroy it.
 
 You can optionally add a `--dir` option to specify the directory where
 these files will be written.
 
-### Credential generation with identity matching
-
-If you have a list of identities in a file `F` with `N` lines, one
-identity per line, you can also run:
-
-    belenios-tool credgen --uuid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX --file F
-
-It will create the same files as above using identities from `F`
-instead of generating numeric identifiers.
-
 
 Trustee's guide
 ---------------
@@ -160,7 +151,8 @@ To generate a keypair, run:
 It will generate two files, `XXXXXXXX.public` and `XXXXXXXX.private`,
 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.
+with extreme care. When the election is open, you should check that
+your public key is present in the published `public_keys.jsons`.
 
 ### Partial decryption
 
@@ -169,8 +161,7 @@ described in the _Voter's guide_ section above, and run:
 
     belenios-tool decrypt --dir /path/to/election --privkey /path/to/privkey > partial_decryption.json
 
-and send `partial_decryption.json` to the election
-administrator.
+and send `partial_decryption.json` to the election administrator.
 
 Note: be sure to authenticate all your input files when you use your
 private key!

doc/web.md

@@ -7,12 +7,13 @@ Election administrator's guide
 
 ### Setup a new election
 
-Once the server is up and running, anyone who can log into the server
-as an administrator can create an election. First, the administrator
-has to choose how credentials will be handled:
+Once the server is up and running (see below), anyone who can log into
+the server as an administrator can create an election. First, the
+administrator has to choose how credentials will be handled:
 
  * in the automatic mode, the server will generate credentials and
-   mail the private parts to each voter. Credential recovery is not
+   mail the private parts to each voter. Credential recovery (i.e. one
+   voter loses his/her credential or does not receive it) is not
    possible in this case;
  * in the manual mode, a third party will generate credentials using
    a web interface or the command-line tool, and upload the public
@@ -53,6 +54,38 @@ into:
 
     sha256sum | xxd -r -p | base64
 
+### Election life cycle
+
+An election starts by being in preparation (or "setup mode"), then
+becomes finalized. Then, it is immediately opened and can be closed
+and re-opened at will. When it is closed, the election administrator
+can initiate the tallying process. The encrypted tally is then
+computed and published. After each trustee has computed his/her share
+of the decryption, the administrator triggers the release of the
+result.
+
+At any moment, a finalized election can be archived. This releases
+some resources on the server and makes the election read-only. In
+particular, it is no longer possible to vote in or to tally an
+archived election.
+
+### Auditing an election
+
+During the election, the following files are published:
+
+ * `election.json`: election parameters
+ * `public_keys.jsons`: trustees' public keys
+ * `public_creds.txt`: the public keys associated to valid credentials
+ * `ballots.jsons`: accepted ballots
+
+They are accessible from the bottom of the election page. Together,
+they enable anyone to audit the election. At the end of the election,
+an additional `result.json` file is published with the result and
+other cryptographic proofs that everything went well.
+
+Please refer to the auditor's guide in the documentation of the
+command-line tool for more information.
+
 
 Server administrator's guide
 ----------------------------
@@ -105,10 +138,11 @@ local changes, an easy way to comply with the AGPL license is to
 commit them in a local git checkout, and put in the `source` element
 the path to the tarball generated by `make archive`.
 
-The `<log>` element indicates a file where some security-sentive
+The `<log>` element indicates a file where some security-sensitive
 events will be logged. It is optional.
 
 The `<spool>` element indicates a directory with election data. This
 directory should be empty when the server is launched for the first
 time, and will be populated with election data. A typical location
-would be `/var/spool/belenios`.
+would be `/var/spool/belenios`. Warning: it may contain sensitive data
+(e.g. the private key when no external trustees are set).

src/tool/tool_cmdline.ml

@@ -53,6 +53,8 @@ let failcmd fmt = Printf.ksprintf (fun x -> raise (Cmdline_error x)) fmt
 let common_man = [
   `S "MORE INFORMATION";
   `P "This command is part of the Belenios command-line tool.";
+  `P "To get more help on a specific subcommand, run:";
+  `P "$(b,belenios-tool) $(i,COMMAND) $(b,--help)";
   `P "See $(i,http://belenios.gforge.inria.fr/).";
 ]