org.hd.d.efs
Class GenParams

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

public final class GenParams
extends java.lang.Object

General parameters for gatherer mechanism. This is immutable.

Attributes are exposed as final fields for simplicity.

Field Summary

static float	DEFAULT_INSECURE_ENTROPY_MULTIPLIER Weighting (multiplier) to apply to estimated entropy from non-secure source.
static int	DEFAULT_MAX_BYTES_FROM_ENTROPY_SOURCE Default maximum input to be read from any entropy source (bytes).
static int	DEFAULT_MAX_CONCURRENT Default maximum concurrency in fetching from entropy sources; strictly positive.
static int	DEFAULT_MAX_DATA_FETCH_TIME_MS Default maximum time to wait for data from an entropy source (ms).
static int	DEFAULT_MAX_REFETCH_INTERVAL_MS Default maximum time between successive fetches of data from one source (ms), even after errors.
static int	DEFAULT_MIN_EXPENSIVE_REFETCH_INTERVAL_MS Default minimum time between successive fetches of data from one expensive source (ms).
static int	DEFAULT_MIN_REFETCH_INTERVAL_MS Default minimum time between successive fetches of data from one inexpensive source (ms).
static int	DEFAULT_MIN_SEED_DUMP_MS Default minimum interval (ms) between automatic seed dumps; strictly positive.
static int	DEFAULT_MIN_SEED_DUMP_TEST_MS Default minimum interval (ms) between automatic seed dumps attempts; strictly positive.
static int	DEFAULT_STIR_INTERVAL_MS Default pool-stirrer interval (ms); prime and strictly positive.
static boolean	DEFAULT_VERBOSITY Default verbosity level.
float	insecureEntropyMultiplier Weighting (multiplier) to apply to estimated entropy from non-secure source; in range 0.0f to 1.0f inclusive.
int	maxBytesFromEntropySource Maximum input to be read from any entropy source (bytes); strictly positive.
int	maxConcurrent Maximum concurrency in fetching from entropy sources; strictly positive.
int	maxDataReadTimeMs Maximum time to wait for data from an entropy source (ms); strictly positive.
int	maxRefetchIntervalMs Minimum time between successive fetches of data from one source (ms); non-negative, even after errors.
int	minRefetchIntervalMs Minimum time between successive fetches of data from one inexpensive source (ms); non-negative.
static java.lang.String	PNAME__GENPARAMS Generic top-level property (attribute) name for GenParams.
static java.lang.String	PNAME_INSECURE_ENTROPY_MULTIPLIER Property (and printable) name for isSecure.
static java.lang.String	PNAME_MAX_CONCURRENT Property (and printable) name for maximum concurrency in fetching from entropy sources.
static java.lang.String	PNAME_VERBOSITY Property (attribute) name for verbosity.
boolean	verbose If true, run verbose.

Constructor Summary

GenParams()
Creates default set of general parameters.

GenParams(int _maxBytesFromEntropySource, int _minRefetchIntervalMs, int _maxDataFetchTimeMs, int _maxRefetchIntervalMs, float _insecureEntropyMultiplier, int _maxConcurrent, boolean _verbose)
Create custom set of general parameters.

Method Summary

static GenParams

parseGenParams(java.util.Properties p, java.lang.String prefix) Retrieve GenParams from Properties.

Methods inherited from class java.lang.Object

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

Field Detail

PNAME__GENPARAMS

public static final java.lang.String PNAME__GENPARAMS

Generic top-level property (attribute) name for GenParams.

See Also:

Constant Field Values

DEFAULT_MAX_BYTES_FROM_ENTROPY_SOURCE

public static final int DEFAULT_MAX_BYTES_FROM_ENTROPY_SOURCE

Default maximum input to be read from any entropy source (bytes).

See Also:

Constant Field Values

maxBytesFromEntropySource

public final int maxBytesFromEntropySource

Maximum input to be read from any entropy source (bytes); strictly positive.

DEFAULT_MIN_REFETCH_INTERVAL_MS

public static final int DEFAULT_MIN_REFETCH_INTERVAL_MS

Default minimum time between successive fetches of data from one inexpensive source (ms). Many typical (eg UNIX) system stats and human-driven processes take of the order of seconds to change significantly.

See Also:

Constant Field Values

minRefetchIntervalMs

public final int minRefetchIntervalMs

Minimum time between successive fetches of data from one inexpensive source (ms); non-negative.

DEFAULT_MIN_EXPENSIVE_REFETCH_INTERVAL_MS

public static final int DEFAULT_MIN_EXPENSIVE_REFETCH_INTERVAL_MS

Default minimum time between successive fetches of data from one expensive source (ms).

See Also:

Constant Field Values

DEFAULT_MAX_REFETCH_INTERVAL_MS

public static final int DEFAULT_MAX_REFETCH_INTERVAL_MS

Default maximum time between successive fetches of data from one source (ms), even after errors. This is less than the length of a typical working day so that we have a fair chance to sample at least once each working day stats that only change markedly during it, whenever it may be, even if good day/hour values are not used.

See Also:

Constant Field Values

maxRefetchIntervalMs

public final int maxRefetchIntervalMs

Minimum time between successive fetches of data from one source (ms); non-negative, even after errors.

DEFAULT_MAX_DATA_FETCH_TIME_MS

