From 2383822d30f877a56a5b66e04a525ecf13e78253 Mon Sep 17 00:00:00 2001 From: David Florness Date: Mon, 15 Feb 2021 20:43:48 -0500 Subject: [PATCH] Update README --- README.md | 95 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 63 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index d13e21d..904e2b5 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,56 @@ # tallyard tallyard is an authenticated voting system that ensures voter privacy while -preventing double-voting. Voter privacy is achieved via the homomorphic secret -sharing system outlined +preventing double-voting. + +A voter can be any user on the [Matrix](https://matrix.org) network. All +ballots are tied to specific Matrix users (preventing double-voting), and said +users can only participate in elections where they are members of the room in +which the election was created. Thus, election participation can be limited to, +for instance, members of a club or citizens of a jurisdiction. + +Voter privacy is achieved by using the homomorphic secret sharing system +outlined [here](https://en.wikipedia.org/wiki/Homomorphic_secret_sharing#Example:_decentralized_voting_protocol) -and double-voting is prevented by a STARKs zero-knowledge proof as described -[here](https://vitalik.ca/general/2017/11/09/starks_part_1.html). Voters' -computers communicate with each other directly over a peer-to-peer network. -While there is a "master" node that decides what the candidates of the election -are, it does not have any privileges once voting begins. +to count the ballots in such a way that no individual user's ballot is revealed +to anyone, but the final, aggregate result of the election can still be +computed. In short, every voter helps count the ballots, but no individual +voter can know anyone's ballot but their own. + +STARKs zero-knowledge proofs, as described +[here](https://vitalik.ca/general/2017/11/09/starks_part_1.html) by Vitalik +Buterin, are used to ensure (with very high probability) that no individual +voter has submitted a fraudulent ballot. (Unfortunately, this zero-knowledge +proof part of tallyard has not been finished yet.) Have a look at the [presentation](https://gitlab.com/edwargix/tallyard/-/raw/master/doc/oresec-talk/tallyard.pdf) -I gave for my university's cybersecurity club for an overview of the -mathematics. +I gave for my former university's cybersecurity club for an overview of the +aforementioned cryptography. + +Because Matrix is an open, federated messaging protocol, it is quite possible +for individuals to participate completely anonymously since often nothing more +than a username and password is required to create a Matrix user account. This +will only be more true once [P2P +Matrix](https://matrix.org/blog/2020/06/02/introducing-p-2-p-matrix) becomes +more of a reality down the road. -The zero-knowledge implementation is not entirely finished. +# Work-in-progress -tallyard is very much a work-in-progress and is only useful for elections where -everyone is voting simultaneously, such as a club election, which it was -actually used for. +tallyard is very much work-in-progress software as it is being actively designed +and implemented, and is thus subject to change (though we will try to follow +[semantic versioning](https://semver.org) for releases, at least for protocol +changes). + +tallyard is also currently only useful for elections where everyone is voting +nearly simultaneously, and requires a somewhat cumbersome five-step process to +conduct an election to completion: + +1. the election is created +2. voters explicitly "join" the election +3. the election creator "starts" the election +4. voters (only those who partook in step 2) submit ballots +5. everyone helps to calculate the result # Installation @@ -39,47 +70,47 @@ $ yay -S tallyard-git ## From Source -Ensure you have the [Go](https://golang.org) programming language -installed. Then: +Ensure you have the [Go](https://golang.org) programming language installed. +Then: ```sh $ git clone https://gitlab.com/edwargix/tallyard $ cd tallyard $ make -$ # the tallyard binary is now at ./tallyard +$ ./tallyard ``` # Usage -Once every voter wishing to participate in the election has tallyard installed, -everyone should run it: +Every voter must have a Matrix account. Once everyone wishing to participate in +an election has tallyard installed, everyone should run it with ```sh $ tallyard ``` -One voter, henceforth called "the master", will then choose "Create Election", -enter the candidates of the election, and share the printed "election key" with -everyone else[^1]. Every voter who is not the master will instead select "Join -Election" and paste the "election key" provided by the master. Voting will -begin once the master hits the enter key. However, the master should only do so -once he has received confirmation of a connection from all of the other voters. +Everyone will be prompted to enter their Matrix credentials. + +Each voter should then select the room where the election will take place (or is +taking place)[^1]. One voter should select "Create Election" and enter the +election's candidates. Once the election has been created, all other voters +should see the election appear in their room UI where they will be able to +select the election, join, and vote (once the election's been started). -[^1]: preferably over a secure medium +[^1]: You cannot join rooms from within tallyard; use a more featureful Matrix + client like [Element](https://element.io) to do so. # Why Go? - concurrency -- [libp2p](https://libp2p.io) +- simplicity +- elegance +- [mautrix-go](https://github.com/tulir/mautrix-go) # Future Work -- Support authentication systems. First on the list is - [Matrix](https://matrix.org/) accounts. Those who used the old client written - in Racket will know that authentication used to be possible; the transition - just hasn't been made yet. -- [Matrix](https://matrix.org) bots for voting on topics in matrix chat rooms. -- Finish the zero-knowledge proof implementation. +- [Matrix](https://matrix.org) bots for periodically voting on topics in Matrix + rooms. # Stuck? Have suggestions or feedback? -- 2.38.4