Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
belenios
belenios
Commits
02eb2a3e
Commit
02eb2a3e
authored
Apr 21, 2016
by
Stephane Glondu
Browse files
Update documentation
parent
745202f4
Changes
8
Hide whitespace changes
Inline
Side-by-side
AUTHORS
0 → 100644
View file @
02eb2a3e
Main developer:
- Stéphane Glondu
Comments, review:
- Pierrick Gaudry
- Véronique Cortier
CHANGES.md
View file @
02eb2a3e
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
View file @
02eb2a3e
...
...
@@ -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
cho
o
se 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
View file @
02eb2a3e
...
...
@@ -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 vote
s
; the administrator collects, checks and publishes
all the ballots.
7.
The administrator closes the election.
8.
Trustees collectively decrypt the result.
...
...
VERSION
View file @
02eb2a3e
0.2
1.0
doc/tool.md
View file @
02eb2a3e
...
...
@@ -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/
elec
tion.json`
.
7.
R
un:
`belenios-tool mkelection --uuid $UUID
--group
$BELENIOS/demo/groups/default.json --template
$BELENIOS/demo/templates/
elec
tion.json`
. It should generate
`election.json`
in the current directory
.
8.
Create an empty
`ballots.jsons`
file.
6.
Edit
`$BELENIOS/demo/templates/
ques
tion
s
.json`
.
7.
Go to
`$DIR`
and r
un:
`belenios-tool mkelection --uuid $UUID
--group
$BELENIOS/demo/groups/default.json --template
$BELENIOS/demo/templates/
ques
tion
s
.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, a
d
d it to
`ballots.jsons`
and run:
For each received ballot, a
ppen
d 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 c
redential generation
###
C
redential 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 a
n 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
View file @
02eb2a3e
...
...
@@ -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-sen
si
tive
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
View file @
02eb2a3e
...
...
@@ -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/)."
;
]
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment