Votebox

Written by: Kyle Derr, Martin Nikoltchev #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 --!> '

#Cards

The entire ballot is rendered before runtime. The ballot is divided into Cards. Cards are divided into CardElements. Each CardElement is visually represented by a single, pre-rendered image which is included in the ballot's media bundle. Conceptually, a ballot can be divided into informational pieces and races (with each race having multiple candidates); here we represent races with Cards, candidates with CardElements.

It then follows that Cards either communicate electoral races or informational pieces intended to be read by the voter. We mandate that informative Cards will not carry any races on them, and race Cards will at most contain one race. (The view may, of course, decide to display more than once Card and hence more than one race at a time.) Each Card and CardElement will have its own unique (across the whole ballot and, by extension, the whole election) ID.

##Card class

represent either a nugget of general information about the election or an individual race in which the voter is allowed to report his preferred outcome. Informational Cards contain only one element, while race Cards contain many elements: one element that describes the race, and one selectable element for each candidate.

##SelectableCardElement class

SelectableCardElement is a class that extends CardElement, and conceptually represents an item in a race which can be both selected (voted for) and focused on. It follows, then, that a SelectableCardElement can exist in four abstract states: default, selected, focused, and focused-selected. The default state is the state that should appear the first time SelectableCardElement is displayed. A selected SelectableCardElement is one which has been chosen by the voter as preferred. A focused SelectableCardElement is an element that the voter has navigated to specifically in order to perform some action (like selecting). A focused-selected SelectableCardElement is one that has been selected and focused at the same time. Support for focusing is not needed on touch-screen systems. There will be an image in the media bundle which can display the SelectableCardElement in each of these four states.

##The media bundle

For the purpose of this documentation, a media bundle is a set of images and audio files, each of which can communicate to the voter both a CardElement's information and (possible) state.

Image files on disk should be in PNG format and should be named by the UID which they claim to represent. An image who is rendered to represent the CardElement with UID 60001 would be named 60001.png. Images also must be pre-rendered to reflect different states which SelectableCardElements can be in. An image who is rendered to represent the CardElement with UID 60001 in the focused state would be named 60001_focused.png on disk.

##BallotParser class

BallotParser class is to act as a factory for blank ballots. We consider a blank ballot to be a ballot that has all SelectableCardElement}(s) in \textbf{default state. To create blank ballots, the parser will read ballot configuration information from disk, and use it as a guide for how the ballot structure should be created.

##Cast Ballots

A cast ballot is a ballot that has been edited by the voter and is considered to be the voter's final preference. Here, we define that our cast ballot structure has the property of being immutable: once it is created it cannot be changed. A CastBallot can only be created by the makeCastBallot() method in Ballot. The ensures that there only is one source for valid CastBallots--no other part of the system can create CastBallots. A CastBallot will carry some basic information that will allow for it to be counted. This includes a list of races and a list of selection(s) in each of those races.

#User Interface

In defining our user interface, we necessarily abstract the view's event-response behavior (event handlers) from the behavior which actually displays images on the screen. We do this so our user interface module has a certain degree of portability. If, later, we decide to change the API that is used to actually display images on the screen, we would only need to change our display implementation. The event-response behaviors are defined such that they communicate with a view interface. It follows from this, then, that here we should define this interface, our first class that implements it, and our event-response behavior.

##IDrawable interface

Any item that is to be drawn on to the display must implement the this interface.

##IView interface

A view must conform to this interface. The view's job is to display ballot information on the screen and also, to capture user input. Therefore, a view must define how to display an IDrawable (both the smallest independently renderable ballot object and the object who accepts all user interface events) on the screen. In order for the ViewManager (see here) to make layout decisions (configure the display however it likes), it needs to have access to three methods in every implemented view.

##MDXView class

Our view will use the Managed Direct3D library to project IDrawable objects onto the screen. Each IDrawable will be represented as a Direct3D two-dimensional sprite which is textured by the image accessed by IDrawable.getImage(...).

In this first iteration of development, we are using the Managed DirectX 9.0 API (version 1.0.2902.0) to render images onto a .NET Windows Form. At present time, we do not have access to the XBox 360 SDK. We can only tentatively speculate that the beta version of Managed DirectX 9.0 version 2.0.0.0 is somewhat like the Managed DirectX API for XBox 360. In addition, we are completely without knowledge of the input device API on an XBox 360. These two facts, coupled with the fact that documentation for version 2.0.0.0 of the Managed DirectX API is harshly lacking in substance, has led us to choose version 1.0.2902.0 for our preliminary build. If this software eventually does explicitly target the XBox 360, both aforementioned components of the MDXView class (both the reliance on Windows Forms as an API for user input and the reliance on version 1.0.2902.0 of the Managed DirectX API) will need to be modified. We assume, however, that this modification will be fairly painless, given the fact that our familiarity with the DirectX API, in general, is evidenced by our use of version 1.0.2902.0.

##ViewManager class

The ViewManager's job is twofold. First, it's job is to command the view to display ballot information in the form of individual CardElements. Second, it defines how the view should respond to events.

##Driver

The driver is the only part of the user interface module that is voter independent. It will initialize the (other) necessary components in the user interface every time a new voter gains access to a machine. The driver is implemented in the Driver class (see here) and will follow the steps identified here.

• Loading the ballot: The Driver will instantiate a new BallotParser so that it may get a Ballot object with which it can communicate ballot information to the voter and record his preference. It will keep a reference to this Ballot for the duration of the voter's session.
• Launch a ViewManager: The Driver will construct a new ViewManager and hand it the Ballot object which it created in the previous step. (This ViewManager, of course, is responsible for constructing the view.)
• Handle the voter's intent to cast a ballot: When the voter decides that he is done modifying his ballot, he will communicate his intent to cast to an IView, who will notify the ViewManager, who will notify the Driver. The Driver will then ask the voter's Ballot to construct a CastBallot representation of itself. The Driver will then pass this immutable ballot structure to the capture interface, which manages the storage and recording of the ballot.
• Reset: After the ballot has been cast, the Driver will dispose of all (other) user interface structures by releasing its reference to the Ballot, the BallotParser, and the ViewManager. The machine then waits to be initialized by an administrator before it will enter another vote session.