Skip to content

Updates documentation #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nkcr merged 6 commits into from
Jul 27, 2022
Merged

Updates documentation #160

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
59f505e
Updates the documentation
nkcr Jul 20, 2022
373b08b
Adds contributors and folders structure
nkcr Jul 20, 2022
24b2b58
Adds architecture and steps documentation
nkcr Jul 21, 2022
659077d
Updates dark icons
nkcr Jul 21, 2022
909c87f
Applies a self review
nkcr Jul 21, 2022
14e301e
Addresses Pierluca's comments
nkcr Jul 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
294 changes: 285 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,21 +61,297 @@
# D-Voting

**D-Voting** is an e-voting platform based on the
[Dela](https://github.com/dedis/dela) blockchain. In short:
[Dela](https://github.com/dedis/dela) blockchain. It uses state-of-the-art
protocols that guarantee privacy of votes and a fully decentralized process.
This project was born in early 2021 and has been iteratively implemented by EPFL
students under the supervision of DEDIS members.

- An open platform to run voting instances on a blockchain
- Provides privacy of votes with state-of-the art protocols
- Fully auditable and decentralized process
⚠️ This project is still under developpment and should not be used for real
elections.

## Global architecture
Main properties of the system are the following:

Find more about the architecture on the [documentation
website](https://dedis.github.io/d-voting/#/).
<div align="center">
<img height="45px" src="docs/assets/spof-black.png#gh-light-mode-only">
<img height="45px" src="docs/assets/spof-white.png#gh-dark-mode-only">
</div>

**No single point of failure** The system is supported by a decentralized
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here and elsewhere, this would help readability:

Suggested change
**No single point of failure** The system is supported by a decentralized
**No single point of failure -** The system is supported by a decentralized

network of blockchain nodes, making no single party able to break the system
without compromising a Byzantine threshold of nodes. Additionally,
side-protocols always distribute trust among nodes: The distributed key
generation protocol (DKG) ensures that a threshold of honest node is needed to
decrypt ballots, and the shuffling protocol needs at least one honest node to
ensure privacy of voters. Only the identification and authorization mechanism
make use of a central authority, but can accommodate to other solutions.

<div align="center">
<img height="45px" src="docs/assets/privacy-black.png#gh-light-mode-only">
<img height="45px" src="docs/assets/privacy-white.png#gh-dark-mode-only">
</div>

**Privacy** Ballots are cast on the client side using a safely-held distributed
key-pair. The private key cannot not be revealed without coercing a threshold of
nodes, and voters can retrieve the public key on any node. Ballots are decrypted
only once a cryptographic process ensured that cast ballots cannot be linked to
the original voter.

<div align="center">
<img height="50px" src="docs/assets/audit-black.png#gh-light-mode-only">
<img height="50px" src="docs/assets/audit-white.png#gh-dark-mode-only">
</div>

**Transparency/Verifiability/Auditability** The whole election process is
recorded on the blockchain and signed by a threshold of blockchain nodes. Anyone
can read and verify the log of events stored on the blockchain. Malicious
behavior can be detected, voters can check that ballots are cast as intended,
and auditors can witness the election process.

## 🧩 Global architecture

The project has 4 main high-level components:
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering if it'd make it easier to follow by starting with the web interface (that everyone understands), then moving on to the web backend, the proxy (as the interface between non-blockchain and blockchain environments) and finally introducing the blockchain node itself.


**Blockchain node** A blockchain node is the wide definition of the program that
runs on a host and participate in the election logic. The blockchain node is
built on top of Dela with an additional d-voting smart contract, proxy, and two
services: DKG and verifiable Shuffling. The blockchain node is more accurately a
subsystem, as it wraps many other components. Blockchain nodes communicate
through gRPC with the [minogrpc][minogrpc] network overlay. We sometimes refer
to the blockchain node simply as a "node".
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph is very confusing. It introduces many terms that a novice would not yet be familiar with.


**Proxy** A proxy enables external interactions on a blockchain node. It is a
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"external" from what ? I'm being a bit picky here, but this could be clearer.

component of the blockchain node that exposes HTTP endpoints for external
entities to send commands to the node. The proxy is notably used by the web
clients to use the election system.

**Web frontend** The web frontend is a web app built with React. It offers a
view for end-users to use the D-Voting system. The app is meant to be used by
voters and admins. Admins can perform administrative tasks such as creating an
election, closing it, or revealing the results. Depending on the task, the web
frontend will directly send HTTP requests to the proxy of a blockchain node, or
to the web-backend.

**Web backend** The web backend handles authentication and authorization. Some
requests that need specific authorization are relayed from the web-frontend to
the web-backend. The web backend checks the requests and signs messages before
relaying them to the blockchain node, which trusts the web-backend. The
web-backend has a local database to store configuration data such as
authorizations. Admins use the web-frontend to perform update.
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
authorizations. Admins use the web-frontend to perform update.
authorizations. Admins use the web-frontend to perform updates.


The following component diagrams summarizes the interaction between those
high-level components:

[minogrpc]: https://github.com/dedis/dela/tree/master/mino/minogrpc

![Global component diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/dedis/d-voting/main/docs/assets/component-global.puml)
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This shows "TPC", a term that's introduced nowhere in this document, which could create confusion.


You can find more information about the architecture on the [documentation
website](https://dedis.github.io/d-voting/#/).

## Workflow

An election follows a specific workflow to ensure privacy of votes. You can
find more about it in the
[documentation](https://dedis.github.io/d-voting/#/api?id=signed-requests), but
here is a high-level recap.

Once an election is created and open, there are 4 main steps from the cast of a
ballot to getting the result of the election:
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would consider moving the pointer to the documentation at the end of the section, as in
For a more formal and in-depth overview of the workflow, see the [documentation]
This makes for a more natural read than having to skip over this to get to the actual content of the paragraph

Suggested change
An election follows a specific workflow to ensure privacy of votes. You can
find more about it in the
[documentation](https://dedis.github.io/d-voting/#/api?id=signed-requests), but
here is a high-level recap.
Once an election is created and open, there are 4 main steps from the cast of a
ballot to getting the result of the election:
An election follows a specific workflow to ensure privacy of votes.
Once an election is created and open, there are 4 main steps from the cast of a
ballot to getting the result of the election:


<div align="center">
<img height="55px" src="docs/assets/encrypt-black.png#gh-light-mode-only">
<img height="55px" src="docs/assets/encrypt-white.png#gh-dark-mode-only">
</div>

**1) Create ballot** The voter gets the shared public key and encrypts locally
its ballot. The shared public key can be retrieved on any node and is associated
to a private key that is distributed among the nodes. This process is done on
the client's browser using the web-frontend.

<div align="center">
<img height="80px" src="docs/assets/cast-black.png#gh-light-mode-only">
<img height="80px" src="docs/assets/cast-white.png#gh-dark-mode-only">
</div>

**2) Cast ballot** The voter submits its encrypted ballot as a transaction to one
of the blockchain node. This operation is relayed by the web-backend which
verifies that the voters has the right to vote. If successful, the encrypted
ballot is stored on the blockchain. At this stage each encrypted ballot is
associated to its voter on the blockchain.

<div align="center">
<img height="70px" src="docs/assets/shuffle-black.png#gh-light-mode-only">
<img height="70px" src="docs/assets/shuffle-white.png#gh-dark-mode-only">
</div>

**3) Shuffle ballots** Once the election is closed by an admin, ballots are
shuffled to ensure privacy of voters. This operation is done by a threshold of
node that each perform their own shuffling. Each shuffling guaranties the
integrity of ballots while re-encrypting and changing the order of ballots. At
this stage encrypted ballots cannot ne linked back to their voters.
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
this stage encrypted ballots cannot ne linked back to their voters.
this stage encrypted ballots cannot be linked back to their voters.


<div align="center">
<img height="90px" src="docs/assets/reveal-black.png#gh-light-mode-only">
<img height="90px" src="docs/assets/reveal-white.png#gh-dark-mode-only">
</div>

**4) Reveal ballots** Once ballots have been shuffled, they are decrypted and
revealed. This operation is done only if the previous step is correctly
executed. The decryption is done by a threshold of nodes that must each provide
a contribution to achieve the decryption. Once done, the result of the election
is stored on the blockchain.

## Smart contract

A smart contract is a piece of code that runs on a blockchain. It defines a set
of operations that act on a global state (think of it as database) and can be
triggered with transactions. What makes a smart contract special is that its
executions depends on a consensus among blockchain nodes where operations are
successful only if a consensus is reached. Additionally, transactions and their
results are permanently recorded and signed on an append-only ledger, making any
operations on the blockchain transparent and permanent.

In the D-Voting system a single D-Voting smart contract handles the elections.
The smart contract ensures that elections follow a correct workflow to
guarantees its desirable properties such as privacy. For example, the smart
contract won't allow ballots to be decrypted if they haven't been previously
shuffled by a threshold of nodes.

## Services

Apart from executing smart contracts, blockchain nodes need additional side
services to support an election. Side services can read from the global state
and send transactions to write to it via the D-Voting smart contract. They are
used to perform specific protocol executions not directly related to blockchain
protocols such as the distributed key generation (DKG) and verifiable shuffling
protocols.

### DKG

DKG stands for Distributed Key Generation. This service allows the creation of a
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### DKG
DKG stands for Distributed Key Generation. This service allows the creation of a
### Distributed Key Generation (DKG)
The DKG service allows the creation of a

distributed key-pair among multiple participants. Data encrypted with the
key-pair can only be decrypted with the contribution of a threshold of
participants. This makes it convenient to distribute trust on encrypted data. In
the D-Voting project we use the Pedersen [[1]] version of DKG.

The DKG service needs to be setup at the beginning of each new election - we
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The DKG service needs to be setup at the beginning of each new election - we
The DKG service needs to be setup at the beginning of each new election, because we

want each election to have its own key-pair. Doing the setup requires two steps:
1\) Initialization and 2\) Setup. The initialization creates a new RPC for nodes
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RPC is Dela terminology in this usage. RPC normally stands for "Remote procedure call", so this reads "The initialization creates a new remote procedure call for nodes to communicate" .... -> it's confusing.

