Secure Biometrics
			   =================
	Library and framework for privacy-preserving computation


	 Copyright (C) 2010 by Yan Huang 

This software package is made freely available under the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


Example Usage
=============

To compile the code, use Ant (http://ant.apache.org/).

e.g.,
 user@laptop:~/secureFP ant

All .class files are generated and stored in the "build" directory. 
Jar files are in the "dist" directory. 


To start the server, type

java -cp dist/jargs.jar:dist/commons-io-1.4.jar:dist/SecureFP.jar Test.Server -N 32 -M 640 --pad-bitlength 45 --sec-param 1024

Specification of involved command line parameters to the server:
-N: the number of rows in the randomly generated database.
-M: the length (in bytes) of each FingerCode vector.
--pad-bitlength: the bit length of paddings which hide the squared distances at the end of the Euclidean distance protocol.
--sec-param: 	 the length of the Paillier Modulus.

To start the client, type

java -cp dist/jargs.jar:dist/commons-io-1.4.jar:dist/SecureFP.jar Test.Client -M 640 -r 5 --server localhost

Specification of involved command line parameters to the client:
-M: the length (in bytes) of each FingerCode vector.
-r: the number of queries to the server (the FingerCode vector is freshly sampled per query).
--server: the IP of the server

Interpretation of the standard output:

At the server's console, time- and bandwidth- stamps are displayed for
each mini-stage. Times are in miliseconds, while bandwidth in
KB. Bandwidthes are given in pairs surrounded with parentheses, in which
the first entry is the server-to-client traffic, and the second entry
the verse. For example,

Elapsed time (ms) on circuit garbling: 112 (160.4326171875, 0.0)

means it takes 112ms to execute the circuit, during which 160.43KB
traffic flows from the server to the client and 0 traffice from client
to the server.


Other output:

Two additional files are generated, db and db_encryption. They are the
binary representation of the database and the encrypted database (with
additive homomorphic encryption). To change the path and file names of
the two files, supply to the server with the "--database" and
"--database-encryption" parameters. (e.g., --database results/db32
--database-encryption results/db32-encryption makes the server store the
two files to the directory "results" and with more specific names.


Package Structure
=================


|-- extlib
	Dependent packages.
`-- src
	Source code files.
    |-- BackTrackTree
		The backtrack tree protocol.
    |-- Cipher
		The symmetric cipher utility.
    |-- OEDP
		The standard Euclidean distance protocol.
    |-- OEDPVar
		The improved Euclidean distance protocol.
    |-- OT
		The oblivious transfer protocols (NPOT and OT Extension).
    |-- Paillier
		The Paillier asymmetric encryption utility.
    |-- Test
		Testing drivers.
    |-- Utils
		Utility classes.
    `-- YaoGC
		The classes for all kinds of garbled circuits.