<commit_before>Who does what during a Belenios election ?
=============

Introduction
------------

Belenios proposes a verifiable e-voting system. Each voter can check that
her ballot is indeed in the ballot box, and any third-party can verify
that the claimed result corresponds to the ballots present in the ballot
box, and that these ballots come from legitimate voters. The vote secrecy
is ensured via the splitting of the decryption key between several
authorities (for instance, some members of the committee in charge of the
election) with a threshold mechanism (for instance, 3 among 5 are enough
to decrypt).

But the nice security properties hold only if everyone performs all the
verifications that they are supposed to do. This document lists in
detail, for each role in the election (voter, administrator, etc) what
must be done at each step.

Instructions for the voter
--------------------------

When a voter wants to vote online, his computer encrypts his choices
(with a Javascript program) and prints a `smart ballot tracker` which is
a fingerprint of the ballot. This `smart ballot tracker` is also sent by
email to the voter when he has completed the voting procedure.

In order to check that his ballot is indeed taken into account, the voter
must check that his `smart ballot tracker` is present in the ballot box
by visiting the link `See accepted ballots` on the main page of the
election. The voter must also vehemently protest if he receives a
confirmation email that contains a `smart ballot tracker` that is
different from the one that was printed on the screen during the voting
phase. Somebody probably managed to add a ballot in his name. This can
for instance be a hint of an attack by a system administrator who has
access to the mailbox of the voter, in the case where both the login /
password and the credential are sent to the same address.

Note: a voter can vote several times. Only the *last* vote is taken into
account. The voter must check that the last `smart ballot tracker` is in
the ballot box. The previous smart ballot trackers are removed from the
box.

A voter can also verify the whole voting process. Instead of checking only
the presence of his ballot in the ballot box, he can verify the validity
of all the ballots, he can monitor the ballot box to check that no ballot
disappears (except in case of revote), and finally check that the claim
result corresponds to the ballots in the ballot box. For all of this, the
voter can follow the auditor instructions below.

Instructions for the trustees
-----------------------------

During the setup of the election, it is expected that the trustee saves:

- her decryption key (or PKI key, in threshold mode) (file `
  private_key.json` or `private_key.txt`). **This key must be saved in a
  secure place** (encrypted container, USB stick stored in a closed place,
  etc) because it protects the secret of the votes (in combination with
  the decryption keys of the other trustees);
- the `url` of the election;
- (in threshold mode) the fingerprint of her PKI public key, simply
  called `public key` below;
- the fingerprint of her verification key associated to her decryption
  key `verification key`.

As soon as the election is ready, it is expected that the trustee checks:

- that her `verification key` is present on the election page, aside her
  name;
- (in threshold mode) that her PKI `public key` is present on the
  election page, aside her name.

After the closing of the election, the trustee participates to the
computation of the tally. In the case of an election with alternative
voting (ordering of the candidates, giving them a grade), the tally
starts by a shuffle phase. For this it is expected from the trustee that
she

- saves the fingerprint of the ballot box after her shuffle: `fingerprint
  of your shuffle`;
- checks immediately thereafter that this fingerprint is present on the
  page of the election (to ensure that her shuffle has not be ignored).

In all cases, the tally then proceeds with a phase where the trustee uses
her private key to decrypt the result. It is expected that the trustee:

- checks (only for alternative voting) the fingerprint of her shuffle
  `fingerprint of your shuffle` as saved in the previous step is present
  on the page of the election, aside her name. If this is not the case,
  the private key must not be used.
- saves the fingerprint of the ballot box to be decrypted: `fingerprint
  of the encrypted tally`.


Once the tally is finished, the results are published on the page of the
election. It is expected that the trustee checks that the following data
are present on this page, each time associated to her name:

- (in threshold mode) her PKI `public key`;
- her `verification key`;
- (for alternative voting) the fingerprint of her shuffle;
- the fingerprint of the ballot box to be decrypted `fingerprint of the
  encrypted tally` (in order to check that her private key has not be
  used to decrypt something else).


