diff --git a/README.md b/README.md index 26e9b3d47..88dad8ce3 100644 --- a/README.md +++ b/README.md @@ -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/#/). +
+ + +
+ +**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. + +
+ + +
+ +**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. + +
+ + +
+ +**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: + +**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) +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: + +
+ + +
+ +**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. + +
+ + +
+ +**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. + +
+ + +
+ +**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. + +
+ + +
+ +**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, +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 + +
+
+.
+β”œβ”€β”€ cli    
+β”‚   β”œβ”€β”€ cosipbftcontroller  Custom initialization of the blockchain node
+β”‚   β”œβ”€β”€ memcoin             Build the node CLI
+β”‚   └── postinstall         Custom node CLI setup
+β”œβ”€β”€ contracts           
+β”‚   └── evoting             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
+β”œβ”€β”€ services
+β”‚   β”œβ”€β”€ dkg  
+β”‚   β”‚   └── pedersen        Implementation of the DKG service
+β”‚   └── shuffle   
+β”‚       └── neff            Implementation of the shuffle service
+└── web
+    β”œβ”€β”€ backend
+    β”‚   └── src             Sources of the web backend (express.js server)
+    └── frontend
+        └── src             Sources of the web frontend (react app)
+
+
+ +## πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’» Contributors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PeriodContributors(s)ActivitiesLinks
Spring 2021Students: Anas Ibrahim, Vincent Parodi
Supervisor: NoΓ©mien Kocher		Initial implementation of the smart contract and servicesReport
Spring 2021Student: Sarah Antille
Supervisor: NoΓ©mien Kocher		Initial implementation of the web frontend in reactReport
Fall 2021Students: Auguste Baum, Emilien Duc
Supervisor: NoΓ©mien Kocher		Adds a flexible election structure. Improves robustness and security. + Report, + Presentation +
Fall 2021Students: Ambroise Borbely
Supervisor: NoΓ©mien Kocher		Adds authentication and authorization mechanism on the frontend.Report
Spring 2022Students: Guanyu Zhang, Igowa Giovanni
Supervisor: NoΓ©mien Kocher
Assistant: Emilien Duc		Improves production-readiness: deploy a test pipeline and analyze the system's robustness. + Report, + Presentation +
Spring 2022Students: Badr Larhdir, Capucine Berger
Supervisor: NoΓ©mien Kocher		Major iteration over the frontend - design and functionalities: implements a flexible election form, nodes setup, and result page. + Report, + Presentation +
-# 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 ``` diff --git a/deb-package/README.md b/deb-package/README.md index 12a4f0f0f..ca78d477b 100644 --- a/deb-package/README.md +++ b/deb-package/README.md @@ -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 \ diff --git a/docs/assets/audit-black.png b/docs/assets/audit-black.png new file mode 100644 index 000000000..ed1a2648d Binary files /dev/null and b/docs/assets/audit-black.png differ diff --git a/docs/assets/audit-white.png b/docs/assets/audit-white.png new file mode 100644 index 000000000..3bcc6f266 Binary files /dev/null and b/docs/assets/audit-white.png differ diff --git a/docs/assets/cast-black.png b/docs/assets/cast-black.png new file mode 100644 index 000000000..2aed094f2 Binary files /dev/null and b/docs/assets/cast-black.png differ diff --git a/docs/assets/cast-white.png b/docs/assets/cast-white.png new file mode 100644 index 000000000..9c03dc76e Binary files /dev/null and b/docs/assets/cast-white.png differ diff --git a/docs/assets/component-global.puml b/docs/assets/component-global.puml index e1ead90e9..89f5592d2 100644 --- a/docs/assets/component-global.puml +++ b/docs/assets/component-global.puml @@ -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 diff --git a/docs/assets/encrypt-black.png b/docs/assets/encrypt-black.png new file mode 100644 index 000000000..8801e6081 Binary files /dev/null and b/docs/assets/encrypt-black.png differ diff --git a/docs/assets/encrypt-white.png b/docs/assets/encrypt-white.png new file mode 100644 index 000000000..449e4f8d8 Binary files /dev/null and b/docs/assets/encrypt-white.png differ diff --git a/docs/assets/privacy-black.png b/docs/assets/privacy-black.png new file mode 100644 index 000000000..4e21efa72 Binary files /dev/null and b/docs/assets/privacy-black.png differ diff --git a/docs/assets/privacy-white.png b/docs/assets/privacy-white.png new file mode 100644 index 000000000..f64e1fb52 Binary files /dev/null and b/docs/assets/privacy-white.png differ diff --git a/docs/assets/reveal-black.png b/docs/assets/reveal-black.png new file mode 100644 index 000000000..e2290c2e2 Binary files /dev/null and b/docs/assets/reveal-black.png differ diff --git a/docs/assets/reveal-white.png b/docs/assets/reveal-white.png new file mode 100644 index 000000000..59c3b03a0 Binary files /dev/null and b/docs/assets/reveal-white.png differ diff --git a/docs/assets/shuffle-black.png b/docs/assets/shuffle-black.png new file mode 100644 index 000000000..e27418680 Binary files /dev/null and b/docs/assets/shuffle-black.png differ diff --git a/docs/assets/shuffle-white.png b/docs/assets/shuffle-white.png new file mode 100644 index 000000000..d1e046f6f Binary files /dev/null and b/docs/assets/shuffle-white.png differ diff --git a/docs/assets/spof-black.png b/docs/assets/spof-black.png new file mode 100644 index 000000000..f58b50ccd Binary files /dev/null and b/docs/assets/spof-black.png differ diff --git a/docs/assets/spof-white.png b/docs/assets/spof-white.png new file mode 100644 index 000000000..10cc721dd Binary files /dev/null and b/docs/assets/spof-white.png differ