GNU project  -  FREE project  -  Savannah @ GNU Free Software Foundation
The FREE project
home | users | developers | writings | download | connections


On this page

Introduction
First Steps
Preparing the Databases
Automated Import
FInishing Off


In this section

Section Index
Getting Started
Running Elections




thanks to:
Swing Digital
 
Getting Started - Intro

GETTING STARTED

Phew! You've just downloaded all the stuff: a Java Compiler and GNU.FREE. Thanks for going to the trouble.

Firstly set up the Java compiler, it should have full instructions included with it. Then uncompress the GNU.FREE archive, being sure that it unpacks into all the right directories.

The correct directory structure for GNU.FREE is:

Free-1.x.x
|
|-Free
   +-AWT
   +-DBPool
   +-util
|-FreeClient
|-ERServer
|-FreeTest
|-Docs
|

They may be some extra directories, but these are the key ones. Make sure you read README and INSTALL before going any further.

Done? Good, now let's do the fun stuff. We're going to start rooting around in the code of GNU.FREE. You'll need a good text editor, such as Programmer's File Editor (Windows) or BBEdit (MacOS) or Emacs (UNIX).

First steps in the GNU.FREE code base

Prior to version 1.4 of GNU.FREE this documented how to setup GNU.FREE by hand. However you now HAVE to use the FreeInstall program to create a secure installation. If you are using an older version of GNU.FREE then either upgrade or refer to the older version of this document in the Docs directory of your GNU.FREE installation. This file remains as a guide to the structure of the software and important steps you need to take once you have run FreeInstall

There are three packages, which for security reasons, are totally independent of each other (though in fact some of their code is nearly identical). Let's take a look at what they do:

Free is the package that contains the program at the very heart of the GNU.FREE system, RTServer (short for Regional or Totaller Server) this receives the votes and adds them up for a final result. This is the biggest and most complex program in GNU.FREE.

ERServer contains the ERServer (short for Electoral Roll Server) software which is the simplest program in GNU.FREE. It receives requests to authenticate voters and also registers that you have cast your vote.

FreeClient holds the code for the FreeClient which is the software the voter actually uses.

Additionally there are two packages of code common to the three mentioned above:

Free.util stores common files for the GNU.FREE system.
Free.awt holds custom AWT files for the GNU.FREE interface.

Furthermore there is a package that holds code common to RTServer and ERServer:

Free.DBPool this contains files for database connection pooling/caching.

[ There are two other packages we include but aren't strictly part of the GNU.FREE system as they don't have anything to do with running an election:

FreeTest is where the GNU.FREE Testing Suite (FTS) is kept. You only need to use this if you plan to help develop GNU.FREE.
FreeInstall is a graphical system for changing the GNU.FREE code without you needing to get your hands dirty. ]

The code is heavily commented, so open it up and take a look if you're interested - this file isn't going to repeat what's already there.

Once you've finished making changes compile all the programs (see INSTALL for more on this)... and relax. You're done! Run the programs, setup the databases (see below) then run FreeClient on any computer with Java and a connection to the Internet and you'll be able to vote!

Preparing the databases

When you run RTServer or ERServer they will automatically prepare and create the Hypersonic SQL databases. Before you can RTServer in regional mode you need to create a rtserver.keys file. But to do this you will need to populate ERServer's database with Electoral Roll information so that voters can be authorised. Here's the default way to do this in GNU.FREE - to use a different authorisation system you'll need to edit the code, so let's keep things simple:

The data is stored in a table called Roll which consists of 4 columns created with the following SQL statement:

CREATE TABLE Roll (name VARCHAR(255), code VARCHAR(255), pword VARCHAR(255), voted CHAR(1))

  • name is the name of the voter.
  • code is a unique code for this ballot only (I suggest it contains numbers and letters).
  • pword is the voter's password.
  • voted stores whether the person has voted. Should be initialised to F, GNU.FREE will set it to T when the person votes successfully.

Since version 1.5 all information inserted into databases by the software is encypted. This makes free-form SQL useage complicated as we don't have an SQL parser in GNU.FREE to figure out which bits to encrypt and which bits not to. In addition the new authentication scheme in 1.5 means that voters' PIN and password are stored as SHA-1 hashes and not plaintext. Thus we have a custom voter data entry command.

To insert data open ERServer's database console (by clicking on the button in ERServer's main window) and type data in with the following syntax into the command box:

~ votername-pincode-password

Click the Go button to execute the data. To check the contents of the table type:

SELECT * FROM Roll

What this effectively does is:

INSERT INTO Roll VALUES (encrypt('votername'), encrypt(hash('pincode')), encrypt(hash('password')), encrypt('F'));

Pretty much any SQL can be used in the database console so feel free to experiment but note the console will only decrypt outcoming info, it doesn't understand how to encrypt incoming data so SELECT statements will be more interesting.

Automated Import

If you have a LOT of data to import than you'll probably want to avoid doing it by hand. This is why since 1.6 you can import Comma Seperated files (CSV).

Your data needs to have the following format (one record per line):

name, pincode, password, type

So for example it could be:

mrhappy, 2020, hello, F

Type can be either 'F' for a normal user or 'B' for a Test Ballot user. A test ballot user's vote won't actually count - it will be used to prove that the system is actually storing the votes people choose and not doing anything nefarious. This is the only way test users can be created.

The CSV file must be called erserver.users and put in the directory in which ERServer is run from (most likely FREE-1.x). Run ERServer and choose Import Users from the menu or click the button. The file will then be used to automatically populate the Electoral Roll.

Security Note: Please see Running Elections for advice and help on the security implications of having these text files.

Finishing off

Once the ERServer database has been populated, click the Build Keys button. When it's all done take the rtserver.keys (and rtserver.test.keys if you specified some test ballot users) and copy it to the default directory of your RTServer which will probably be the FREE-1.x directory. Then start the RTServer and it will read the file and automatically populate the database with encrypted, unique, single-use keys.

Security Note: Please see Running Elections for advice and help on the security implications of having these text files.

The vote is ready to begin.

Having problems? Take a look around the rest of this documentation and then e-mail me.

- User Home -

Contact - by Jason Kitcat - j-dom portal

Copyright 2000, 2001 FREE e-democracy project.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.