org.hd.d.efs
Class Gatherer

java.lang.Object
  org.hd.d.efs.Gatherer

public final class Gatherer
extends java.lang.Object

General gatherer of entropy from sources other than serlvet page hits. This can gather entropy from files, processes, and Web pages.

Field Summary

static boolean	DEFAULT_USESEEDFILE Default value of useSeedFile.
static java.lang.String	PNAME__SRCLIST Top-level property (attribute) name for the list of sources.
static java.lang.String	PNAME__USESEEDFILE Top-level property (attribute) name for flag to use a seed file or not.

Constructor Summary

Gatherer(EntropyPool _pool, GenParams _genParams, SrcParams[] _sources, java.io.File _seedFile)
Make new gatherer.

Method Summary

protected void	finalize() Make sure gathering has been stopped by GC of this Gatherer object.
static java.security.DigestOutputStream	getNullDigestStream() Make a stream that computes a secure digest an throws away its content.
EntropyPool	getPool() Recover a reference to the underlying EntropyPool; never returns null.
static boolean	mustConservePower(GenParams genParams) If true, the system should conserve power (eg CPU cycles).
static Gatherer	parseGatherer(java.util.Properties p, java.lang.String prefix, EntropyPool pool, java.io.File seedFile) Retrieve Gatherer from Properties.
void	saveSeed() Attempt to save a seed file (if seedFile is set).
void	start() Call once after construction to start gatherer activity.
void	stop() Stops the entropy gathering.

Methods inherited from class java.lang.Object

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

Field Detail

PNAME__SRCLIST

public static final java.lang.String PNAME__SRCLIST

Top-level property (attribute) name for the list of sources.

See Also:

Constant Field Values

DEFAULT_USESEEDFILE

public static final boolean DEFAULT_USESEEDFILE

Default value of useSeedFile.

See Also:

Constant Field Values

PNAME__USESEEDFILE

public static final java.lang.String PNAME__USESEEDFILE

Top-level property (attribute) name for flag to use a seed file or not.

See Also:

Constant Field Values

Constructor Detail

Gatherer

public Gatherer(EntropyPool _pool,
                GenParams _genParams,
                SrcParams[] _sources,
                java.io.File _seedFile)

Make new gatherer. This needs to be given an EntropyPool to inject bits into, a set of general parameters, and one or more gatherer descriptions.

None of these items need be private to this gatherer, eg other sources may inject bits into the same EntropyPool.

This will not start any gatherer activity until start() is called, and will stop that activity when stop() is called or when this object is garbage collected (the threads hold no reference back to this object).

We create one thread to manage each entropy source.

We may steal some bits from the pool at start-up to help hide our internal state and that of our gatherers and to try to prevent traffic analysis revealing anything about pool state.

Some methods on this object, such as start(), are synchronized for thread safety. Others, such as stop() and finalize() are not to avoid the possibility of deadlock in the GC process.

Parameters:

_sources - list of entropy source descriptions; must be non-zero length and contain no nulls

_seedFile - if non-null is the location of a seed file to read (and overwrite) at startup, and to save to at shutdown and possibly periodically in between; thus any seed file but be readable/writable/creatable by us

Method Detail

getPool

public EntropyPool getPool()

Recover a reference to the underlying EntropyPool; never returns null.

saveSeed

public void saveSeed()
              throws java.io.IOException

Attempt to save a seed file (if seedFile is set). Will attempt to overwrite the start of any extant file and then truncate to size to minimise the chance of being left without a seed file or having any remnant of an old one left behind.

We could disguise the seed file to hide it from some low-level disc or network-traffic sniffing by making it more redundant and by spreading out the bits.

We note the time that we successfully complete the saving of the seed.

Throws:

java.io.IOException

start

public void start()
           throws java.io.IOException

Call once after construction to start gatherer activity. This schedules each task to repeat after the minimum interval (ie at the maximum rate) allowed.

If the source is marked as expensive then the first run is deferred by that minimum interval. For a non-expensive source the first run is scheduled immediately. This avoids pestering/overusing an expensive source if we restart frequently, eg for crash/reboot.

If a seed file name has been passed to the constructor we attempt to read it after starting up our entropy gatherers, then attempt to immediately overwrite it with a new file of the right size to hide the old file contents.

Throws:

java.lang.IllegalStateException - if called more than once

java.io.IOException - in case of difficulty reading/rewriting the seed file

stop

public void stop()

Stops the entropy gathering. Any gathering that is actually in progress when this is called will be allowed to complete.

Cancels all the timers (if not already done). Should be idempotent, but no attempt to use this class should be made after stop() has been called.

finalize

protected void finalize()
                 throws java.lang.Throwable

Make sure gathering has been stopped by GC of this Gatherer object. We do this because we are using non-memory resources.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

parseGatherer

public static Gatherer parseGatherer(java.util.Properties p,
                                     java.lang.String prefix,
                                     EntropyPool pool,
                                     java.io.File seedFile)

Retrieve Gatherer from Properties. Given a Properties object and a prefix (and an EntropyPool), this constructs a Gatherer object using the properties available.

First this constructs a whitespace-separated list of names of sources to use. Then it looks up the general parameters. Then it looks up the sources by name. If the prefix is null then the property names used are of the form:

     sources
     useSeedFile
     genParams.genAttributeName
     srcParams.sourceName.srcAttributeName
 

else they are of the form:

     prefix.sources
     prefix.useSeedFile
     prefix.genParams.genAttributeName
     prefix.srcParams.sourceName.srcAttributeName
 

Parameters:

seedFile - if non-null and read/writable (or creatable) and the useSeedFile property is true, then use the given file as a seed file at start-up and shut-down

pool - the EntropyPool that this gatherer will try to keep filled

p - the properties to read from (they are not altered by thus routine)

prefix - the prefix to apply to property names; null means no prefix at all else the value passed has a ``.'' appended and is then prefixed to the property named used

Returns:

GenParams object; as if created with the default constructor if no suitable configuration is available

Throws:

java.lang.IllegalArgumentException - if any of the parameters specified by the properties is invalid or unusable

getNullDigestStream

public static java.security.DigestOutputStream getNullDigestStream()

Make a stream that computes a secure digest an throws away its content. Typically you might wrap this in a PrintStream or similar.

This uses the EntropyPool's preferred digest algorithm.

Use getMessageDigest() to get access to the underlying hash when you are done.

If a suitable hash/digest cannot be created this throws a fatal Error

Throws:

java.lang.Error - if a suitable hash algorithm cannot be found

mustConservePower

public static boolean mustConservePower(GenParams genParams)

If true, the system should conserve power (eg CPU cycles).