README
¶
tallyard
tallyard is an authenticated voting system that ensures voter privacy while preventing double-voting.
A voter can be any user on the Matrix 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 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.
Jens Groth's zk-SNARK, as described here, is used to ensure (with very high probability) that a given voter's ballot is not fraudulent, while revealing zero information about the ballot itself.
Have a look at the presentation I gave for my former university's cybersecurity club for an overview of the aforementioned cryptography. Note: some of the info in the slides is very out-of-date.
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 becomes more of a reality down the road.
Work-in-progress
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 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:
- the election is created
- voters explicitly "join" the election
- the election creator "starts" the election
- voters (only those who partook in step 2) submit ballots
- everyone helps to calculate the result
Installation
Arch Linux
Latest Stable Version
$ yay -S tallyard
HEAD of master
$ yay -S tallyard-git
From Source
Ensure you have golang and the olm library (plus headers) installed. Then:
$ wget -O tallyard-v0.4.1.tar.gz https://git.hnitbjorg.xyz/~edwargix/tallyard/archive/v0.4.1.tar.gz
$ tar xzf tallyard-v0.4.1.tar.gz
$ cd tallyard-v0.4.1
$ make
$ ./tallyard
Usage
Every voter must have a Matrix account. Once everyone wishing to participate in an election has tallyard installed, everyone should run it with
$ tallyard
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]: You cannot join rooms from within tallyard; use a more featureful Matrix client like Element to do so.
Contributing
Contributions are welcome; thank you! Please send any patches you come up with to ~edwargix/tallyard-dev@lists.hnitbjorg.xyz.
Please send any feature requests / issues to ~edwargix/tallyard@todo.hnitbjorg.xyz or to our Matrix room.
Both of these lists are behind a greylisting SMTP server, so it'll take a few minutes for your first couple of messages to get through.
You should consider everything you submit to these lists public; if you want to contribute privately, please reach out to me directly with email and PGP or via a private 1-on-1 Matrix room with me.
If you've never sent patches with email before, I highly recommend git-send-email.io.
Why Go?
- concurrency
- simplicity
- elegance
- mautrix-go
Future Work
See todo.hnitbjorg.xyz/~edwargix/tallyard.
Stuck? Have suggestions or feedback?
Join our Matrix room to participate in the discussion.
If you're unfamiliar with Matrix, you can learn about it and sign up for an account here.
Origin of the name
"Tillyard" is the last name of the author of the The Elizabethan World Picture, which I read in my phenomenal Shakespeare class. Also, the voting system works by keeping a "tally" of votes in a secretive manner. These two notions together yield "tallyard".
"tallyard" is written in lowercase letters to follow the convention of UNIX executable names being all lowercase.
Documentation
Source Files
Directories