Votebox

Usage

Compiling and running the supervisor is easily accomplished by building an artifact. In The InteliJ IDEA IDE go to Build -> Build Artifacts... -> Votebox

The jar will then be compiled and automatically pull in the /path/to/starvote/STAR-Vote/out/Votebox as Votebox.jar

With the jar built, you can simply cd to the jar directory and :

$ java -jar Votebox.jar [serial number] ###Summary and Module Definition

In this document we define specification for the user interface module of the VoteBox voting machine. By "user interface," we mean the module which defines all behaviors that relate to a single voter's interaction with the machine. This notably includes those behaviors which produce the visual software controls which a voter may interact with in order to record his preference in an election, as well as the behavior that creates immutable cast ballots that other parts of the system use. The user interface module keeps no state between voting sessions (where a single voting session is defined as the interval of time where a single voter uses the software to record his preferences in an election). In fact, a different instance of this module is created for every unique voter, and, throughout the software's run time, at most, one instance of this module exists at any single point in time.

###Aside It is important to note that in the domain of human factors testing, the only relevant module is this one. As a consequence of this, all human factors research related design goals are specified here. Because the goals that we have specified for human factors research are, in some cases, necessarily in conflict with those that we have specified for security research, the parts of this document that are explicitly stated as only beneficial to human factors research can be assumed to be left out of any version which we propose should be placed under the scrutiny of an expert in computer security. Because the user interface module (which we will abbreviate UI) defines the parts of the software which directly affect the voter's experience, it is useful (towards the goal of a definition for this module) to give a concise description of what a voter should expect when he interacts with our machine. The voter will be able to use hardware controls to select candidates, navigate the ballot, and cast a finished ballot. Our design allows for flexibility in which hardware controls are used in an implementation. (For example, touch screens, scroll wheels, and arrow keys are reasonable solutions.) While at the machine, the voter will be presented with a series of screens. First, he will navigate through screens which will explain the election. Next, he will be presented with a series of races in which he can vote. After he votes, he will be presented with a summary screen which will allow him to confirm that the machine has accurately recorded his preferences in the races in which he can vote. Finally, the user will confirm his vote, the ballot will be cast, and the machine will appear to "restart" (as the UI module will be thrown away and recreated for the next voter).

The UI will be independently constructed by the [:VoteBoxBackend:Back End] module) for each individual voter who comes into contact with the machine, and will only exist in memory while the voter is interacting with the machine. When the voter declares his intent to cast his ballot, the modules we define here will convey the ballot state to another module in a form that is immutable. The driver component will then release all references to the mutable ballot.

THIS NEEDS TO BE RETHOUGHT AND POSSIBLY PLACED ELSEWHERE The modules we define here will interact as follows (ADD A DIAGRAM). The hardware with which the voter will interact will trigger events in the view. The view's job is simply to display screens to the voter and accept the voter's input. This view will have been constructed by a view manager, whose job is to control all the changes in the view which happen in response to user interface events. The view manager will respond to events by asking the view to change what is being displayed on the screen. A new view manager (and corresponding view) is constructed by the user interface driver every time a new vote session is started. When the voter communicates his intent to cast his ballot, the view manager will ask the ballot to create an immutable representation of itself, which it will hand to the user interface driver. The user interface driver will then release its reference to the view manager, and pass the cast ballot to the vote recording module.

Ballot

Here we define what is referred to throughout this document as a ballot. Ballot definition, in general, is relevant to the UI definition in that each form defined here is either interpreted, modified, or created by the UI.

In defining the user interface, this document includes references to many (different) structural definitions for what we refer to, conceptually, as a ballot. In this section we hope remedy confusion by giving a concrete definition for each ballot type, as well as by offering some explanation as to why there are different definitions for what a ballot is and when each one is appropriate.

