Merge pull request #160 from dedis/documentation-update

Updates documentation

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/#/).
+<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:
+
+**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:
+
+<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,
+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
 ```

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 \

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