Data::Entropy::Source - encapsulated source of entropy

use Data::Entropy::Source;
$source = Data::Entropy::Source->new($handle, "sysread");
$c = $source->get_octet;
$str = $source->get_bits(17);
$i = $source->get_int(12345);
$i = $source->get_int(Math::BigInt->new("1000000000000"));
$j = $source->get_prob(1, 2);

An object of this class encapsulates a source of entropy (randomness). Methods
allow entropy to be dispensed in any quantity required, even fractional bits.
An entropy source object should not normally be used directly. Rather, it
should be used to support higher-level entropy-consuming algorithms, such as
those in Data::Entropy::Algorithms.

This type of object is constructed as a layer over a raw entropy source which
does not supply methods to extract arbitrary amounts of entropy. The raw
entropy source is expected to dispense only entire octets at a time. The

**/dev/random** devices on some versions of Unix constitute such a source,
for example. The raw entropy source is accessed via the "IO::Handle"
interface. This interface may be supplied by classes other than
"IO::Handle" itself, as is done for example by
"Data::Entropy::RawSource::CryptCounter".

If two entropy sources of this class are given exactly the same raw entropy
data, for example by reading from the same file, and exactly the same sequence
of "get_" method calls is made to them, then they will return
exactly the same values from those calls. (Calls with numerical arguments that
have the same numerical value but are of different types count as the same for
this purpose.) This means that a run of an entropy-using algorithm can be made
completely deterministic if desired.

- Data::Entropy::Source->new(RAW_SOURCE, READ_STYLE)
- Constructs and returns an entropy source object based on
the given raw source. RAW_SOURCE must be an I/O handle referring to a
source of entropy that can be read one octet at a time. Specifically, it
must support either the "getc" or "sysread" method
described in IO::Handle. READ_STYLE must be a string, either
"getc" or "sysread", indicating which method should be
used to read from the raw source. No methods other than the one specified
will ever be called on the raw source handle, so a full implementation of
"IO::Handle" is not required.

The "sysread" method should be used with **/dev/random** and
its ilk, because buffering would be very wasteful of entropy and might
consequently block other processes that require entropy. "getc"
should be preferred when reading entropy from a regular file, and it is
the more convenient interface to implement when a non-I/O object is being
used for the handle.

- $source->get_octet
- Returns an octet of entropy, as a string of length one.
This provides direct access to the raw entropy source.

- $source->get_bits(NBITS)
- Returns NBITS bits of entropy, as a string of octets. If
NBITS is not a multiple of eight then the last octet in the string has its
most significant bits set to zero.

- $source->get_int(LIMIT)
- LIMIT must be a positive integer. Returns a
uniformly-distributed random number between zero inclusive and LIMIT
exclusive. LIMIT may be either a native integer, a
"Math::BigInt" object, or an integer-valued
"Math::BigRat" object; the returned number is of the same type.

This method dispenses a non-integer number of bits of entropy. For example,
if LIMIT is 10 then the result contains approximately 3.32 bits of
entropy. The minimum non-zero amount of entropy that can be obtained is 1
bit, with LIMIT = 2.

- $source->get_prob(PROB0, PROB1)
- PROB0 and PROB1 must be non-negative integers, not both
zero. They may each be either a native integer, a "Math::BigInt"
object, or an integer-valued "Math::BigRat" objects; types may
be mixed. Returns either 0 or 1, with relative probabilities PROB0 and
PROB1. That is, the probability of returning 0 is PROB0/(PROB0+PROB1), and
the probability of returning 1 is PROB1/(PROB0+PROB1).

This method dispenses a fraction of a bit of entropy. The maximum amount of
entropy that can be obtained is 1 bit, with PROB0 = PROB1. The more
different the probabilities are the less entropy is obtained. For example,
if PROB0 = 1 and PROB1 = 2 then the result contains approximately 0.918
bits of entropy.

Data::Entropy, Data::Entropy::Algorithms,
Data::Entropy::RawSource::CryptCounter, Data::Entropy::RawSource::Local,
Data::Entropy::RawSource::RandomOrg, IO::Handle

Andrew Main (Zefram) <zefram@fysh.org>

Copyright (C) 2006, 2007, 2009, 2011 Andrew Main (Zefram)
<zefram@fysh.org>

This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.