public static final int DEFAULT_MAX_DATA_FETCH_TIME_MS

Default maximum time to wait for data from an entropy source (ms).

See Also:

Constant Field Values

maxDataReadTimeMs

public final int maxDataReadTimeMs

Maximum time to wait for data from an entropy source (ms); strictly positive.

DEFAULT_INSECURE_ENTROPY_MULTIPLIER

public static final float DEFAULT_INSECURE_ENTROPY_MULTIPLIER

Weighting (multiplier) to apply to estimated entropy from non-secure source. Note that the default of 0.0f means that non-secure-source data will still be folded into the entropy pool but will not increase the pool's entropy count.

See Also:

Constant Field Values

PNAME_INSECURE_ENTROPY_MULTIPLIER

public static final java.lang.String PNAME_INSECURE_ENTROPY_MULTIPLIER

Property (and printable) name for isSecure.

See Also:

Constant Field Values

insecureEntropyMultiplier

public final float insecureEntropyMultiplier

Weighting (multiplier) to apply to estimated entropy from non-secure source; in range 0.0f to 1.0f inclusive.

DEFAULT_MAX_CONCURRENT

public static final int DEFAULT_MAX_CONCURRENT

Default maximum concurrency in fetching from entropy sources; strictly positive. Set low enough to be unlikely to overwhelm even a small installation while allowing reasonable concurrency to overcome latency and to enhance non-determinism.

Especially useful at startup when otherwise the Gatherer may try to run all sources at once.

Note that setting this too low may reduce the rate at which the pool can be topped up.

We may wish to reduce concurrency when in a 'low power' mode.

See Also:

Constant Field Values

PNAME_MAX_CONCURRENT

public static final java.lang.String PNAME_MAX_CONCURRENT

Property (and printable) name for maximum concurrency in fetching from entropy sources.

See Also:

Constant Field Values

maxConcurrent

public final int maxConcurrent

Maximum concurrency in fetching from entropy sources; strictly positive.

DEFAULT_MIN_SEED_DUMP_MS

public static final int DEFAULT_MIN_SEED_DUMP_MS

Default minimum interval (ms) between automatic seed dumps; strictly positive. Something of the order of several hours is probably fine; we can postpone such a save when we are conserving power, for example.

See Also:

Constant Field Values

DEFAULT_MIN_SEED_DUMP_TEST_MS

public static final int DEFAULT_MIN_SEED_DUMP_TEST_MS

Default minimum interval (ms) between automatic seed dumps attempts; strictly positive. Somewhere of the order of hourly (but not a round interval) is probably fine.

See Also:

Constant Field Values

DEFAULT_STIR_INTERVAL_MS

public static final int DEFAULT_STIR_INTERVAL_MS

Default pool-stirrer interval (ms); prime and strictly positive.

See Also:

Constant Field Values

DEFAULT_VERBOSITY

public static final boolean DEFAULT_VERBOSITY

Default verbosity level.

See Also:

Constant Field Values

PNAME_VERBOSITY

public static final java.lang.String PNAME_VERBOSITY

Property (attribute) name for verbosity.

See Also:

Constant Field Values

verbose

public final boolean verbose

If true, run verbose.

Constructor Detail

GenParams

public GenParams()

Creates default set of general parameters.

GenParams

public GenParams(int _maxBytesFromEntropySource,
                 int _minRefetchIntervalMs,
                 int _maxDataFetchTimeMs,
                 int _maxRefetchIntervalMs,
                 float _insecureEntropyMultiplier,
                 int _maxConcurrent,
                 boolean _verbose)

Create custom set of general parameters.

Parameters:

_maxBytesFromEntropySource - strictly-positive limit on number of bytes to read from any one entropy source on any one run unless overridden for that source

_minRefetchIntervalMs - non-negative interval in milliseconds before revisiting an entropy source to fetch more data

_maxDataFetchTimeMs - strictly-positive limit on time in milliseconds that will be spent reading data from a given source before we decide that that source is failed or jammed (useful for giving up on locked or slow sources); if we reach that limit any data collected so far is folded into the entropy pool but the entropy may be counted as zero

_insecureEntropyMultiplier - [0.0f, 1.0f] multiplier on entropy from sources that may be observable by other parties ie people that may want to guess a key value that you have extracted from an entropy pool; for non-sensitive applications such as generation of numbers for purely statistical purposes this should probably be 1.0f, for highly-sensitive applications 0.0f to discount this viewable data, for normal circumstances maybe 0.5f so that an adversiary in effect does not know which half of the bits you have actually used

_maxConcurrent - is the preferred maximum number of sources to collect from at once; bigger may help avoid problems if some jam, allow faster startup, and possibly throw more scheduling and network-timing noise into the pot

_verbose - if true, run the gathering system in verbose mode with logging output to System.err and System.out

Throws:

java.lang.IllegalArgumentException - if input parameters are out of range

Method Detail

parseGenParams

public static GenParams parseGenParams(java.util.Properties p,
                                       java.lang.String prefix)

Retrieve GenParams from Properties. Given a Properties object and a prefix, this constructs a GenParams object using the properties available. If the prefix is null then the property names used are of the form:

     genParams.genAttributeName
 

else they are of the form:

     prefix.genParams.genAttributeName
 

Parameters:

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