Prerequisites
=============
Java JDK (or JRE) 1.3.1 or higher needs to be installed on your system

Usage
=====
The BIRN ID manager can be run via the following command
 
java -jar birnid_man.jar <arguments>

If arguments are omitted description of the usage is printed as below

Usage:
        java birnid_gen.BIRNIDManager <-create|find> <args>
for BIRN ID creation
        java birnid_gen.BIRNIDManager -create -p <prefix> -l <linkTableFilename> \
                -cf <clinicalIdsFilename> | -c <clinicalId>]
to find the matching message digest for the patient (clinical) ID
        java birnid_gen.BIRNIDManager -find -c <clinicalId> -l <linkTableFilename>


Here prefix is the institution ID (like UCSD) prefixed to to each secure random number generated.

You either provide a list of clinical (patient) ids (using -cf <clinicalIdsFilename>) or a single clinical id (using -c <clinicalId>) to the program to create
BIRN IDs and a link table containing MD5 one-way hashes of the clinical ids and
matching BIRN IDs. The link table is persisted to a text file ( using -l <linkTableFilename> ) and kept upto date every time you create new BIRN IDs. The clinical id file contains clinical IDs one per line.
It is guaranteed that the BIRN ID created is not repeated within the institution. The secure random number generated for BIRN ID has 8 digits, produces non-deterministic output and the seed is unpredictable and the output of the secure random number generator is cryptographically strong sequences (RFC 1750: Randomness Recommendations for Security).

If someone has access to the link table AND clinical ids, he/she can get the 
corresponding BIRN ID using -find option. One cannot retrieve the patient (clinical) IDs from the MD5 one-way patient hashes.

Information about the Random Number Generator used for BIRN ID creation
=======================================================================
SHA1PRNG: The name of the pseudo-random number generation (PRNG) algorithm supplied by the SUN provider. This implementation follows the IEEE P1363 standard, Appendix G.7: "Expansion of source bits", and uses SHA-1 as the foundation of the PRNG. It computes the SHA-1 hash over a true-random seed value concatenated with a 64-bit counter which is incremented by 1 for each operation. From the 160-bit SHA-1 output, only 64 bits are used. 

SHA-1 is the Secure Hash Algorithm, as defined in Secure Hash Standard, NIST FIPS 180-1. 

SHA1PRNG is a cryptographically strong pseudo-random number generator (PRNG). A cryptographically strong pseudo-random number minimally complies with the statistical random number generator tests specified in FIPS 140-2, Security Requirements for Cryptographic Modules, section 4.9.1. Additionally, SecureRandom must produce non-deterministic output and therefore it is required that the seed material be unpredictable and that output of SecureRandom be cryptographically strong sequences as described in RFC 1750: Randomness Recommendations for Security. 
