org.hd.d.efs
Class SrcParams

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

public final class SrcParams
extends java.lang.Object

Per-source gatherer parameters. These override the general parameters where set.

This is immutable.

Attributes are exposed as final fields for simplicity.

Field Summary

static java.lang.Number	DEFAULT_ENTROPYEST Default value of fetchTimeEntropyBits; assume a modest 1 bit from the whole input.
static boolean	DEFAULT_ISEXPENSIVE Default value of `isExpensive' attribute.
static boolean	DEFAULT_ISSECURE Default value of `isSecure' attribute.
static boolean	DEFAULT_SEEKFROMEND Default value of `seek-from-end' attribute.
java.lang.String	definition Source description/definition string; never null nor zero-length.
static java.lang.String	definition_pName Property name /attribute for source definition string.
java.lang.Number	entropyBits If less than 1.0 the number of entropy bits per input bit, else total entropy bits per fetch; non-null, non-negative.
static byte	ES_FILE Indicates a file-based entropy source.
static byte	ES_INT Indicates internal seed-bit-generator entropy source.
static byte	ES_PROC Indicates a process-based entropy source.
static byte	ES_SR Indicates a SecureRandom seed-bit-generator entropy source.
static byte	ES_URL Indicates an URL-based entropy source.
int	fetchTimeEntropyBits Number of estimated entropy bits in fetch time itself; non-negative.
static java.lang.String	FILE_DESC_SPECIAL Special file source definition value that invites poking around in filesystem...
GenParams	gParams Generic parameters; never null.
boolean	isExpensive If true, source is expensive and should not be used during bootup.
boolean	isSecure If true, source is secure and private from outside inspection.
int	maxBytesFromEntropySource Maximum bytes to fetch each time from source; non-negative.
int	maxDataReadTimeMs Minimum time allowed to fetch data on each run; strictly positive.
int	maxRefetchIntervalMs Maximum interval between fetches in milliseconds, even after errors; non-negative.
int	minBytesChange Minimum bytes that must change between runs to count entropy; non-negative.
int	minRefetchIntervalMs Minimum interval between fetches in milliseconds; non-negative.
static java.lang.String	PNAME__SRCPARAMS Generic top-level property (attribute) name for SrcParams.
static java.lang.String	PNAME_ENTROPYEST Property (and printable) name for fetchTimeEntropyBits.
static java.lang.String	PNAME_FILE Property (and printable) name of file-based entropy source.
static java.lang.String	PNAME_INT Property (and printable) name of internal seed-bit-generator entropy source.
static java.lang.String	PNAME_ISEXPENSIVE Property (and printable) name for isExpensive.
static java.lang.String	PNAME_ISSECURE Property (and printable) name for isSecure.
static java.lang.String	PNAME_MAXBYTES Property (and printable) name for maxBytesFromEntropySource.
static java.lang.String	PNAME_MAXREADTIME Property (and printable) name for maxDataReadTimeMs.
static java.lang.String	PNAME_MAXREFETCH Property (and printable) name for maxRefetchIntervalMs.
static java.lang.String	PNAME_MINBYTESCHANGE Property (and printable) name for minBytesChange.
static java.lang.String	PNAME_MINREFETCH Property (and printable) name for minRefetchIntervalMs.
static java.lang.String	PNAME_PROC Property (and printable) name of process-based entropy source.
static java.lang.String	PNAME_SEEKFROMEND Property (and printable) name for seek direction.
static java.lang.String	PNAME_SR Property (and printable) name of SecureRandom seed-bit-generator entropy source.
static java.lang.String	PNAME_URL Property (and printable) name of URL-based entropy source.
boolean	seekFromEnd If true and source is seekable, take bytes from end of source.
byte	sourceType Source type; EC_XXX value.
static java.lang.String	sourceType_pName Property name/attribute for source type (as String).
byte	usefulDays Bit pattern for days (GMT/UTC) that the source is useful; bit 0 is Sunday, bit 6 is Saturday.
int	usefulHours Bit pattern for hours (GMT/UTC) that the source is useful; bit 0 is 00XX, 1 is 01XX, etc.

Constructor Summary

SrcParams(GenParams _gParams, byte _sourceType, java.lang.String _definition, boolean _isSecure, boolean _isExpensive, java.lang.Number _entropyBits, int _fetchTimeEntropyBits, int _maxBytesFromEntropySource, int _minRefetchIntervalMs, int _maxDataReadTimeMs, int _maxRefetchIntervalMs, byte _usefulDays, int _usefulHours, boolean _seekFromEnd, int _minBytesChange)
Make an entropy gatherer definition.

Method Summary

static SrcParams	makeSpecialFileSource(GenParams gp) Returns a ready-made source definition for the `special' file source.
static SrcParams	parseSrcParams(GenParams gp, java.util.Properties p, java.lang.String prefix, java.lang.String sourceName) Retrieve SrcParams from Properties.
java.lang.String	toString() Generate human-readable concise (single-line) form.