Here, it helps to use the older, punch card election system (specifically, the ballots that it uses) as an appropriate explanatory analogue, as our ballots are conceptually analogous. One form of it is created before an election by some sort of election administrator. This might be appropriately called a definition of ballot content. Content, here, includes a definition of everything that a voter can see (including explanatory information about races and the candidates' actual names) as well as a definition for the method which the voter can use to communicate his preference in each race. From this original, a copy is made for and modified by each voter (when said voter records his preferences). This, of course, happens on election day. Once a voter is finished modifying his personal copy of the ballot, he places it in an environment which (supposedly) makes it safe from further modification. These three forms which a ballot takes represent three different and distinct definitions for "ballot" which we will use.

Ballot Content

Each of our defined ballot forms claim to represent, conceptually, the same thing. For this reason, we have defined and made use of certain terminology in order to accurately refer to different components of the ballot.

Ballot Content Definition A ballot can have cards properties A card has a unique ID, and can also have card elements properties A card element has a unique ID and can also have properties A ballot is divided into many cards, each of which is divided into many card elements. The most common use of this hierarchy of subdivision is the case where each race in an election is represented with a card, while each candidate in each race is represented with a card element. Our purpose in being generic with terminology is to claim that these subdivisions are generic, even though necessarily used to represent certain notions. More specifically, in our design, races are necessarily represented as cards; candidates, as elements. However, cards and card elements are also used to represent other things. Card elements can be used, for example, to represent explanatory bits on the ballot that cannot be "voted" for, such as a referendum description or a race title. Cards can be used to represent a section in which no selections are made at all, but only consist of explanatory bits, such as a set of instructions. Both cards and card elements are identified by

Properties help to more specifically define elements in the ballot. A property, as we have defined it, is a ballot configuration parameter that an election administrator has the power to set. The voting machine will check these properties as part of the process that it uses to determine what to do with each card and card element. For example, an election administrator can choose to place a specific card element as belonging to a particular political party, or define that on a specific card, a given number of elements can be selected simultaneously.

Ballot Configuration

We use the term ballot configuration to mean the ballot that is created by an election administrator before an election. Because this version of the ballot will need to be persisted on some sort of storage until the time of the election, and then copied to each machine once for every participating, registered voter, the ballot configuration can be thought of as a set of files. These files are then parsed by the voting machine at run time in order to make a "copy" of the ballot which the voter can modify and cast.

Ballot XML File

The ballot's content is defined in an XML file which conforms to the format we define here.

The file makes use of the following five tags: , , , SelectableCardElement, and .

The Ballot tag, as would be expected, is used to define a ballot. The first tag encountered in the file must be a Ballot tag, and no other tag in the file is allowed to be. All other tags must be defined inside the ballot tag. It has no attributes.

CardElement, SelectableCardElement, and Card may be used inside the top-level Ballot tag to define the existence of card elements and cards. The SelectableCardElement tag is used to denote card elements that can be chosen by the voter. (For example, in the case where a card element represents a candidate in a rate, this candidate would be defined in the XML as a SelectableCardElement.) The Card tag can only be used inside the top-level Ballot tag, and both CardElement and SelectableCardElement can only be used inside a Card tag. Each

Syntax

Where T is one of {Card, CardElement, SelectableCardElement} <T uid="aUid"> ... </T> The Property tag is used to express the notion of properties referenced above. Properties can be thought of as typed entries in a dictionary. Each property that is defined can have only one value. For a complete list of supported keys and values, please see the JavaDoc. A Property tag can belong to any other tag in the definition, not including other Property tags, and including the top-level Ballot tag. Each property definition and its corresponding value will follow this syntax: <property name="key" type="string" value="value"></property>

To define (in the configuration file) a Card as belonging to a Ballot, place a tag inside the tag. A card must define an int property named "uid." (UIDs, of course, must be unique across any given ballot. This is enforced at parse-time.)

To define (in the configuration file) a CardElement as belonging to a Card, place a tag inside the tag of its parent. A card element must define both an int property named "uid," and a boolean property named selectable. The uid must be unique across the ballot. For card elements which are intended to be selectable (such as card elements which will hold a candidate's name), set the selectable property to true. Otherwise, set it to false.

If a certain trait is required of a ballot, card, or a card element, then the definition of that trait must be specified in the attributes of the either the card or card element. If a trait is optional it can be defined in a property tag. For example, "MaxImageSize" is an optional trait, defined across the whole ballot, that defines the number of images associated with every card element (indexed from zero onward). Its default state (if not initialized) is zero, corresponding to one element per card element. (TBD: what other traits are optional for what type of ballots?)

' <!-- This is an informational card --!> <!-- This is a race card --!> <!-- uids do not have to be ascending or descending, only unique --!> '

##Ballot class

The Ballot class represents the runtime version of the ballot. This means that a Ballot contains both Properties (see here) and Cards. The Cards will be stored in memory as a List.

###State The Ballot contains both a Properties reference and a List. ###Construction Construction is handled exclusively by the BallotParser. The constructor can only be accessed from the scope of the user interface assembly. The BallotParser is the only user interface component which constructs new Ballots that can be used by other parts of the user interface system. Ballots are not accessible (at all) from outside the user interface system. ###Methods Ballot defines the following methods: public CastBallot makeCastBallot() Generates a CastBallot that represents this ballot. The CastBallot cannot be modified.

##Properties

After a ballot's properties are parsed from the ballot configuration file, they are stored in the ballot's state. They are stored in an instance of the Properties class. The Properties class allows for the ballot to have unique traits and be customizable by storing parsed properties of the ballot.

###State Properties has a Dictionary<string,string> as state. In addition, all the keys used in the dictionary will be declared as final constants. This is done to reduce the number of typos and make for easier auditing/verification. ###Construction Properties will have only one, default, initializing constructor. ###Methods Properties defines the following methods: internal void add(string key, string value) This method allows for the addition of a new key and value to the dictionary. ###public string getString(string key) Get the string value mapped to a given key. If this value has been declared to not exist as type string, this method will throw an exception. ###public int getInt(string key) Get the int value mapped to a given key. If this value has been declared to not exist as type int, this method will throw an exception. ###public int getDouble(string key) Get the double value mapped to a given key. If this value has been declared to not exist as type double, this method will throw an exception. ###public int getBoolean(string key) Get the boolean value mapped to a given key. If this value has been declared to not exist as type boolean, this method will throw an exception. ###public List getList() This method returns a List of all the property mappings in the Dictionary.