Skip to content
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

Updates documentation #160

Merged
merged 6 commits into from
Jul 27, 2022
+291 −12
Merged

Updates documentation #160

Changes from all 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
295 changes: 286 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -61,21 +61,298 @@
# 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 development 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
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

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.


**Proxy** - A proxy offers the mean for an external actor such as a website to
interact with a blockchain node. It is a 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 updates.

**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".

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

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. 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 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.

For a more formal and in-depth overview of the workflow, see the
[documentation](https://dedis.github.io/d-voting/#/api?id=signed-requests)

## 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.

### 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, 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 new RPC
endpoints on each node, which they can use to communicate with each other. 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 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 the
integrity of the elements is guarantee (i.e no elements have been modified,
Copy link
Contributor

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 performs a shuffling on the current list of
encrypted ballots and tries to submit it to the D-Voting smart contract. The
smart contract will accept only one shuffling step per block in the blockchain.
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)
</code>
</pre>

## 👩‍💻👨‍💻 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).

@@ -227,7 +504,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
```
4 changes: 3 additions & 1 deletion deb-package/README.md
View file
Original file line number Diff line number Diff line change
@@ -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):
@@ -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 \
Binary file added docs/assets/audit-black.png
View file
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
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
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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/assets/component-global.puml
View file
Original file line number Diff line number Diff line change
@@ -30,8 +30,8 @@ wb -> teq: authenticate
wf ~down~ iproxy2
wb ~down~ iproxy2

interface TPC as inode
interface TPC as inode2
interface gRPC as inode
interface gRPC as inode2

bc -- inode
bc2 -- inode2
Binary file added docs/assets/encrypt-black.png
View file
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
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
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
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
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
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
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
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
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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.