Methods inherited from class java.lang.Object

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

Field Detail

ES_URL

public static final byte ES_URL

Indicates an URL-based entropy source.

See Also:

Constant Field Values

PNAME_URL

public static final java.lang.String PNAME_URL

Property (and printable) name of URL-based entropy source.

See Also:

Constant Field Values

ES_PROC

public static final byte ES_PROC

Indicates a process-based entropy source.

See Also:

Constant Field Values

PNAME_PROC

public static final java.lang.String PNAME_PROC

Property (and printable) name of process-based entropy source.

See Also:

Constant Field Values

ES_FILE

public static final byte ES_FILE

Indicates a file-based entropy source.

See Also:

Constant Field Values

PNAME_FILE

public static final java.lang.String PNAME_FILE

Property (and printable) name of file-based entropy source.

See Also:

Constant Field Values

ES_SR

public static final byte ES_SR

Indicates a SecureRandom seed-bit-generator entropy source.

See Also:

Constant Field Values

PNAME_SR

public static final java.lang.String PNAME_SR

Property (and printable) name of SecureRandom seed-bit-generator entropy source.

See Also:

Constant Field Values

ES_INT

public static final byte ES_INT

Indicates internal seed-bit-generator entropy source.

See Also:

Constant Field Values

PNAME_INT

public static final java.lang.String PNAME_INT

Property (and printable) name of internal seed-bit-generator entropy source.

See Also:

Constant Field Values

FILE_DESC_SPECIAL

public static final java.lang.String FILE_DESC_SPECIAL

Special file source definition value that invites poking around in filesystem...

See Also:

Constant Field Values

PNAME__SRCPARAMS

public static final java.lang.String PNAME__SRCPARAMS

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

See Also:

Constant Field Values

gParams

public final GenParams gParams

Generic parameters; never null.

sourceType

public final byte sourceType

Source type; EC_XXX value.

sourceType_pName

public static final java.lang.String sourceType_pName

Property name/attribute for source type (as String).

See Also:

Constant Field Values

definition

public final java.lang.String definition

Source description/definition string; never null nor zero-length.

definition_pName

public static final java.lang.String definition_pName

Property name /attribute for source definition string.

See Also:

Constant Field Values

DEFAULT_ISSECURE

public static final boolean DEFAULT_ISSECURE

Default value of `isSecure' attribute.

See Also:

Constant Field Values

PNAME_ISSECURE

public static final java.lang.String PNAME_ISSECURE

Property (and printable) name for isSecure.

See Also:

Constant Field Values

isSecure

public final boolean isSecure

If true, source is secure and private from outside inspection.

DEFAULT_ISEXPENSIVE

public static final boolean DEFAULT_ISEXPENSIVE

Default value of `isExpensive' attribute.

See Also:

Constant Field Values

PNAME_ISEXPENSIVE

public static final java.lang.String PNAME_ISEXPENSIVE

Property (and printable) name for isExpensive.

See Also:

Constant Field Values

isExpensive

public final boolean isExpensive

If true, source is expensive and should not be used during bootup.

entropyBits

public final java.lang.Number entropyBits

If less than 1.0 the number of entropy bits per input bit, else total entropy bits per fetch; non-null, non-negative.

DEFAULT_ENTROPYEST

public static final java.lang.Number DEFAULT_ENTROPYEST

Default value of fetchTimeEntropyBits; assume a modest 1 bit from the whole input.

PNAME_ENTROPYEST

public static final java.lang.String PNAME_ENTROPYEST

Property (and printable) name for fetchTimeEntropyBits.

See Also:

Constant Field Values

fetchTimeEntropyBits

public final int fetchTimeEntropyBits

Number of estimated entropy bits in fetch time itself; non-negative.

PNAME_MAXBYTES

public static final java.lang.String PNAME_MAXBYTES

Property (and printable) name for maxBytesFromEntropySource.

See Also:

Constant Field Values

maxBytesFromEntropySource

public final int maxBytesFromEntropySource

Maximum bytes to fetch each time from source; non-negative.

PNAME_MINREFETCH

public static final java.lang.String PNAME_MINREFETCH

Property (and printable) name for minRefetchIntervalMs.

See Also:

Constant Field Values

minRefetchIntervalMs

public final int minRefetchIntervalMs

Minimum interval between fetches in milliseconds; non-negative.

PNAME_MAXREADTIME

public static final java.lang.String PNAME_MAXREADTIME

Property (and printable) name for maxDataReadTimeMs.

See Also:

Constant Field Values

maxDataReadTimeMs

public final int maxDataReadTimeMs

Minimum time allowed to fetch data on each run; strictly positive.

PNAME_MAXREFETCH

public static final java.lang.String PNAME_MAXREFETCH

Property (and printable) name for maxRefetchIntervalMs.

See Also:

Constant Field Values

maxRefetchIntervalMs

public final int maxRefetchIntervalMs

Maximum interval between fetches in milliseconds, even after errors; non-negative.

