Package gnu.java.zrtp.utils

Class FortunaGenerator

java.lang.Object

gnu.java.zrtp.utils.FortunaGenerator

All Implemented Interfaces:

org.bouncycastle.crypto.prng.RandomGenerator

public class FortunaGenerator
extends Object
implements org.bouncycastle.crypto.prng.RandomGenerator

The Fortuna random number generator.

This class is a modified variant of the original Fortuna generator in GNU Classpath (see note below). The class now uses the Bouncycastle hash and cipher classes and provides a Bouncycastle compliant interface.

Fortuna is a continuously-seeded pseudo-random number generator (PRNG) and is composed of two major pieces: the entropy accumulator and the generator function. The former takes in random bits and incorporates them into the generator's state. The latter takes this base entropy and generates pseudo-random bits from it.

Here an example how to use the FortunaGenerator (pseudo code):

 ...
     new Random().nextBytes(firstSeed)  // get some random data
     FortunaGenerator fg = new FortunaGenerator(firstSeed);
     ...
     
     fg.nextBytes(randomData)
     ...
     fg.addSeedMaterial(entropyData)
 
 

After some time the application has done its work and exits. To enable a fast restart of the FortunaGenerator you may store the seed status and initialize the FortunaGenerator with this seed the next time. For example:

 ... // use FortunaGenerator
     seedStatus = fg.getSeedStatus()
     
     // save seed status somewhere
     // exit application
 ...
     // restart application
     if (saved seed status available) 
         read seed status data
         FortunaGenerator fg = new FortunaGenerator()
         fg.setSeedStatus(seed status data)
     // alternatively you can do 
         FortunaGenerator = new FortunaGenerator(seed status data)
     // use FortunaGenerator
 
 

There are some things users of this class must be aware of:

Adding Random Data

This class does not do any polling of random sources, but rather provides an interface for adding entropy data (additional seed). Applications that use this code must provide this mechanism. We use this design because an application writer who knows the system he is targeting is in a better position to judge what random data is available.

Storing the Seed

This class implements functions to read and restore the seed in such a way that it returns a 64 byte seed byte array to the application, and sets it back again when the application sets the seed status again. This is the extent of seed file management, however, and those using this class are encouraged to think deeply about when, how often, and where to store the seed.

References:

• Niels Ferguson and Bruce Schneier, Practical Cryptography, pp. 155--184. Wiley Publishing, Indianapolis. (2003 Niels Ferguson and Bruce Schneier). ISBN 0-471-22357-3.

I did some small enhancements of the re-seed loop that, otherwise the algorithms were not touched.

License: the Bouncycastle license applies to this file. Also notice the GNU Classpath license exception (see below).

Copyright (C) 2010 Werner Dittmann (Werner.Dittmann@t-online.de)
Copyright (C) 2004, 2006 Free Software Foundation, Inc.

Field Summary

Fields

Modifier and Type	Field	Description
protected int	ndx	The index into buffer of where the next byte will come from.

Constructor Summary

Constructors

Constructor	Description
FortunaGenerator()
FortunaGenerator(byte[] seed)

Method Summary

Modifier and Type	Method	Description
void	addSeedMaterial(byte[] buf)	Adds new random data (entropy) to an entropy pool.
void	addSeedMaterial(byte[] buf, int offset, int length)	Adds new random data (entropy) to an entropy pool.
void	addSeedMaterial(int poolNumber, byte[] data, int offset, int length)	Adds new random data (entropy) to the specified entropy pool.
void	addSeedMaterial(long b)	Adds new random data (entropy) to an entropy pool.
byte[]	getSeedStatus()	Return the generator's seed status.
void	nextBytes(byte[] out)	Get new random data.
void	nextBytes(byte[] out, int offset, int length)	Get new random data.
void	setSeedStatus(byte[] seedStatus)	Seed the generator with a previously saved seed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ndx

protected int ndx

The index into buffer of where the next byte will come from.

Constructor Detail

