README for java implementation of HB and HB Plus Protocol for use in RFID tags

Kelsey Livingston
8/20/06
Stevens Institute of Tech/DIMACS REU SUmmer 2006
kliving2@email.smith.edu

This collection of classes simulates the implemention the HB and HB Plus Protocols on 
RFID tags and readers.  This README assumes the reader has basic knowledge of these protocols.
For more information, see www.cs.stevens.edu/~klivings

This summer, I wrote the following classes

Protocol.java
HB.java
HBPlus.java
Reader.java
HBReader.java
HBPlusReader.java
Tag.java
HBTag.java
HBPlusTag.java

Debugging.java
UserInterface.java
DataCollection.java
GenData.java
SecData.java
Parse.java

The first 9 files constitute the basic implementation files, while the last 6 are a variety
of user interface and data collection tools for collecting information on the implementation.

BASIC IMPLEMENTATION

Protocol, Reader, and Tag are abstract classes, and each are extended by a HB and HB Plus subclass
The abstract classes contain fields and methods used by both protocols, while the subclasses contain
protocol specific fields and methods.  Each Protocol instance contains a Reader and Tag instance, and 
the Protocol calls various methods in the Reader and Tag to execute an iteration fo the HB or HB Plus
protocol.


RANDOM NUMBER GENERATION

Random numbers are needed many times in each iteration of a protcol, as follows:
1) The creation of an array of 32 bit secrets (HB) or pairs of secrets (HBPlus) for the reader
2) The choice of 1 secret or pair of secrets from this array to be the tag's secret
3) The creation of queries by the reader
4) The creation of queries by the tag (HBPlus only)
5) The flipping of responses by the tag

My implimentation allows 3 types of random number generation.  
1) The unseeded java random number generator
2) The seeded java random number generator, with seeds being drawn from provided files
3) All random numbers drawn from pregenerated files

We found the second method to be the best compromise for large scale data collection, and used
files of hex from random.org as the source for the seeds for the random number generator.

USER INTERFACES

UserInterface is meant for small scale demonstrations and unsophisticated user interaction.  It 
allows the user to change the parameters used in the protocol without changing the code, and 
is set up to print results to the screen, rather than a file.

DATA COLLECTION PROGRAMS

DataCollection, GenData, and SecData are all meant for large scale data collection.  DataCollection
uses all pregenerated files, while GenData and SecData use only pregenerated seeds.  

There are four easily variable parameters of the protocols that we chose to examine this summer:
1) The number of secrets
2) The number of queries
3) The value of epsilon
4) The allowed variance of error above and below epsilon (We tend to call this the bound)
Given specific values for these four parameters, DataCollection and GenData are meant to 
collect information on the number of accepts or rejects in 50 sets of 100 iterations of the protocol.
Each of these programs produces 50 result files per run.

We noticed that the reader was occasionally accepting the tag on the wrong secret, so we wrote
SecData to print result files that were more specific than GenData and indicated whether the
reader accepted using the right secret or not.

PARSE

Parse uses the 50 result files created by each run of DataCollection, GenData, and SecData and compiles
them into 1 more easily readable result files with percentages of accepts (or in the case of SecData,
bad accepts) out of all of the iterations of the protocol.

SOURCE AND RESULT FILES

DataCollection, GenData, SecData, Parse, and UserInterface all require specifically named, located, 
and formated source files.  Except for Parse, source files should be located in the directory 
Source, and contain hex (the programs will ignore white space and carriage returns in reading the 
hex, so the exact format within the files is unimportant).  For more information on the specific 
names of the source files and results produced, read the section of the header on each program 
marked FILES. 

These 5 programs also allow certain command line arguments that print debugging code and provide 
information.  See the ARGS section of each header for more information on specific required
or optional command line args.

DEBUGGING

Debugging contains 7 debugging booleans.  When flipped to true, these print real time information 
about the execution of the protocol to the screen.  See the debugging header for more information.