usefulDays

public final byte usefulDays

Bit pattern for days (GMT/UTC) that the source is useful; bit 0 is Sunday, bit 6 is Saturday.

usefulHours

public final int usefulHours

Bit pattern for hours (GMT/UTC) that the source is useful; bit 0 is 00XX, 1 is 01XX, etc.

DEFAULT_SEEKFROMEND

public static final boolean DEFAULT_SEEKFROMEND

Default value of `seek-from-end' attribute.

See Also:

Constant Field Values

PNAME_SEEKFROMEND

public static final java.lang.String PNAME_SEEKFROMEND

Property (and printable) name for seek direction.

See Also:

Constant Field Values

seekFromEnd

public final boolean seekFromEnd

If true and source is seekable, take bytes from end of source.

PNAME_MINBYTESCHANGE

public static final java.lang.String PNAME_MINBYTESCHANGE

Property (and printable) name for minBytesChange.

See Also:

Constant Field Values

minBytesChange

public final int minBytesChange

Minimum bytes that must change between runs to count entropy; non-negative.

Constructor Detail

SrcParams

public SrcParams(GenParams _gParams,
                 byte _sourceType,
                 java.lang.String _definition,
                 boolean _isSecure,
                 boolean _isExpensive,
                 java.lang.Number _entropyBits,
                 int _fetchTimeEntropyBits,
                 int _maxBytesFromEntropySource,
                 int _minRefetchIntervalMs,
                 int _maxDataReadTimeMs,
                 int _maxRefetchIntervalMs,
                 byte _usefulDays,
                 int _usefulHours,
                 boolean _seekFromEnd,
                 int _minBytesChange)

Make an entropy gatherer definition.

Parameters:

_gParams - is the set of general parameters used as defaults (non null)

_sourceType - is the type of the source (ES_URL, ES_PROC, ES_FILE)

_definition - is the source definition (non-null, non-zero-length) (http/https URL, command line, filename)

_isSecure - if true, the source is private and secure, else it might be observed or predicted by an adversary; note that secure may have to mean not visible to anyone but the user running the JVM for very sensitive applications, or it might include anything that someone in your company or a user on the host for this JVM might see

_isExpensive - if true, source is expensive and should not be used excessively, eg during startup, until _minRefetchIntervalMs has passed

_entropyBits - if 0 then no entropy is expected from the source data, if between 0.0 and 1.0 exclusive then this is the bits of expected entropy per input bit, if 1 or greater then total bits of expected entropy in input (if not secure than figure given here is multiplied by gParams.insecureEntropyMultiplier) (non-negative)

_fetchTimeEntropyBits - is estimated number of bits of entropy available from jitter in fetch time (non-negative)

_maxBytesFromEntropySource - limit on number of bytes to read from any one entropy source on any one run if non-positive then the _gParams value is used;

_minRefetchIntervalMs - interval in milliseconds before revisiting an entropy source to fetch more data; if negative then the _gParams value is used

_maxDataReadTimeMs - 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; if non-positive then the _gParams value is used

_usefulDays - is days of week input is useful (one bit indicates valid that day; 0x7f or -1 is all); bit 0 (==1) is Sunday, bit 1 (==2) is Monday, to bit 6 (64) is Saturday

_usefulHours - is hours of useful hours (GMT/UTC) that input is useful (one bit indicates valid 0xffffff or -1); bit 0 (==1) is 00XX GMT, bit 1 (==2) is 01XX GMT, to bit 23XX is 23 GMT

_seekFromEnd - if true and input is seekable (usually a file), take input from end of data stream

_minBytesChange - if positive is the minimum number of bytes that must change from one one to the next for any entropy to be counted; this can be valuable to ignore small changes, for example from embedded `time now' dates embedded in the results

Method Detail

toString

public java.lang.String toString()

Generate human-readable concise (single-line) form.

Overrides:

toString in class java.lang.Object

makeSpecialFileSource

public static SrcParams makeSpecialFileSource(GenParams gp)

Returns a ready-made source definition for the `special' file source. This source uses a number of tricks to try and suck entropy in from the OS through the Java APIs.

It may prove especially useful at gathering system-specific state on its first run to help make the initial state of the entropy pool difficult to guess, but tries to pick up maybe a bit or two of entropy from the timing of file creation on each run. This is modest about how much entropy it actually claims to add each time.

Since we might actually add a small amount of disc wear-and-tear we don't run all that often.

parseSrcParams

public static SrcParams parseSrcParams(GenParams gp,
                                       java.util.Properties p,
                                       java.lang.String prefix,
                                       java.lang.String sourceName)

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

     srcParams.sourceName.srcAttributeName
 

else they are of the form:

     prefix.srcParams.sourceName.srcAttributeName
 

At least the source type and definition must be supplied (and non-empty).

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:

SrcParams object;

Throws:

java.lang.IllegalArgumentException - if any of the parameters specified by the properties is invalid or unusable or no definition for the given source can be found