1Data::Entropy::Source(3U)ser Contributed Perl DocumentatiDoanta::Entropy::Source(3)
2
3
4

NAME

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

SYNOPSIS

9               use Data::Entropy::Source;
10
11               $source = Data::Entropy::Source->new($handle, "sysread");
12
13               $c = $source->get_octet;
14               $str = $source->get_bits(17);
15               $i = $source->get_int(12345);
16               $i = $source->get_int(Math::BigInt->new("1000000000000"));
17               $j = $source->get_prob(1, 2);
18

DESCRIPTION

20       An object of this class encapsulates a source of entropy (randomness).
21       Methods allow entropy to be dispensed in any quantity required, even
22       fractional bits.  An entropy source object should not normally be used
23       directly.  Rather, it should be used to support higher-level entropy-
24       consuming algorithms, such as those in Data::Entropy::Algorithms.
25
26       This type of object is constructed as a layer over a raw entropy source
27       which does not supply methods to extract arbitrary amounts of entropy.
28       The raw entropy source is expected to dispense only entire octets at a
29       time.  The /dev/random devices on some versions of Unix constitute such
30       a source, for example.  The raw entropy source is accessed via the
31       "IO::Handle" interface.  This interface may be supplied by classes
32       other than "IO::Handle" itself, as is done for example by
33       "Data::Entropy::RawSource::CryptCounter".
34
35       If two entropy sources of this class are given exactly the same raw
36       entropy data, for example by reading from the same file, and exactly
37       the same sequence of "get_" method calls is made to them, then they
38       will return exactly the same values from those calls.  (Calls with
39       numerical arguments that have the same numerical value but are of
40       different types count as the same for this purpose.)  This means that a
41       run of an entropy-using algorithm can be made completely deterministic
42       if desired.
43

CONSTRUCTOR

45       Data::Entropy::Source->new(RAW_SOURCE, READ_STYLE)
46           Constructs and returns an entropy source object based on the given
47           raw source.  RAW_SOURCE must be an I/O handle referring to a source
48           of entropy that can be read one octet at a time.  Specifically, it
49           must support either the "getc" or "sysread" method described in
50           IO::Handle.  READ_STYLE must be a string, either "getc" or
51           "sysread", indicating which method should be used to read from the
52           raw source.  No methods other than the one specified will ever be
53           called on the raw source handle, so a full implementation of
54           "IO::Handle" is not required.
55
56           The "sysread" method should be used with /dev/random and its ilk,
57           because buffering would be very wasteful of entropy and might
58           consequently block other processes that require entropy.  "getc"
59           should be preferred when reading entropy from a regular file, and
60           it is the more convenient interface to implement when a non-I/O
61           object is being used for the handle.
62

METHODS

64       $source->get_octet
65           Returns an octet of entropy, as a string of length one.  This
66           provides direct access to the raw entropy source.
67
68       $source->get_bits(NBITS)
69           Returns NBITS bits of entropy, as a string of octets.  If NBITS is
70           not a multiple of eight then the last octet in the string has its
71           most significant bits set to zero.
72
73       $source->get_int(LIMIT)
74           LIMIT must be a positive integer.  Returns a uniformly-distributed
75           random number between zero inclusive and LIMIT exclusive.  LIMIT
76           may be either a native integer, a "Math::BigInt" object, or an
77           integer-valued "Math::BigRat" object; the returned number is of the
78           same type.
79
80           This method dispenses a non-integer number of bits of entropy.  For
81           example, if LIMIT is 10 then the result contains approximately 3.32
82           bits of entropy.  The minimum non-zero amount of entropy that can
83           be obtained is 1 bit, with LIMIT = 2.
84
85       $source->get_prob(PROB0, PROB1)
86           PROB0 and PROB1 must be non-negative integers, not both zero.  They
87           may each be either a native integer, a "Math::BigInt" object, or an
88           integer-valued "Math::BigRat" objects; types may be mixed.  Returns
89           either 0 or 1, with relative probabilities PROB0 and PROB1.  That
90           is, the probability of returning 0 is PROB0/(PROB0+PROB1), and the
91           probability of returning 1 is PROB1/(PROB0+PROB1).
92
93           This method dispenses a fraction of a bit of entropy.  The maximum
94           amount of entropy that can be obtained is 1 bit, with PROB0 =
95           PROB1.  The more different the probabilities are the less entropy
96           is obtained.  For example, if PROB0 = 1 and PROB1 = 2 then the
97           result contains approximately 0.918 bits of entropy.
98

SEE ALSO

100       Data::Entropy, Data::Entropy::Algorithms,
101       Data::Entropy::RawSource::CryptCounter,
102       Data::Entropy::RawSource::Local, Data::Entropy::RawSource::RandomOrg,
103       IO::Handle
104

AUTHOR

106       Andrew Main (Zefram) <zefram@fysh.org>
107
109       Copyright (C) 2006, 2007, 2009, 2011 Andrew Main (Zefram)
110       <zefram@fysh.org>
111

LICENSE

113       This module is free software; you can redistribute it and/or modify it
114       under the same terms as Perl itself.
115
116
117
118perl v5.34.0                      2022-01-21          Data::Entropy::Source(3)
Impressum