Class BitPool

java.lang.Object
   |
   +----java.lang.Thread
           |
           +----BitPool

public class BitPool
extends Thread

Netrand Project

Software Engineering - CS536

University of Wisconsin - Milwaukee

Authors:

Spring 1998 - Francis William Kasper

File: BitPool.java

As the clients collect entropy from the network, they send their results back to the server in datagram packets. It is the BitPool class which handles the datagram socket that accepts these packets and stores them in an internal buffer. This operation is performed from within its own thread. It is assumed that the clients are sending one byte of random data at a time. The reason for only accepting one byte at a time is to to prevent large strings of random data that originated from one source. When a byte of data is received, a section of the current buffer is hashed using the HashMD5 class. Each byte of the resulting hash value is XORed together and then XORed with the new byte. This helps to reduce biases in the incoming data.
Note: this hashing behavior does not begin until the BitPool has accumulated enough bytes in the internal buffer to hash. If there are not enough bytes in the internal buffer as input to the hash function, the the new bytes are added to the internal buffer as is.

There are two ways the BitPool class can be used:

BitPool can be called by the RandomByteServer class to collect data from the clients. When the RandomByteServer receives a request for string of random bytes, it queries the BitPool for the data.
BitPool can be called from the command line:
java BitPool [receiving_port] [output_file]
In this mode, the BitPool class collects the data received from the clients and writes it to the output file.

bitPool
internal byte buffer
collector
datagram receiving socket
incoming
holds the incoming datagram packets
maxPoolSize
maximum size of the internal buffer
maxRequestSize
maximum bytes available per request
outputFile
the output file when running in file-mode

BitPool(int, int, int)
constructor for the BitPool class - server mode
BitPool(int, String)
constructor for the BitPool class - file mode

addPacketDataToPool(DatagramPacket)
extracts the data from a packet and calls hashIntoBuffer() to add it to the internal buffer.
getBytesFromPool(int)
extracts bytes from the internal buffer
hasBytesAvailable(int)
determines if there are enough bytes in the internal buffer to fill a request
hashIntoBuffer(byte)
takes newly a newly received byte and adds it to the internal buffer.
initBitCollection(int)
initializes the DatagramSocket which receives the packets from the clients
initRandomBitPool(int, int)
initializes the internal buffer which stores the random bytes of data Note: the internal buffer is actually be poolSize + numHashInputBytes : this is done to prevent setting the maximum pool size to be less than the number of bytes needed to hash the buffer
main(String[])
Run when the BitPool class is involked from the command line.
run()
overrides the Thread's run() method; an infinite loop which receives datagram packets over the socket, calls the appropriate functions to add the datagram packet's data to the internal buffer

collector
```
 private DatagramSocket collector
```
datagram receiving socket

incoming
```
 private DatagramPacket incoming
```
holds the incoming datagram packets

bitPool
```
 private ByteVector bitPool
```
internal byte buffer

maxPoolSize
```
 private int maxPoolSize
```
maximum size of the internal buffer

maxRequestSize
```
 private int maxRequestSize
```
maximum bytes available per request

outputFile
```
 private FileOutputStream outputFile
```
the output file when running in file-mode

BitPool
```
 public BitPool(int maxReqBytes,
                int poolSize,
                int collectionPort) throws BitPoolException
```
constructor for the BitPool class - server mode

Parameters:
maxReqBytes - - maximum number of bytes a user can take from buffer at one time
poolSize - - the size of the internal buffer which stores the random bytes of data
collectionPort - - the listening port for the datagram socket to accept packets from the clients
Throws: BitPoolException
if an error occurs while initializing the object

BitPool
```
 public BitPool(int collectionPort,
                String outFile) throws BitPoolException, IOException
```
constructor for the BitPool class - file mode

Parameters:
collectionPort - - the listening port for the datagram socket to accept packets from the clients
outFile - - the name of file to write data to
Throws: BitPoolException
if an error occurs while initializing the BitPool object

main
```
 public static void main(String args[])
```
Run when the BitPool class is involked from the command line.

Parameters:
args[0] - - port the DatagramSocket should listen for data on
args[1] - - the file to write the random bytes to

run
```
 public void run()
```
overrides the Thread's run() method; an infinite loop which receives datagram packets over the socket, calls the appropriate functions to add the datagram packet's data to the internal buffer

Overrides:
run in class Thread

initBitCollection
```
 private void initBitCollection(int port) throws BitPoolException
```
initializes the DatagramSocket which receives the packets from the clients

Parameters:
port - - the port to listen for incoming packets on
Throws: BitPoolException
if the attempt to open the socket fails

initRandomBitPool
```
 private void initRandomBitPool(int maxReqBytes,
                                int poolSize) throws BitPoolException
```
initializes the internal buffer which stores the random bytes of data Note: the internal buffer is actually be poolSize + numHashInputBytes : this is done to prevent setting the maximum pool size to be less than the number of bytes needed to hash the buffer

Parameters:
maxReqBytes - - the maximum number of bytes a user and extract from the buffer at one time
poolSize - - the maximum visable size of the internal buffer
Throws: BitPoolException
if an error occured while initializing the buffer

hasBytesAvailable
```
 public boolean hasBytesAvailable(int numBytes)
```
determines if there are enough bytes in the internal buffer to fill a request

Parameters:
numBytes - - the number of bytes to request
Returns:
true iff the removal of numBytes from the internal buffer would not bring the size of the buffer below the number of bytes needed as input to the hash function AND numBytes is less than the maximum request size

addPacketDataToPool
```
 private synchronized void addPacketDataToPool(DatagramPacket p)
```
extracts the data from a packet and calls hashIntoBuffer() to add it to the internal buffer. If BitPool is running in conjunction with the server, when the internal buffer exceeds the maximum pool size, the buffer is reduced to the maximum pool size by discarding the older random bytes in the buffer. If BitPool is running in file mode, when the internal buffer exceeds the maximum pool size, the access bytes are written to the output file.

Parameters:
p - - the datagram packet holding the data

getBytesFromPool
```
 public synchronized byte[] getBytesFromPool(int numBytes) throws BitPoolException
```
extracts bytes from the internal buffer

Parameters:
numBytes - - the number of bytes to extract from the buffer
Returns:
an array of bytes containing the requested data
Throws: BitPoolException
if the internal buffer cannot supply the requested bytes

hashIntoBuffer
```
 private synchronized void hashIntoBuffer(byte newByte)
```
takes newly a newly received byte and adds it to the internal buffer. if there are enough existing bytes in the buffer to be hashed by the HashMD5 class, then oldest bytes in the internal buffer are hashed. Each byte of the hash value is XORed together along with the new byte. Then the new byte is added to the internal buffer. If the internal buffer does not have enough bytes to hash, the new byte is added to the buffer as is.

Parameters:
newByte - - the new byte to add to the buffer