org.hd.d.efs
Class GenParams

java.lang.Object
  extended by 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