|
|
| |
Data::Entropy::Source(3) |
User Contributed Perl Documentation |
Data::Entropy::Source(3) |
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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |