ccs.chaos
Class ChaosMage

java.lang.Object
  extended by ccs.chaos.ChaosMage

public class ChaosMage
extends java.lang.Object

The ChaosMage is Checkpoint's crytosecure random number source. The bytestrings returned by the ChaosMage are suitable for all uses of random uniform deviates without further processing. This class is the central co-ordinator. Most applications should not instantiate it directly. Instead, use ccs.cxp.ChaosGetter to retrieve random numbers from the Daemon's instance.

There is also a "default ChaosMage" which is used by certain kernel classes. If your app has access to the Daemon, call DaemonManager.initDefaultMage during your app's startup process to initialise this. If your app always starts a session straight away, do this after starting the session; otherwise, do it during startup anyway. If your app does not always have access to the Daemon, call startScavenger during the startup process. Your app can use the default ChaosMage as well, if it doesn't have access to the Daemon.

The ChaosMage is a slightly sawn-off implementation of Yarrow. It only has one pool (Yarrow specifies two - one for everyday use and one for close encounters), doesn't keep its entropy sources separate (it can't really tell where a particular sample is coming from), and doesn't automatically reseed (At the moment, entropy always comes in manually, and so do reseeds.) The design freely admits that the current reseed control is still ad-hoc, so subsituting another ad-hocery should not have too deleterious an effect on the security of the system. We use AES and SHA-512 as our primitives; the Yarrow-160 reference implem uses TripleDES and SHA-1 instead.

MT-Safe.


Field Summary
static int DEFAULTKEYLENGTH
          A good default length for a symmetric key.
 
Constructor Summary
ChaosMage()
           
 
Method Summary
 ChaosMetrics addEntropy(byte[] sample, float degrader)
          Accepts a supply of entropy and adds it to the pool.
static ChaosMage getDefaultMage()
          Returns a "default ChaosMage".
 void getRandom(byte[] buf, int off, int len)
          Obtain random numbers.
 ChaosModel getStatus()
          Obtain a status report.
 void load(java.io.DataInputStream src)
          Loads the ChaosMage's state from a stream.
 void reseed()
          Reseed the generator.
 void save(java.io.DataOutputStream dest)
          Save the ChaosMage's state to a stream.
 void setAcceptLowEntropyReseed(boolean isAcceptable)
          Sets whether the generator can be reseeded with an inadequate amount of entropy.
static void setDefaultSeed(byte[] seed)
          Sets the seed for the default ChaosMage.
static void startScavenger()
          Starts a background entropy-scavenger for the default ChaosMage.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULTKEYLENGTH

public static final int DEFAULTKEYLENGTH
A good default length for a symmetric key. (This assumes a cryptosystem where all keys are equally strong; most mainstream symmetric encryption algorithms have this property, including the AES cipher which Checkpoint uses.)

See Also:
Constant Field Values
Constructor Detail

ChaosMage

public ChaosMage()
Method Detail

getDefaultMage

public static ChaosMage getDefaultMage()
Returns a "default ChaosMage". This primarily for use by kernel classes which may need cryptorandom numbers but don't have access to the Daemon (since it might not be there). This instance is preseeded; the seed should be good enough for many purposes but you shouldn't use this ChaosMage for generating long-term or high-value keys.

Throws:
java.io.IOException

setDefaultSeed

public static void setDefaultSeed(byte[] seed)
Sets the seed for the default ChaosMage.


startScavenger

public static void startScavenger()
Starts a background entropy-scavenger for the default ChaosMage. If your app does not have access to the Daemon, you should call this as part of its startup process.


load

public void load(java.io.DataInputStream src)
          throws java.io.IOException
Loads the ChaosMage's state from a stream.

Throws:
java.io.IOException

save

public void save(java.io.DataOutputStream dest)
          throws java.io.IOException
Save the ChaosMage's state to a stream. The ChaosMage's state changes after every getRandom or addEntropy call, and should be saved.

Throws:
java.io.IOException

addEntropy

public ChaosMetrics addEntropy(byte[] sample,
                               float degrader)
Accepts a supply of entropy and adds it to the pool. You should usually call saveState immediately afterwards.

Parameters:
sample - The bytes.
degrader - The factor to multiply the entropy estimate by. Must be between 0.0 and 0.5.

setAcceptLowEntropyReseed

public void setAcceptLowEntropyReseed(boolean isAcceptable)
Sets whether the generator can be reseeded with an inadequate amount of entropy. This is not generally recommended: use the ChaosGetter instead. However, it can be useful in some situations where the sequence needs to be repeatable: the high seeding costs of the ChaosMage make it more resistant to dictionary attacks than a simple PRNG. (NB. the degree of immunity decreases exponentially as the entropy drops.)


reseed

public void reseed()
Reseed the generator. You should call saveState immediately afterwards. There must be at least 100 bits of entropy in the fast pool, or the operation will fail.


getRandom

public void getRandom(byte[] buf,
                      int off,
                      int len)
               throws CipherException
Obtain random numbers.

Parameters:
buf - The buffer to fill with random numbers.
off - The offset to start from.
len - The number of random bytes to supply. Must be divisible by 8.
Throws:
CipherException

getStatus

public ChaosModel getStatus()
                     throws java.io.IOException
Obtain a status report.

Throws:
java.io.IOException