org.hd.d.efs
Class SrcParams

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