FortunaGenerator

public FortunaGenerator()

FortunaGenerator

public FortunaGenerator(byte[] seed)

Method Detail

nextBytes

public void nextBytes(byte[] out)

Get new random data.

This functions fills a byte buffer with new random data.

Specified by:

nextBytes in interface org.bouncycastle.crypto.prng.RandomGenerator

Parameters:

out - the buffer that receives the random data

nextBytes

public void nextBytes(byte[] out,
                      int offset,
                      int length)

Get new random data.

This functions returns new random data.

Specified by:

nextBytes in interface org.bouncycastle.crypto.prng.RandomGenerator

Parameters:

out - the buffer that receives the random data

offset - offset into the buffer

length - number of random bytes

addSeedMaterial

public void addSeedMaterial(long b)

Adds new random data (entropy) to an entropy pool.

This functions adds entropy data to the current pool. Fortuna uses 32 pools to gather entropy. After the function added the entropy to the pool it increments the current pool number modulo 32.

Only if pool 0 (zero) got enough entropy (min. 64 bytes) then Fortuna uses the pools to perform a real re-seed. If an application uses this function to add entropy it shall take this behaviour into consideration.

Specified by:

addSeedMaterial in interface org.bouncycastle.crypto.prng.RandomGenerator

Parameters:

b - a long with new entropy data. If the current pool is 0 then the function adds the length of a long to the overall entropy count that controls re-seed.

addSeedMaterial

public void addSeedMaterial(byte[] buf)

Adds new random data (entropy) to an entropy pool.

This functions adds entropy data to the current pool. Fortuna uses 32 pools to gather entropy. After the function added the entropy to the pool it increments the current pool number modulo 32.

Only if pool 0 (zero) got enough entropy (min. 64 bytes) then Fortuna uses the pools to perform a real re-seed. If an application uses this function to add entropy it shall take this behaviour into consideration.

Specified by:

addSeedMaterial in interface org.bouncycastle.crypto.prng.RandomGenerator

Parameters:

buf - buffer with new entropy data. If the current pool is 0 then the function adds the length of the buffer to the overall entropy count that controls re-seed.

addSeedMaterial

public void addSeedMaterial(byte[] buf,
                            int offset,
                            int length)

Adds new random data (entropy) to an entropy pool.

This functions adds entropy data to the current pool. Fortuna uses 32 pools to gather entropy. After the function added the entropy to the pool it increments the current pool number modulo 32.

Only if pool 0 (zero) got enough entropy (min. 64 bytes) then Fortuna uses the pools to perform a real re-seed. If an application uses this function to add entropy it shall take this behaviour into consideration.

Parameters:

buf - buffer with new entropy data.

offset - offset into the buffer

length - number of bytes to add to the current pool's entropy. If the current pool is 0 then the function adds the length of the buffer to the overall entropy count that controls re-seed.

addSeedMaterial

public void addSeedMaterial(int poolNumber,
                            byte[] data,
                            int offset,
                            int length)

Adds new random data (entropy) to the specified entropy pool.

This functions adds entropy data to the the specified pool. Fortuna uses32 pools to gather entropy.

Only if pool 0 (zero) got enough entropy (min. 64 bytes) then Fortuna uses the pools to perform a real re-seed. If an application uses this function to add entropy it shall take this behaviour into consideration.

Parameters:

poolNumber - specifies which pool receives the entropy data

data - buffer with new entropy data.

offset - offset into the buffer

length - number of bytes to add to the specified pool's entropy. If the specified pool is 0 then the function adds the length of the data to the overall entropy count that controls re-seed.

getSeedStatus

public byte[] getSeedStatus()

Return the generator's seed status.

An application may get the seed status, store it in a safe place and retrieve it to seed a new Fortuna PRNG instance.

Returns:

The seed status.

setSeedStatus

public void setSeedStatus(byte[] seedStatus)

Seed the generator with a previously saved seed.

Parameters:

seedStatus - the generator's seed.