Commit 48a45abd authored by Stephane Glondu's avatar Stephane Glondu
Browse files

Update README.md

parent 9e7e9b16
......@@ -127,83 +127,139 @@ To get the public key derived from a private credential, run:
belenios-tool credgen --uuid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX --derive YYYYYYYYYYYYYYY
Election organizer's guide
--------------------------
Once the server is up and running (see next section), anyone who can
log into the server can create an election, with the help of the
command-line tool. The interface is very rudimentary at the moment,
and it is not possible to edit or destroy an election once it has been
accepted by the server.
### Setup a new election
1. Generate an UUID with the `uuidgen` command. Let it be `$UUID`.
2. Go to an empty directory. In the following, we denote by `$DIR`
the full path to this directory and by `$BELENIOS` the full path
to the Belenios source tree.
4. Ask the credential authority to generate credentials. Note that
`$UUID` is needed for that. Save the file with public
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 a `$DIR/metadata.json` file. Its format is currently
undocumented and subject to future evolution, but you can get
inspiration from `$BELENIOS/demo/data/*/metadata.json`.
9. Open a browser, go to the _Administer elections_ page (link at
the bottom), log in, and upload all the files created in the
previous steps.
### Election administration
Each election has its own administration page and authentication
configuration. An election owner has to log in from the site
administration page (accessible from the link at the bottom of pages)
to be able to access the administration page specific to the election.
### Tally
1. Go to the election directory, which must contain `election.json`,
`public_keys.jsons`, `public_creds.txt` and `ballots.jsons`.
`ballots.jsons` must be downloaded from the running webserver,
as well as `public_creds.txt` if some credentials were changed
during the election.
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-tool election finalize`. 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.
Server administrator's guide
----------------------------
### Overview of the web server
A sample web server can be run with the `demo/run-server.sh` script,
from the compiled source tree.
Here is an excerpt of the sample configuration file:
<eliom module="_build/src/web/server.cma">
<enable-dummy/>
<enable-password db="demo/data/password_db.csv"/>
<auth name="demo"><dummy/></auth>
<auth name="local"><password db="demo/password_db.csv"/></auth>
<source file="../belenios.tar.gz"/>
<main-election uuid="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"/>
<admin hash="XXX"/>
<log file="_RUNDIR_/log/security.log"/>
<data dir="demo/data"/>
<import dir="demo/data"/>
<spool dir="_RUNDIR_/spool"/>
</eliom>
The `<enable-dummy>` tag enables the dummy authentication method,
which just asks for a name. No security is intended. This is useful
for debugging or demonstration purposes but obviously not suitable for
production. To disable it, just remove the tag.
The `<enable-password>` tag enables password-based authentication. It
takes as parameter a file, in CSV format, where each line consists of:
`<auth>` elements configure authentication for the whole
site. Available authentication methods:
* a user name
* a salt
* SHA256(salt concatenated with password)
* `<dummy>`: just asks for a name. No security is intended. This is
useful for debugging or demonstration purposes but obviously not
suitable for production
* `<password>`: password-based authentication. It takes as parameter
a file, in CSV format, where each line consists of:
+ a user name
+ a salt
+ SHA256(salt concatenated with password)
Additional fields are ignored. In the sample `password_db.csv` file, a
fourth field with the plaintext password is included. The sample file
has been generated with the following shell command:
Additional fields are ignored. In the sample `password_db.csv`
file, a fourth field with the plaintext password is included. The
sample file has been generated with the following shell command:
for u in `seq 1 5`; do SALT=`pwgen`; PASS=`pwgen`; echo "user$u,$SALT,$(echo -n "$SALT$PASS" | sha256sum | read a b; echo $a),$PASS"; done
`for u in $(seq 1 5); do SALT=$(pwgen); PASS=$(pwgen); echo "user$u,$SALT,$(echo -n "$SALT$PASS" | sha256sum | read a b; echo $a),$PASS"; done`
There is also the possibility to authenticate with a
[CAS](http://www.jasig.org/cas) server. To do that, use the
`<enable-cas>` instead of other `<enable-*>` tags:
* `<cas>`: authenticate with a [CAS](http://www.jasig.org/cas)
server. For example:
<enable-cas server="https://cas.example.org"/>
`<auth name="example"><cas server="https://cas.example.com/cas"/></auth>`
If the web server is behind a reverse-proxy, it might be needed to
rewrite URLs passed to the CAS server. This can be done with the
following directive:
If the web server is behind a reverse-proxy, it might be needed to
rewrite URLs passed to the CAS server. This can be done with the
following directive:
<rewrite-prefix src="https://backend-server" dst="https://frontend-server/belenios"/>
`<rewrite-prefix src="https://backend-server" dst="https://frontend-server/belenios"/>`
The `<source>` tag gives the path of the source tarball. Note that this
is a path on the local filesystem and not a URL. If you made 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` tag the path to the
tarball generated by `make archive`.
The `<source>` element gives the path to the source tarball. Note that
this is a path on the local filesystem and not a URL. If you made
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`.
If the `<main-election>` tag is present, the home page will be a
redirection to the referenced election, and not a mere listing of open
elections. This is useful if there is a single election.
If a `<main-election>` element is present, the home page will be a
redirection to the referenced election, and not a mere listing of
featured elections. This is useful if there is a single
election. Others elections (if any) are still accessible, though.
The `<admin>` tag indicates the SHA256 of the admin password.
The `<log>` element indicates a file where some security-sentive
events will be logged. It is optional.
The `<log>` tag indicates a file where some security-sentive 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`.
The `<data>` tag indicates a directory with election data. This
directory must contain one subdirectory per election, and in each of
these directories, the following files are expected:
The `<import>` element indicates a directory from where elections will
be imported when the server is launched for the first time. The
directory referenced here must contain an `index.json` file. Each
election subdirectory must contain the following files:
* `election.json`: election parameters
* `metadata.json`: additional parameters that are not published
* `public_keys.jsons`: public keys of the trustees, one per line
* `public_creds.txt`: anonymous public credentials, one per line
If a `result.json` file exists, the election is assumed to be finished
and ignored.
The *election fingerprint*, which is shown on the election page and in
the booth, is the compact Base64 encoding of the SHA256 of
`election.json`. It can be computed from a POSIX shell by piping it
......@@ -211,65 +267,6 @@ into:
sha256sum | xxd -r -p | base64
During an election, the web server stores dynamic data such as
accepted ballots in Ocsipersist's store.
In the following, we assume `ocsigenserver` is properly configured.
### Setup a new election
1. Generate an UUID with the `uuidgen` command. Name it `$UUID`.
2. Create a new directory in the data directory. For uniqueness, it
is suggested to include `$UUID` in the directory name. In the
following, we denote by `$DIR` the full path to this directory
and by `$BELENIOS` the full path to the Belenios source tree.
3. Go to `$DIR`.
4. Ask the credential authority to generate credentials. Note that
`$UUID` is needed for that. Save the file with public
credentials into `public_creds.txt`.
5. Ask each trustee to generate a keypair. Concatenate all trustee
public keys into a `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. (Optionally) Copy `$BELENIOS/demo/templates/metadata.json` to
`$DIR` and edit the dates in it.
9. Go to `$BELENIOS`.
10. Edit `demo/ocsigenserver.conf.in`, in particular:
* the admin password
* the UUID of the main election
* the data directory (see above)
11. Run `demo/run-server.sh`. This script is a wrapper around
`ocsigenserver` and takes the same options. In particular, the
`-V` option is useful for debugging and `--help` can be used to
get help.
### Update a credential
1. Go to `/login-admin` on the live server and log in using the admin
password.
2. Go to `/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`.
`ballots.jsons` must be downloaded from the running webserver,
as well as `public_creds.txt` if some credentials were changed
during the election.
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-tool election finalize`. 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.
Legal
-----
......
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