readme.md
1CryptoBallot
2============
3
4[](https://travis-ci.org/cryptoballot/cryptoballot)
5[](https://scrutinizer-ci.com/g/cryptoballot/cryptoballot/build-status/master)
6[](https://goreportcard.com/report/github.com/cryptoballot/cryptoballot)
7[](https://coveralls.io/github/cryptoballot/cryptoballot?branch=master)
8[](https://godoc.org/github.com/cryptoballot/cryptoballot/cryptoballot)
9[](https://scrutinizer-ci.com/g/cryptoballot/cryptoballot/issues)
10
11Features
12--------
13 - All votes are anoymous with an option for the voter to mark their ballot as public.
14 - All voters can verify that their vote has been counted
15 - All voters can verify that all the votes have been tallied correctly
16 - All voters can verify that the total number of signed ballots matches the number of votes cast.
17 - Auditors with access to the Voters List can verify the identities of all voters who cast a ballot, but cannot match which ballot belongs to which voter.
18
19
20
21VoterList Server (Voter registry)
22---------------------------------
23 - Primarily composed of a voter database and a mechanism for voters to supply public key(s).
24 - Access to the VoterList should be limited to a verified list of Auditors who can verify the integrity of the VoterList database. Optionally the entire VoterList could be made public if so desired.
25 - VoterList should allow anyone to verify that a public-key is active and valid, but should not disclose the identity of the voter with that public key.
26 - Risks include:
27 - Account stuffing (server is hacked and additional user-accounts are inserted into the database). This can be mitigated by tying voter-database to another trusted ID database. For example, a driver's licence database. This risk is equally present in a paper-based voting system.
28
29
30
31BallotClerk Server (Ballot signing)
32----------------------------
33 - Each client, before submitting their ballot to the BallotBox must first have it signed by the BallotClerk.
34 - The ballot may be blinded before it is submitted, guaranteeing that the ballot is fully anonymous once it is cast
35 - Each client will create and sign a Signature Request with their public-key on file with the VoterList.
36 - The BallotClerk will verify the request and provide the voter with a signed ballot. The user will then unblind this ballot and submit it to the BallotBox.
37 - The BallotClerk publishes the full list of Signature Requests once an election is ended. This allows voters to verify that the total number of signed ballots matches the number of ballots tallied by the BalltoBox.
38
39
40POSTing a Signature Request takes the following form:
41```http
42POST /sign/<election-id> HTTP/1.1
43
44<election-id>
45
46<request-id>
47
48<voter-public-key>
49
50<unsigned-ballot-hash> (Could be blinded or unblinded)
51
52<voter-signature>
53```
54
55The server will respond with a Fufilled Signature Request, which takes the following form:
56
57```
58<signature-request>
59
60<ballot-signature>
61```
62
63`<election-id>` is the unique identifier for this election / decision.
64
65`<request-id>` is the unique identifier for this Signature Request. It is the (hex encoded) SHA-512 of the voter-public-key.
66
67`<voter-public-key>` is the voter's rsa public key for this vote. It is base64 encoded and contains no line breaks.
68
69`<unsigned-ballot-hash>` is the SHA512 hash of the ballot to be signed. It is encoded in hex. Generally it is blinded, but if a voter does not desire anonimity, they may choose just to use the raw hex-encoded SHA512 of an unblinded ballot. See below under "BallotBox Server" for the ballot specification.
70
71`<voter-signature>` is the base64 encoded signature of the entire body up to this point (excluding headers and the linebreak immidiately preceding the signature).
72
73
74The BallotClerk Server also exposes the following service points
75
76`GET /sigs/<election-id>` provides the full list of all Fufilled Signature Requests for the election. This service point is only available to the public after the election is over.
77
78`GET /sigs/<election-id>/<request-id>` provides access to a single Fufilled Signature Request. A user may use this to regain a lost ballot-signature. They will have to attach a X-CryptoBallot-Signature header which signs the string `GET /sigs/<election-id>/<request-id>` with their public key.
79
80
81
82BallotBox Server
83----------------
84 - Recives votes signed with BallotClerk key and checks the validity of the submitted ballot.
85 - All ballots are identified using a randomly user generated ID and not two ballots may share this ID. This is to prevent signed ballot copying / stuffing.
86 - All votes are an ordered list of git urls and commits (/path/to/repo:commit-hash)
87 - Any client may request to see their "ballot on file".
88 - Existing ballot may be updated at any time (before counting / tallying takes place). This is accomplished by getting a new ballot signed that includes an revokation of the previous ballot.
89 - All ballots are "sealed" until the votes are ready to be counted. Some clients may choose to make their vote "public" by tagging it as such.
90 - When ballots are ready to be counted all votes are "unsealed" in their entirety and published. Any 3rd party may then count the votes and tally the results.
91 - Risks include:
92 - Voter identity discovery via ip address if either ballot-box server or ssl/tls compromise. A tor hidden service should be provided in order to mitigate this attack.
93 - Voter identity discovery though a timing attack if the user immidiately submits their ballot after having it signed by the Ballot Clerk. To mitigate this attack the voter should randomly stagger this interval.
94
95
96Casting a ballot takes an HTTP request of the following form
97
98```http
99PUT /vote/<election-id>/<ballot-id> HTTP/1.1
100
101<election-id>
102
103<ballot-id>
104
105<vote>
106
107<tags>
108
109<ballot-signature>
110```
111
112`<election-id>` is the unique identifier for this election / decision.
113
114`<ballot-id>` is the unqiue ID of this ballot. It is the (hex-encoded) SHA512 hash of randomly generated bits. This is to prevent signed ballot copying / stuffing. If two ballots are discovered with the same ballot-id, they are invalid.
115
116`<vote>` is an ordered, line-seperated list of git addresses and commit hashes that represent the vote
117
118`<tags>` is additional information a voter may wish to attach to the vote in the format of `key="value"`. Each key-value pair goes on a new line. Standardization around commonly understood keys forthcoming. Examples might include the voter's name if they wish to publically forclose their vote.
119
120`<ballot-signature>` is the base64 encoded BallotClerk signature of the ballot. This is the entire body up to this point (excluding headers and the linebreak immidiately preceding the signature). This signature is provided by the BallotClerk Server in a Fufilled Signature Request.
121
122
123
124User-interface / client software
125--------------------------------
126 - Multiple versions may be built by 3rd parties and others.
127 - May be server based or a local binary application.
128 - Reference implementation here will be an ember.js app.
129
130
131
132Verifying an election
133---------------------
134The following steps can be taken to do an end-to-end verification of an election
135 1. Retrieve the full ballot box for an election from the Ballot Box server and verify the SHA512 signature of the result set with other clients.
136 2. Retrieve the BallotClerk's public key and verify that all ballots have been properly signed by the BallotClerk.
137 3. Verify that no two ballots share the same ID.
138 4. Tally the ballots and verify that other clients have tallied the same result.
139 5. Retrieve the full set of Fufilled Signature Requests from the Ballot Clerk and verify the SHA512 signature of the set with other clients.
140 6. Verify the the number of ballots is not more than the number of Fufilled Signature Requests.
141 7. Verify the voter signature on all Signature Requests against the voters' public keys.
142 8. Contact the VoterList server and verify that all public keys belong to verified voters.
143
144
145
146Shortcomings
147------------
1481. Cryptoballot provides no guarantees of endpoint security of the machine or software being used to cast the vote.
1492. Cryptoballot does not provide any protection against voter coersion. Since cryptoballot allows voters to view their vote after it has been counted in order to verify the veracity of the election, this opens the door to private coersion of votes or vote-trading. This problem is not unique to Cryptoballot and is endemic to any electronic voting system that allows voting on private devices in a private setting.
150
151
152
153Generating Crypto Keys
154----------------------
155```bash
156#Generate private-key. This is your private key. Keep it secret, keep it safe.
157openssl genrsa -out private.key 1024
158
159#Generate public-key der file
160openssl rsa -in private.key -out public.der -outform DER -pubout
161
162#Gerenate base64 encoded public key - this is the <public-key> you will pass to the BallotClerk server for ballot signing
163base64 public.der -w0 > public.der.base64
164
165#Generate SHA512 request-id from public key. This is your <request-id> for creating a Signature Request
166sha512sum public.der.base64 | awk '{printf $1}' > public.der.base64.sha512
167```
168
169Paper Voting Equivalent to CryptoBallot
170---------------------------------------
171
172|Paper Voting Equivalent | CryptoBallot
173|---------------------------------------------------------------------|-----------------------------------------------------------------------------
174| | User generates private / public RSA keypair
175|Voters registers to vote and is put on voters list | User registers to vote and is put on voters list along with their public key
176|*Election Time!* | *Election Time!*
177|Voter receives blank ballot by mail with unique ID stamped in corner | Voter randomly generates unique ID for ballot
178|Voter writes down vote on their ballot at home | Voter creates digital ballot file on personal device using the generated ID
179|Voter puts ballot in an envelope along with carbon paper | Voter creates a blinded copy of their ballot using RSA blinding
180|Voter presents ID to voting-station clerk who verifies identity | Voter asserts identity to Ballot-Clerk server using crypto-signature
181|Voting-station clerk has voter sign receipt. Clerk keeps receipt. | Ballot-Clerk server stores copy of the voter's signature-request as a receipt
182|Voting-station clerk signs outside of envelope | Ballot-Clerk server blind-signs voter's blinded-ballot
183|Voter removes ballot from envelope and discards carbon paper | Voter unblinds digital ballot
184|Voter goes to private voting booth | Voter waits a random amount of time and enables Tor
185|Voter places ballot in ballot-box | Voter submits ballot to Ballot-Box server (which checks ballot-clerk signature on ballot)
186|*Counting time!* | *Counting time!*
187|Clerk's signature is published | Ballot-Clerk's public-key is published
188|All ballots are poured out on big counting table | All ballots are published in the open
189|All ballots are checked for the clerk's carbon-copied signature | All ballots are cryptographically verified against Ballot-Clerk server's public key / signature
190|All ballots are checked to make sure they have a unique-id | All ballots are checked to make sure they have a unique-id
191|Count the ballot and the receipts, make sure receipts >= ballots | Count the ballot and the signature-request receipts, make sure receipts >= ballots
192|Auditors verify receipts are properly signed by a registered voter | Auditors verify signature-request receipts are properly signed by a registered voter
193|Tally the results of the election! | Tally the results of the election!
194
195Database Setup
196--------------
197The system can build the database schema automatically. Run either of the following:
198
199 ballotbox --set-up-db
200 electionclerk --set-up-db
201
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}