Maemo.org team/How Elections Work

m (Voting Process: typo)
m (Voting Process: typo)
Line 26: Line 26:
The entire voting process is state driven.  When a user chooses an election and logs in, the system validates the token to allow them into the voting interface.  This is a "courtesy validation" to allow the user to know that the token is still valid.  Nothing is altered by this step.
The entire voting process is state driven.  When a user chooses an election and logs in, the system validates the token to allow them into the voting interface.  This is a "courtesy validation" to allow the user to know that the token is still valid.  Nothing is altered by this step.
-
The list of choices is presented to the user, and stored in a javascript applet that allows the voter to chose as many options as they like, in the order they like.  When the voter is happy with their choice(s), they submit the choices for validation and confirmation.  The vote selection is validated, displayed to the voter to confirm that they system got their choice correct, and the user is asked to again submit the vote for final processing.
+
The list of choices is presented to the user, and stored in a javascript applet that allows the voter to chose as many options as they like, in the order they like.  When the voter is happy with their choice(s), they submit the choices for validation and confirmation.  The vote selection is validated, displayed to the voter to confirm that the system got their choice correct, and the user is asked to again submit the vote for final processing.
The next step is the most complex and critical.  Once the vote has been submitted, several things happen all in one single step:
The next step is the most complex and critical.  Once the vote has been submitted, several things happen all in one single step:

Revision as of 20:46, 1 May 2013

This page details the current voting system and how it works. It is presented as a means of offering transparency into how voting is handled and how the current system provides both anonymity and verifiability in community elections and referendums.

Contents

Overview

The voting system provides users with a way to select an ordered list of one or more options from a list of options. The votes can then be used by simply selecting the first choice (often referendums with 2 choices use this method), or by using a run-off or single transferable voting method.

The current voting system is broken into several steps, often these steps are not visible to the voter, or are taken as a given. To ease the process, we will follow the "life" of a single vote, from the creation of the election to the final results.


Elections

Elections are created and stored in the database with several vital fields about that election. Included in that list are the start and stop times, the title of the election, the candidates for the election, and the number of "winners" there will be for said election. The contents of these tables is generally viewable in one form or another in the interface for voters.

Electorate

The system also contains a list of users eligible to vote in any election. That list generally gets updated from the main maemo.org list before elections are started. It is difficult (but not impossible) to update or fix this list after elections have started. For that reason it is asked that voters check their account settings and setup any linkages needed at least a few weeks before elections start.

Voting Tokens

When an election is setup and ready to be used, an administrator instructs the system to create and mail tokens for the electorate. A script in the system then generates a random voting token for every member of the electorate, and mails that token to each user. The voting token, used as a password for the voting login screen, is valid for one vote in the election for a given person. Administrators never see these tokens (aside from any token they may get as a voter).

The tokens are stored in a separate table, with a numeric pointer to the user who it belongs to. Storing them this way, in separate tables, makes it harder for an administrator to "accidentally" see a user's e-mail and their token together if they need to look at the database for any reason. The odds of anyone guessing a token is also quite slim. To login to the voting interface, one needs to know both the voting token and the e-mail address of the user involved, which would be hard for anyone not having access to said e-mail address.

Voting Process

The entire voting process is state driven. When a user chooses an election and logs in, the system validates the token to allow them into the voting interface. This is a "courtesy validation" to allow the user to know that the token is still valid. Nothing is altered by this step.

The list of choices is presented to the user, and stored in a javascript applet that allows the voter to chose as many options as they like, in the order they like. When the voter is happy with their choice(s), they submit the choices for validation and confirmation. The vote selection is validated, displayed to the voter to confirm that the system got their choice correct, and the user is asked to again submit the vote for final processing.

The next step is the most complex and critical. Once the vote has been submitted, several things happen all in one single step:

  1. A random vote validation string is created for this vote.
  2. The vote is prepared for entry into the list of votes.
  3. The system atomically (as one step):
    1. Adds the vote to the list of votes
    2. Validates that the vote token is valid
    3. Deletes the valid vote token

At this stage, one of two things happens:

  • If an error occurs, all sub-steps are undone, leaving a valid vote token, and an error is reported to the voter.
  • If all works as expected, the random vote validation string is presented to the voter.

The first step generates a random validation string for your vote. When the vote is stored in the vote table, that is the *only* reference as to "who" cast this vote. Being that it's random, the only way one can know it is by seeing it on their screen, having just submitted the vote. This is important because it allows each user to validate the public ballot later by looking up their unique entry to verify their vote was counted as it was cast.

The third step guarantees that a voter always has either a vote token, or has a vote cast with a random validation string. This prevents multiple votes per voter, and prevents technical problems from leaving a voter stranded without a vote. For this reason, at any time up to the point one hits the "submit vote" button on the validation page, one may close their browser, or hit back, to change their choices.

Post Election Ballot Validation

Once the vote has closed, the ballot of all votes cast is publicly viewable (and downloadable) by everyone. The list includes the votes cast, including the order of the choices for multi-choice votes, and the random validation strings for each vote. Since each voter knows his or her voting string, they can validate their vote is correct. They can also count the votes, and validate that the results of the election are correct. But since only one random validation string is know per voter, voters can not determine who voted for which candidates in the election. Since there are no links to the original owner or starting token in the final voting table, there's also no way for an adminstrator (or anyone with database access) to determine who voted either.

Technical Details

This area is for a more technical look at how things work, and may be less interesting for the general voter.

Source Code

For those interested, the voting code is public domain and can be reviewed. At this point, the entire voting system consists of PHP code, a small piece of javascript that runs in the browser, and a perl script that handles e-mail delivery. Since the addition of the admin interface, even the administration functions are now in PHP.

Database Setup

The database schema for the voting database is also checked in as an SQL script that can be used to create all tables needed for the scripts to function. Any updates to tables should be included in this schema.

Individual Tables

There are several tables in the election interface. Below is a brief description of each, as they exist at the time of writing this wiki page.

Table Name Description
admin_users This table contains the information needed to validate users of the administration interface.
elections This contains a list of all elections, past, present, and future.
election_anon_tokens This contains a list of all validation strings ever made, and indicates which election the token was made for, but not which voter.
election_choices This contains the choices for all elections, from Yes/No to candidates for elections.
election_results This contains html blobs that are shown as official election results.
election_tmp_tokens This contains the list of all tokens for all elections. Each token knows which user and election it belongs to (via numeric index).
election_votes This contains the actual votes for an election. The only references here are to election_anon_tokens, to indicate which votes go to which verification string.
electorate This contains the list of all eligible voters for all elections.
midgard_users This is a temporary table, imported from Midgard and/or the garage to allow scripts to update the electorate in an easier fashion.
outbound_email This system handles queuing and batching mail to prevent us from looking like spammers.