Skip to content

Commit 8a82240

Browse files
nkcrnkcr
authored
Merge pull request #160 from dedis/documentation-update
Updates documentation
2 parents c42d630 + 14e301e commit 8a82240

17 files changed

Lines changed: 291 additions & 12 deletions

‎README.md‎

Lines changed: 286 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -61,21 +61,298 @@
6161
# D-Voting
6262

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

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

70-
## Global architecture
72+
Main properties of the system are the following:
7173

72-
Find more about the architecture on the [documentation
73-
website](https://dedis.github.io/d-voting/#/).
74+
<div align="center">
75+
<img height="45px" src="docs/assets/spof-black.png#gh-light-mode-only">
76+
<img height="45px" src="docs/assets/spof-white.png#gh-dark-mode-only">
77+
</div>
78+
79+
**No single point of failure** - The system is supported by a decentralized
80+
network of blockchain nodes, making no single party able to break the system
81+
without compromising a Byzantine threshold of nodes. Additionally,
82+
side-protocols always distribute trust among nodes: The distributed key
83+
generation protocol (DKG) ensures that a threshold of honest node is needed to
84+
decrypt ballots, and the shuffling protocol needs at least one honest node to
85+
ensure privacy of voters. Only the identification and authorization mechanism
86+
make use of a central authority, but can accommodate to other solutions.
87+
88+
<div align="center">
89+
<img height="45px" src="docs/assets/privacy-black.png#gh-light-mode-only">
90+
<img height="45px" src="docs/assets/privacy-white.png#gh-dark-mode-only">
91+
</div>
92+
93+
**Privacy** - Ballots are cast on the client side using a safely-held
94+
distributed key-pair. The private key cannot not be revealed without coercing a
95+
threshold of nodes, and voters can retrieve the public key on any node. Ballots
96+
are decrypted only once a cryptographic process ensured that cast ballots cannot
97+
be linked to the original voter.
98+
99+
<div align="center">
100+
<img height="50px" src="docs/assets/audit-black.png#gh-light-mode-only">
101+
<img height="50px" src="docs/assets/audit-white.png#gh-dark-mode-only">
102+
</div>
103+
104+
**Transparency/Verifiability/Auditability** - The whole election process is
105+
recorded on the blockchain and signed by a threshold of blockchain nodes. Anyone
106+
can read and verify the log of events stored on the blockchain. Malicious
107+
behavior can be detected, voters can check that ballots are cast as intended,
108+
and auditors can witness the election process.
109+
110+
## 🧩 Global architecture
111+
112+
The project has 4 main high-level components:
113+
114+
**Proxy** - A proxy offers the mean for an external actor such as a website to
115+
interact with a blockchain node. It is a component of the blockchain node that
116+
exposes HTTP endpoints for external entities to send commands to the node. The
117+
proxy is notably used by the web clients to use the election system.
118+
119+
**Web frontend** - The web frontend is a web app built with React. It offers a
120+
view for end-users to use the D-Voting system. The app is meant to be used by
121+
voters and admins. Admins can perform administrative tasks such as creating an
122+
election, closing it, or revealing the results. Depending on the task, the web
123+
frontend will directly send HTTP requests to the proxy of a blockchain node, or
124+
to the web-backend.
125+
126+
**Web backend** - The web backend handles authentication and authorization. Some
127+
requests that need specific authorization are relayed from the web-frontend to
128+
the web-backend. The web backend checks the requests and signs messages before
129+
relaying them to the blockchain node, which trusts the web-backend. The
130+
web-backend has a local database to store configuration data such as
131+
authorizations. Admins use the web-frontend to perform updates.
132+
133+
**Blockchain node** - A blockchain node is the wide definition of the program
134+
that runs on a host and participate in the election logic. The blockchain node
135+
is built on top of Dela with an additional d-voting smart contract, proxy, and
136+
two services: DKG and verifiable Shuffling. The blockchain node is more
137+
accurately a subsystem, as it wraps many other components. Blockchain nodes
138+
communicate through gRPC with the [minogrpc][minogrpc] network overlay. We
139+
sometimes refer to the blockchain node simply as a "node".
140+
141+
The following component diagrams summarizes the interaction between those
142+
high-level components:
143+
144+
[minogrpc]: https://github.com/dedis/dela/tree/master/mino/minogrpc
74145

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

148+
You can find more information about the architecture on the [documentation
149+
website](https://dedis.github.io/d-voting/#/).
150+
151+
## Workflow
152+
153+
An election follows a specific workflow to ensure privacy of votes. Once an
154+
election is created and open, there are 4 main steps from the cast of a ballot
155+
to getting the result of the election:
156+
157+
<div align="center">
158+
<img height="55px" src="docs/assets/encrypt-black.png#gh-light-mode-only">
159+
<img height="55px" src="docs/assets/encrypt-white.png#gh-dark-mode-only">
160+
</div>
161+
162+
**1) Create ballot** The voter gets the shared public key and encrypts locally
163+
its ballot. The shared public key can be retrieved on any node and is associated
164+
to a private key that is distributed among the nodes. This process is done on
165+
the client's browser using the web-frontend.
166+
167+
<div align="center">
168+
<img height="80px" src="docs/assets/cast-black.png#gh-light-mode-only">
169+
<img height="80px" src="docs/assets/cast-white.png#gh-dark-mode-only">
170+
</div>
171+
172+
**2) Cast ballot** The voter submits its encrypted ballot as a transaction to one
173+
of the blockchain node. This operation is relayed by the web-backend which
174+
verifies that the voters has the right to vote. If successful, the encrypted
175+
ballot is stored on the blockchain. At this stage each encrypted ballot is
176+
associated to its voter on the blockchain.
177+
178+
<div align="center">
179+
<img height="70px" src="docs/assets/shuffle-black.png#gh-light-mode-only">
180+
<img height="70px" src="docs/assets/shuffle-white.png#gh-dark-mode-only">
181+
</div>
182+
183+
**3) Shuffle ballots** Once the election is closed by an admin, ballots are
184+
shuffled to ensure privacy of voters. This operation is done by a threshold of
185+
node that each perform their own shuffling. Each shuffling guaranties the
186+
integrity of ballots while re-encrypting and changing the order of ballots. At
187+
this stage encrypted ballots cannot be linked back to their voters.
188+
189+
<div align="center">
190+
<img height="90px" src="docs/assets/reveal-black.png#gh-light-mode-only">
191+
<img height="90px" src="docs/assets/reveal-white.png#gh-dark-mode-only">
192+
</div>
193+
194+
**4) Reveal ballots** Once ballots have been shuffled, they are decrypted and
195+
revealed. This operation is done only if the previous step is correctly
196+
executed. The decryption is done by a threshold of nodes that must each provide
197+
a contribution to achieve the decryption. Once done, the result of the election
198+
is stored on the blockchain.
199+
200+
For a more formal and in-depth overview of the workflow, see the
201+
[documentation](https://dedis.github.io/d-voting/#/api?id=signed-requests)
202+
203+
## Smart contract
204+
205+
A smart contract is a piece of code that runs on a blockchain. It defines a set
206+
of operations that act on a global state (think of it as database) and can be
207+
triggered with transactions. What makes a smart contract special is that its
208+
executions depends on a consensus among blockchain nodes where operations are
209+
successful only if a consensus is reached. Additionally, transactions and their
210+
results are permanently recorded and signed on an append-only ledger, making any
211+
operations on the blockchain transparent and permanent.
212+
213+
In the D-Voting system a single D-Voting smart contract handles the elections.
214+
The smart contract ensures that elections follow a correct workflow to
215+
guarantees its desirable properties such as privacy. For example, the smart
216+
contract won't allow ballots to be decrypted if they haven't been previously
217+
shuffled by a threshold of nodes.
218+
219+
## Services
220+
221+
Apart from executing smart contracts, blockchain nodes need additional side
222+
services to support an election. Side services can read from the global state
223+
and send transactions to write to it via the D-Voting smart contract. They are
224+
used to perform specific protocol executions not directly related to blockchain
225+
protocols such as the distributed key generation (DKG) and verifiable shuffling
226+
protocols.
227+
228+
### Distributed Key Generation (DKG)
229+
230+
The DKG service allows the creation of a distributed key-pair among multiple
231+
participants. Data encrypted with the key-pair can only be decrypted with the
232+
contribution of a threshold of participants. This makes it convenient to
233+
distribute trust on encrypted data. In the D-Voting project we use the Pedersen
234+
[[1]] version of DKG.
235+
236+
The DKG service needs to be setup at the beginning of each new election, because
237+
we want each election to have its own key-pair. Doing the setup requires two
238+
steps: 1\) Initialization and 2\) Setup. The initialization creates new RPC
239+
endpoints on each node, which they can use to communicate with each other. The
240+
second step, the setup, must be executed on one of the node. The setup step
241+
starts the DKG protocol and generates the key-pair. Once done, the D-Voting
242+
smart contract can be called to open the election, which will retrieve the DKG
243+
public key and save it on the smart contract.
244+
245+
[1]: https://dl.acm.org/doi/10.5555/1754868.1754929
246+
247+
### Verifiable shuffling
248+
249+
The shuffling service ensures that encrypted votes can not be linked to the user
250+
who cast them. Once the service is setup, each node can perform what we call a
251+
"shuffling step". A shuffling step re-orders an array of elements such that the
252+
integrity of the elements is guarantee (i.e no elements have been modified,
253+
added, or removed), but one can't trace how elements have been re-ordered.
254+
255+
In D-Voting we use the Neff [[2]] implementation of verifiable shuffling. Once
256+
an election is closed, an admin can trigger the shuffling steps from the nodes.
257+
During this phase, every node performs a shuffling on the current list of
258+
encrypted ballots and tries to submit it to the D-Voting smart contract. The
259+
smart contract will accept only one shuffling step per block in the blockchain.
260+
Nodes re-try to shuffle the ballots, using the latest shuffled list in the
261+
blockchain, until the result of their shuffling has been committed to the
262+
blockchain or a threshold of nodes successfully submitted their own shuffling
263+
results.
264+
265+
[2]: https://dl.acm.org/doi/10.1145/501983.502000
266+
267+
## 📁 Folders structure
268+
269+
<pre>
270+
<code>
271+
.
272+
├── cli
273+
│ ├── cosipbftcontroller Custom initialization of the blockchain node
274+
│ ├── <b>memcoin</b> Build the node CLI
275+
│ └── postinstall Custom node CLI setup
276+
├── <b>contracts</b>
277+
│ └── <b>evoting</b> D-Voting smart contract
278+
│ └── controller CLI commands for the smart contract
279+
├── deb-package Debian package for deployment
280+
├── docs Documentation
281+
├── integration Integration tests
282+
├── internal Internal packages: testing, tooling, tracing
283+
├── metrics
284+
│ └── controller CLI commands for Prometheus
285+
├── proxy Defines and implements HTTP handlers for the REST API
286+
├── <b>services</b>
287+
│ ├── dkg
288+
│ │ └── <b>pedersen</b> Implementation of the DKG service
289+
│ └── shuffle
290+
│ └── <b>neff</b> Implementation of the shuffle service
291+
└── <b>web</b>
292+
├── <b>backend</b>
293+
│ └── src Sources of the web backend (express.js server)
294+
└── <b>frontend</b>
295+
└── src Sources of the web frontend (react app)
296+
</code>
297+
</pre>
298+
299+
## 👩‍💻👨‍💻 Contributors
300+
301+
<table>
302+
<tr style="font-weight:bold">
303+
<td>Period</td>
304+
<td>Contributors(s)</td>
305+
<td>Activities</td>
306+
<td>Links</td>
307+
</tr>
308+
<tr>
309+
<td>Spring 2021</td>
310+
<td>Students: Anas Ibrahim, Vincent Parodi<br>Supervisor: Noémien Kocher</td>
311+
<td>Initial implementation of the smart contract and services</td>
312+
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2021/07/report-2021-1-Vincent-Anas_EvotingDela.pdf">Report</a></td>
313+
</tr>
314+
<tr>
315+
<td>Spring 2021</td>
316+
<td>Student: Sarah Antille<br>Supervisor: Noémien Kocher</td>
317+
<td>Initial implementation of the web frontend in react</td>
318+
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2021/07/report-2021-1-SarahAntille_EvotingonDela.pdf">Report</a></td>
319+
</tr>
320+
<tr>
321+
<td>Fall 2021</td>
322+
<td>Students: Auguste Baum, Emilien Duc<br>Supervisor: Noémien Kocher</td>
323+
<td>Adds a flexible election structure. Improves robustness and security.</td>
324+
<td>
325+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/report-2021-3-baum-auguste-Dvoting.pdf">Report</a>,
326+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/presentation-2021-3-baum-auguste-dvoting.pdf">Presentation</a>
327+
</td>
328+
</tr>
329+
<tr>
330+
<td>Fall 2021</td>
331+
<td>Students: Ambroise Borbely<br>Supervisor: Noémien Kocher</td>
332+
<td>Adds authentication and authorization mechanism on the frontend.</td>
333+
<td><a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/02/report-2021-3-borbely-ambroise-DVotingFrontend.pdf">Report</a></td>
334+
</tr>
335+
<tr>
336+
<td>Spring 2022</td>
337+
<td>Students: Guanyu Zhang, Igowa Giovanni<br>Supervisor: Noémien Kocher<br>Assistant: Emilien Duc</td>
338+
<td>Improves production-readiness: deploy a test pipeline and analyze the system's robustness.</td>
339+
<td>
340+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/report-2022-1-giovanni-zhang-d-voting-production.pdf">Report</a>,
341+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/presentation-2022-1-giovanni-zhang-d-voting-production.pdf">Presentation</a>
342+
</td>
343+
</tr>
344+
<tr>
345+
<td>Spring 2022</td>
346+
<td>Students: Badr Larhdir, Capucine Berger<br>Supervisor: Noémien Kocher</td>
347+
<td>Major iteration over the frontend - design and functionalities: implements a flexible election form, nodes setup, and result page.</td>
348+
<td>
349+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/report-2022-1-capucine-badr-d-voting-frontend.pdf">Report</a>,
350+
<a href="https://www.epfl.ch/labs/dedis/wp-content/uploads/2022/07/presentation-2022-1-capucine-badr-d-voting-frontend.pdf">Presentation</a>
351+
</td>
352+
</tr>
353+
</table>
77354