Instructions for the credential authority
-----------------------------------------

The main role of the credential authority is to generate and transmit
a private credential to each voter.

**Setup.** During the setup of the election, the credential authority
first obtains a private url that allows her to retrieve the voter list
`voters.txt`.  The credential authority must verify with the committee
in charge of the election that this list is correct, as well as the
weight of each voter in case of a weighted vote;

Then the authority has two options to generate the credentials:
- either click on `Generate` on her browser;
- or:
  - copy the voter list to a file, e.g. `voter.txt`;
  - let `$UUID` be the identifier of the election (the last component
    in the given election URL);
  - let `$GROUP` be either `BELENIOS-2048` (if there are no
    alternative questions) or `RFC-3526-2048` (if there is at least
    one alternative question);
  - run the command:

        belenios-tool credgen --file voters.txt --group <(echo $GROUP) --uuid $UUID

    It will generate two files, `$TIMESTAMP.privcreds` and
    `$TIMESTAMP.pubcreds`;
  - upload the `.pubcreds` file with the `Submit by file` form;
  - [compute the fingerprint](#hash) of the `.pubcreds` file and save
    it as `fingerprint of the public credentials`;
  - keep the `.privcreds` file and save it as `creds.txt`.

The second option should be preferred for more security, in particular
if there is no auditor in charge of monitoring the server.<commit_msg>Update instructions-en.md with instructions to check URL of static pages<commit_after>Who does what during a Belenios election ?
=============

Introduction
------------

Belenios proposes a verifiable e-voting system. Each voter can check that
her ballot is indeed in the ballot box, and any third-party can verify
that the claimed result corresponds to the ballots present in the ballot
box, and that these ballots come from legitimate voters. The vote secrecy
is ensured via the splitting of the decryption key between several
authorities (for instance, some members of the committee in charge of the
election) with a threshold mechanism (for instance, 3 among 5 are enough
to decrypt).

But the nice security properties hold only if everyone performs all the
verifications that they are supposed to do. This document lists in
detail, for each role in the election (voter, administrator, etc) what
must be done at each step.

Instructions for the voter
--------------------------

When a voter wants to vote online, his computer encrypts his choices
(with a Javascript program) and prints a `smart ballot tracker` which is
a fingerprint of the ballot. This `smart ballot tracker` is also sent by
email to the voter when he has completed the voting procedure.

In order to check that his ballot is indeed taken into account, the voter
must check that his `smart ballot tracker` is present in the ballot box
by visiting the link `See accepted ballots` on the main page of the
election. The voter must also vehemently protest if he receives a
confirmation email that contains a `smart ballot tracker` that is
different from the one that was printed on the screen during the voting
phase. Somebody probably managed to add a ballot in his name. This can
for instance be a hint of an attack by a system administrator who has
access to the mailbox of the voter, in the case where both the login /
password and the credential are sent to the same address.

Note: a voter can vote several times. Only the *last* vote is taken into
account. The voter must check that the last `smart ballot tracker` is in
the ballot box. The previous smart ballot trackers are removed from the
box.

A voter can also verify the whole voting process. Instead of checking only
the presence of his ballot in the ballot box, he can verify the validity
of all the ballots, he can monitor the ballot box to check that no ballot
disappears (except in case of revote), and finally check that the claim
result corresponds to the ballots in the ballot box. For all of this, the
voter can follow the auditor instructions below.

Instructions for the trustees
-----------------------------

During the setup of the election, each trustee is invited to generate
a decryption key by following a link sent by the election
administrator. The trustee must follow the link, and make sure the URL
of the resulting page has one of the following forms:

- `PREFIX/draft/trustee.html#UUID-TOKEN`, or
- `PREFIX/draft/threshold-trustee.html#UUID-TOKEN` (in threshold mode)

Moreover, it is expected that the trustee saves:

- her decryption key (or PKI key, in threshold mode) (file `
  private_key.json` or `private_key.txt`). **This key must be saved in a
  secure place** (encrypted container, USB stick stored in a closed place,
  etc) because it protects the secret of the votes (in combination with
  the decryption keys of the other trustees);
- the `url` of the election;
- (in threshold mode) the fingerprint of her PKI public key, simply
  called `public key` below;
- the fingerprint of her verification key associated to her decryption
  key `verification key`.

As soon as the election is ready, it is expected that the trustee checks:

- that her `verification key` is present on the election page, aside her
  name;
- (in threshold mode) that her PKI `public key` is present on the
  election page, aside her name.

After the closing of the election, the trustee participates to the
computation of the tally. In the case of an election with alternative
voting (ordering of the candidates, giving them a grade), the tally
starts by a shuffle phase. For this it is expected from the trustee that
she

- checks that the URL of the page has the following form:
  `PREFIX/election/shuffle.html#UUID-TOKEN`
- saves the fingerprint of the ballot box after her shuffle: `fingerprint
  of your shuffle`;
- checks immediately thereafter that this fingerprint is present on the
  page of the election (to ensure that her shuffle has not be ignored).

In all cases, the tally then proceeds with a phase where the trustee uses
her private key to decrypt the result. It is expected that the trustee:

- checks that the URL of the page has the following form:
  `PREFIX/election/trustees.html#UUID-TOKEN`
- checks (only for alternative voting) the fingerprint of her shuffle
  `fingerprint of your shuffle` as saved in the previous step is present
  on the page of the election, aside her name. If this is not the case,
  the private key must not be used.
- saves the fingerprint of the ballot box to be decrypted: `fingerprint
  of the encrypted tally`.


Once the tally is finished, the results are published on the page of the
election. It is expected that the trustee checks that the following data
are present on this page, each time associated to her name:

- (in threshold mode) her PKI `public key`;
- her `verification key`;
- (for alternative voting) the fingerprint of her shuffle;
- the fingerprint of the ballot box to be decrypted `fingerprint of the
  encrypted tally` (in order to check that her private key has not be
  used to decrypt something else).


Instructions for the credential authority
-----------------------------------------

The main role of the credential authority is to generate and transmit
a private credential to each voter.

**Setup.** During the setup of the election, the credential authority
first obtains a private link. She must follow the link, and make sure
the URL of the resulting page has the following form:
`PREFIX/draft/credentials.html#UUID-TOKEN`.

On this page, there is the voter list. The credential authority must
verify with the committee in charge of the election that this list is
correct, as well as the weight of each voter in case of a weighted
vote;

Then the authority has two options to generate the credentials:
- either click on `Generate` on her browser;
- or:
  - copy the voter list to a file, e.g. `voter.txt`;
  - let `$UUID` be the identifier of the election (the last component
    in the given election URL);
  - let `$GROUP` be either `BELENIOS-2048` (if there are no
    alternative questions) or `RFC-3526-2048` (if there is at least
    one alternative question);
  - run the command:

        belenios-tool credgen --file voters.txt --group <(echo $GROUP) --uuid $UUID

    It will generate two files, `$TIMESTAMP.privcreds` and
    `$TIMESTAMP.pubcreds`;
  - upload the `.pubcreds` file with the `Submit by file` form;
  - [compute the fingerprint](#hash) of the `.pubcreds` file and save
    it as `fingerprint of the public credentials`;
  - keep the `.privcreds` file and save it as `creds.txt`.

The second option should be preferred for more security, in particular
if there is no auditor in charge of monitoring the server.
{'fraction_non_alphanumeric': 0.06212395795578108, 'fraction_numerical': 0.002029720913374411, 'mean_word_length': 3.7786629719431937, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '773717', 'n_tokens_mistral': 3614, 'n_tokens_neox': 3387, 'n_words': 2188}