Could we say that the initialization creates new RPC endpoints on each node, which they can use to communicate with each other ?

to communicate and must be done on each node. The second step, setup, must be
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to communicate and must be done on each node. The second step, setup, must be
to communicate and must be done on each node. The second step, the setup, must be

executed on one of the node. The setup step starts the DKG protocol and
generates the key-pair. Once done, the D-Voting smart contract can be called to
open the election, which will retrieve the DKG public key and save it on the
smart contract.

[1]: https://dl.acm.org/doi/10.5555/1754868.1754929

### Verifiable shuffling

The shuffling service ensures that encrypted votes can not be linked to their
voters. Once the service is setup, each node can perform what we call a
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The shuffling service ensures that encrypted votes can not be linked to their
voters. Once the service is setup, each node can perform what we call a
The shuffling service ensures that encrypted ballots can not be linked to the user who cast them.
Once the service is setup, each node can perform what we call a

"shuffling step". A shuffling step re-orders an array of elements such that
integrity of the elements is guarantee (i.e no elements have been modified,
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
integrity of the elements is guarantee (i.e no elements have been modified,
the integrity of the elements is guaranteed (i.e no elements have been modified,

added, or removed), but one can't trace how elements have been re-ordered.

In D-Voting we use the Neff [[2]] implementation of verifiable shuffling. Once
an election is closed, an admin can trigger the shuffling steps from the nodes.
During this phase, every node perform a shuffling on the current list of
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
During this phase, every node perform a shuffling on the current list of
During this phase, every node performs a shuffling on the current list of

encrypted ballots and try to submit it to the D-Voting smart contract. The smart
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
encrypted ballots and try to submit it to the D-Voting smart contract. The smart
encrypted ballots and tries to submit it to the D-Voting smart contract. The smart

contract will accept only one shuffling step per block, and nodes repeat their
shuffling step with the latest shuffled list until their shuffling step has been
accepted or a threshold of nodes successfully submitted their shuffling steps.
Copy link
Contributor

@pierluca pierluca Jul 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
contract will accept only one shuffling step per block, and nodes repeat their
shuffling step with the latest shuffled list until their shuffling step has been
accepted or a threshold of nodes successfully submitted their shuffling steps.
contract will accept only one shuffling operation per block in the blockchain,
and nodes re-try to shuffle the ballots, using the latest shuffled list in the blockchain, until the result of their shuffling has been committed to the blockchain or a threshold of nodes successfully submitted their own shuffling results.


[2]: https://dl.acm.org/doi/10.1145/501983.502000

## 📁 Folders structure

<pre>
<code>
.
├── cli
│ ├── cosipbftcontroller Custom initialization of the blockchain node
│ ├── <b>memcoin</b> Build the node CLI
│ └── postinstall Custom node CLI setup
├── <b>contracts</b>
│ └── <b>evoting</b> D-Voting smart contract
│ └── controller CLI commands for the smart contract
├── deb-package Debian package for deployment
├── docs Documentation
├── integration Integration tests
├── internal Internal packages: testing, tooling, tracing
├── metrics
│ └── controller CLI commands for Prometheus
├── proxy Defines and implements HTTP handlers for the REST API
├── <b>services</b>
│ ├── dkg
│ │ └── <b>pedersen</b> Implementation of the DKG service
│ └── shuffle
│ └── <b>neff</b> Implementation of the shuffle service
└── <b>web</b>
├── <b>backend</b>
│ └── src Sources of the web backend (express.js server)
└── <b>frontend</b>
└── src Sources of the web frontend (react app)
</pre>
</code>

## 👩‍💻👨‍💻 Contributors

<table>
<tr style="font-weight:bold">
<td>Period</td>
<td>Contributors(s)</td>
<td>Activities</td>
<td>Links</td>
</tr>
<tr>
<td>Spring 2021</td>
<td>Students: Anas Ibrahim, Vincent Parodi<br>Supervisor: Noémien Kocher</td>
<td>Initial implementation of the smart contract and services</td>
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2021/07/report-2021-1-Vincent-Anas_EvotingDela.pdf">Report</a></td>
</tr>
<tr>
<td>Spring 2021</td>
<td>Student: Sarah Antille<br>Supervisor: Noémien Kocher</td>
<td>Initial implementation of the web frontend in react</td>
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2021/07/report-2021-1-SarahAntille_EvotingonDela.pdf">Report</a></td>
</tr>
<tr>
<td>Fall 2021</td>
<td>Students: Auguste Baum, Emilien Duc<br>Supervisor: Noémien Kocher</td>
<td>Adds a flexible election structure. Improves robustness and security.</td>
<td>
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/report-2021-3-baum-auguste-Dvoting.pdf">Report</a>,
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/presentation-2021-3-baum-auguste-dvoting.pdf">Presentation</a>
</td>
</tr>
<tr>
<td>Fall 2021</td>
<td>Students: Ambroise Borbely<br>Supervisor: Noémien Kocher</td>
<td>Adds authentication and authorization mechanism on the frontend.</td>
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/report-2021-3-borbely-ambroise-DVotingFrontend.pdf">Report</a></td>
</tr>
<tr>
<td>Spring 2022</td>
<td>Students: Guanyu Zhang, Igowa Giovanni<br>Supervisor: Noémien Kocher<br>Assistant: Emilien Duc</td>
<td>Improves production-readiness: deploy a test pipeline and analyze the system's robustness.</td>
<td>
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/report-2022-1-giovanni-zhang-d-voting-production.pdf">Report</a>,
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/presentation-2022-1-giovanni-zhang-d-voting-production.pdf">Presentation</a>
</td>
</tr>
<tr>
<td>Spring 2022</td>
<td>Students: Badr Larhdir, Capucine Berger<br>Supervisor: Noémien Kocher</td>
<td>Major iteration over the frontend - design and functionalities: implements a flexible election form, nodes setup, and result page.</td>
<td>
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/report-2022-1-capucine-badr-d-voting-frontend.pdf">Report</a>,
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/presentation-2022-1-capucine-badr-d-voting-frontend.pdf">Presentation</a>
</td>
</tr>
</table>

# Setup
# ⚙️ Setup

First be sure to have Go installed (at least 1.17).

Expand Down Expand Up @@ -227,7 +503,7 @@ To install a package run the following:

```sh
echo "deb http://apt.dedis.ch/ squeeze main" >> /etc/apt/sources.list
wget -q -O- http://apt.dedis.ch/unicore.gpg | sudo apt-key add -
wget -q -O- http://apt.dedis.ch/dvoting-release.pgp | sudo apt-key add -
sudo apt update
sudo apt install dedis-dvoting
```
Expand Down
4 changes: 3 additions & 1 deletion deb-package/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ with the node's public address:
export dela_public="//172.16.253.150:9000"
```

and don't forget to restart the service!

### Leader's node

Get the token and certificate (24h * 30 = 720):
Expand Down Expand Up @@ -100,7 +102,7 @@ sudo memcoin --config /var/opt/dedis/dvoting/data/dela ordering setup \
```sh
PK=<> # taken from the "ordering export", the part after ":"
sudo memcoin --config /var/opt/dedis/dvoting/data/dela pool add \
--key /home/user/master.key \
--key /home/dedis/private.key \
--args go.dedis.ch/dela.ContractArg --args go.dedis.ch/dela.Access \
--args access:grant_id --args 0300000000000000000000000000000000000000000000000000000000000000 \
--args access:grant_contract --args go.dedis.ch/dela.Evoting \
Expand Down
Binary file added docs/assets/audit-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/audit-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/cast-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/cast-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/encrypt-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/encrypt-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/privacy-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/privacy-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/reveal-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/reveal-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/shuffle-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/shuffle-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/spof-black.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/spof-white.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.