Running EEVHE

General information

To use EEVHE for an election some setup must be done. This is described in this article. EEVHE is a distributed service and for optimal security all server instances should run on different machines.

In the bin folder there is a number of launch-scripts which contains standard setups, which is used in this setup guide. By running bin/run.sh -h from a terminal configuration information is printed to the console.

This article will go through the possible configuration options, and explain them.

NOTE for SystemCOnfigurer, Voter and ResultFetcher instances there are a GUI application available here

Instances

The first thing that must be executed is the System Configurer, who creates configuration files used by both Decryption Authority instances and Bulletin Board Peers.

System Configurer

Used in creating the common input for all Decryption Authorities. These looks as follows:

Field	Description
pHex	Keygeneration parameter p in hexadecimal encoding
gHex	Keygeneration parameter g in hexadecimal encoding
eHex	Keygeneration parameter e in hexadecimal encoding
endTime	Time that election terminates in ms since January 1, 1970, 00:00:00 GMT
infos	List of (id, address) tuples for ALL Decryption Authorities
encodedElectionCertificate	.pem representation of the election certificate/global certificate

The input to the configurer is the termination time of the election. Votes cast after this moment are not valid. It is defines as: --time -days=#days -hours=#days -min=#minutes, where one or more of these can be specified.

The second input necessary is a list of addresses for all the Decryption Authorities on the form --da_addresses -id1_address1 -id3address2 ...

The third input necessary is a list of addresses for all the Bulletin Board peers on the form --bb_addresses -id1_address1 -id3address2 ...

Note that the addresses supplied are where the servers can BE accessed, meaning that if NGINX or similar forwards communication from address x to y the address should be x

The forth input are the location of the output file. This is passed as: --outputFolder=path/to/folder

The fifth and sixth inputs, are the locations of the .pem files containing the secret key, and the global certificate, respectively.

The folder will contain the common input for the Decryption Authorities in JSONformat, in the file common_input.json, and common input for the Bulletin Board Peers, also in JSON format, in the file BB_input.json.

The folder will also contain a .zip file for each DecryptionAuthority with a private key, and a certificate signed by the global certificate, and a zip file for each BulletinBoardPeer with a private key.

Bulletin Board

The bulletin board consists of two instance-types; The BB-Peer and BB-Edge respectively.

The BB-Peer instances will create a p2p network and keep a distributed state containing ballots, results and other information used throughout the election.

The edge nodes will act as helpers in communicating with the BB-Peers.

It is recommended, however not necessary, to run the peers on a private network only accessible by the edges, such that no-one outside said network can attempt an attack on the BB-Peer instances.

Bulletin Board Peer

The bulletin board peer instances are the advanced part of the bulletin board. The parameters, however, are simple.

Each peer needs to know its id - which needs to correspond to its address in the information given to the SystemConfigurer, which port it should listen on, with port=x, and the relative path to the folder containing the BB_input.json file, and the .zip file for this instance, with conf=relative/path.

Bulletin Board Edge

The Bulletin Board Edge takes the same parameters, however the id does not need to be an integer, as it is only used in logging statements. The conf path should just point to a folder with the BB_input.json file, as an edge has no private input.

Decryption Authority

The system should consist of one decryption authority for each of the addresses passed to the configurer. Note that any authority specified in that parameter, not created, will count as a corrupt party.

Each authority will need to be created with the only differing argument being its id.

The arguments are as follows:

• id the id is mandatory and must correspond to the address in the configuration that the authority is hosted on
• port the port to launch the server on - default=8080
• bb/bulletinBoard url pointing at the BulletinBoardEdge to be used in the election
• conf path to the directory containing the files output by the SystemConfigurer in the previous step

In addition to the arguments, a file containing the possible candidates must be present at the relative path $confArgument/candidates.json for all the honest decryption authorities, and a zip file containing the private input output by the SystemConfigurer named DA$id.zip

Using bin/decryptionAuthority.sh takes id as a paremeter, and assumes output from configurer is in conf/

Client

The client has two modes. Voting and getting results.

They have two parameters in common server and electionCertificate.

The server parameter specifies where the server is located. This must point to a valid BB-Edge instance, and is supplied by adding the following: --server=SERVER:PORT

The electionCertificate parameter specifies the relative path to the certificate used by the election holder, when signing certificates for both DA instances and BB-Peer instances. It is supplied by adding: --electionCertificate=some/path

Voting

Voting can take place from the time the Decryption Authorities has posted their public information entities to the bulletin board and up to the moment where the clock on the bulletin board exceeds the timestamp endTime from the common input generated by the System Configurer.

Votes is an integer corresponding to the index of the wanted candidate in the candidate list.

If no votes is supplied, the candidates are printed, and the program request as input the candidate to vote for.

There are multiple ways to vote. The bin/vote.sh posts a vote to a BulletinBoard assumed to be available at localhost:8080, after prompting the user for the candidate to vote for.

When testing bin/multiVote.sh can be called with an integer parameter denoting the amount of random votes to be cast. This also assumes bulletin board at localhost:8080

To vote to an external bulletin board use bin/run.sh --client --server=SERVER:PORT

Getting result

Results can be read after the poll has expired and all decryption authorities has posted their partial results. Using bin/getResult.sh results are retrieved and calculated from bulletin board assumed to be at localhost:8080.

To read from external bulletin board use bin/run.sh --client --server=SERVER:PORT --read=true