FortunaGenerator (bccontrib 1.0 API)

java.lang.Object
- org.jitsi.bccontrib.prng.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 and Description

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

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

Constructor Summary

Constructors
Constructor and Description

FortunaGenerator()

FortunaGenerator(byte[] seed)

Constructors
Constructor and Description
`FortunaGenerator()`
`FortunaGenerator(byte[] seed)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.

Class FortunaGenerator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ndx

Constructor Detail

FortunaGenerator

FortunaGenerator

Method Detail

nextBytes

nextBytes

addSeedMaterial

addSeedMaterial

addSeedMaterial

addSeedMaterial

getSeedStatus

setSeedStatus