78-
# Setup
355+
# ⚙️ Setup
79356

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

@@ -227,7 +504,7 @@ To install a package run the following:
227504

228505
```sh
229506
echo "deb http://apt.dedis.ch/ squeeze main" >> /etc/apt/sources.list
230-
wget -q -O- http://apt.dedis.ch/unicore.gpg | sudo apt-key add -
507+
wget -q -O- http://apt.dedis.ch/dvoting-release.pgp | sudo apt-key add -
231508
sudo apt update
232509
sudo apt install dedis-dvoting
233510
```

‎deb-package/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ with the node's public address:
4343
export dela_public="//172.16.253.150:9000"
4444
```
4545

46+
and don't forget to restart the service!
47+
4648
### Leader's node
4749

4850
Get the token and certificate (24h * 30 = 720):
@@ -100,7 +102,7 @@ sudo memcoin --config /var/opt/dedis/dvoting/data/dela ordering setup \
100102
```sh
101103
PK=<> # taken from the "ordering export", the part after ":"
102104
sudo memcoin --config /var/opt/dedis/dvoting/data/dela pool add \
103-
--key /home/user/master.key \
105+
--key /home/dedis/private.key \
104106
--args go.dedis.ch/dela.ContractArg --args go.dedis.ch/dela.Access \
105107
--args access:grant_id --args 0300000000000000000000000000000000000000000000000000000000000000 \
106108
--args access:grant_contract --args go.dedis.ch/dela.Evoting \

‎docs/assets/audit-black.png‎

3.52 KB
Loading

‎docs/assets/audit-white.png‎

2.88 KB
Loading

‎docs/assets/cast-black.png‎

5.22 KB
Loading

‎docs/assets/cast-white.png‎

4.33 KB
Loading

‎docs/assets/component-global.puml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@ wb -> teq: authenticate
3030
wf ~down~ iproxy2
3131
wb ~down~ iproxy2
3232

33-
interface TPC as inode
34-
interface TPC as inode2
33+
interface gRPC as inode
34+
interface gRPC as inode2
3535

3636
bc -- inode
3737
bc2 -- inode2

‎docs/assets/encrypt-black.png‎

4.79 KB
Loading

‎docs/assets/encrypt-white.png‎

4.14 KB
Loading

‎docs/assets/privacy-black.png‎

3.37 KB
Loading

0 commit comments

Comments
 (0)