Commit 02eb2a3e authored by Stephane Glondu's avatar Stephane Glondu

Update documentation

parent 745202f4
Main developer:
- Stéphane Glondu
Comments, review:
- Pierrick Gaudry
- Véronique Cortier
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)
================
......
......@@ -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
......
......@@ -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.
......
......@@ -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!
......@@ -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).
......@@ -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/).";
]
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment