.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Entropy::Source 3pm"
.TH Data::Entropy::Source 3pm "2021-01-01" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Entropy::Source \- encapsulated source of entropy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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.
.PP
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 \fB/dev/random\fR devices on some versions of Unix constitute
such a source, for example.  The raw entropy source is accessed
via the \f(CW\*(C`IO::Handle\*(C'\fR interface.  This interface may be supplied by
classes other than \f(CW\*(C`IO::Handle\*(C'\fR itself, as is done for example by
\&\f(CW\*(C`Data::Entropy::RawSource::CryptCounter\*(C'\fR.
.PP
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 \f(CW\*(C`get_\*(C'\fR 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.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "Data::Entropy::Source\->new(\s-1RAW_SOURCE, READ_STYLE\s0)" 4
.IX Item "Data::Entropy::Source->new(RAW_SOURCE, READ_STYLE)"
Constructs and returns an entropy source object based on the given raw
source.  \s-1RAW_SOURCE\s0 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 \f(CW\*(C`getc\*(C'\fR or \f(CW\*(C`sysread\*(C'\fR method described in IO::Handle.
\&\s-1READ_STYLE\s0 must be a string, either \*(L"getc\*(R" or \*(L"sysread\*(R", 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 \f(CW\*(C`IO::Handle\*(C'\fR is not required.
.Sp
The \f(CW\*(C`sysread\*(C'\fR method should be used with \fB/dev/random\fR and its ilk,
because buffering would be very wasteful of entropy and might consequently
block other processes that require entropy.  \f(CW\*(C`getc\*(C'\fR 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.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$source\->get_octet" 4
.el .IP "\f(CW$source\fR\->get_octet" 4
.IX Item "$source->get_octet"
Returns an octet of entropy, as a string of length one.  This provides
direct access to the raw entropy source.
.ie n .IP "$source\->get_bits(\s-1NBITS\s0)" 4
.el .IP "\f(CW$source\fR\->get_bits(\s-1NBITS\s0)" 4
.IX Item "$source->get_bits(NBITS)"
Returns \s-1NBITS\s0 bits of entropy, as a string of octets.  If \s-1NBITS\s0 is
not a multiple of eight then the last octet in the string has its most
significant bits set to zero.
.ie n .IP "$source\->get_int(\s-1LIMIT\s0)" 4
.el .IP "\f(CW$source\fR\->get_int(\s-1LIMIT\s0)" 4
.IX Item "$source->get_int(LIMIT)"
\&\s-1LIMIT\s0 must be a positive integer.  Returns a uniformly-distributed
random number between zero inclusive and \s-1LIMIT\s0 exclusive.  \s-1LIMIT\s0 may be
either a native integer, a \f(CW\*(C`Math::BigInt\*(C'\fR object, or an integer-valued
\&\f(CW\*(C`Math::BigRat\*(C'\fR object; the returned number is of the same type.
.Sp
This method dispenses a non-integer number of bits of entropy.
For example, if \s-1LIMIT\s0 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 \s-1LIMIT\s0 = 2.
.ie n .IP "$source\->get_prob(\s-1PROB0, PROB1\s0)" 4
.el .IP "\f(CW$source\fR\->get_prob(\s-1PROB0, PROB1\s0)" 4
.IX Item "$source->get_prob(PROB0, PROB1)"
\&\s-1PROB0\s0 and \s-1PROB1\s0 must be non-negative integers, not both zero.
They may each be either a native integer, a \f(CW\*(C`Math::BigInt\*(C'\fR object,
or an integer-valued \f(CW\*(C`Math::BigRat\*(C'\fR objects; types may be mixed.
Returns either 0 or 1, with relative probabilities \s-1PROB0\s0 and \s-1PROB1.\s0
That is, the probability of returning 0 is \s-1PROB0/\s0(\s-1PROB0+PROB1\s0), and the
probability of returning 1 is \s-1PROB1/\s0(\s-1PROB0+PROB1\s0).
.Sp
This method dispenses a fraction of a bit of entropy.  The maximum
amount of entropy that can be obtained is 1 bit, with \s-1PROB0\s0 = \s-1PROB1.\s0
The more different the probabilities are the less entropy is obtained.
For example, if \s-1PROB0\s0 = 1 and \s-1PROB1\s0 = 2 then the result contains
approximately 0.918 bits of entropy.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Entropy,
Data::Entropy::Algorithms,
Data::Entropy::RawSource::CryptCounter,
Data::Entropy::RawSource::Local,
Data::Entropy::RawSource::RandomOrg,
IO::Handle
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006, 2007, 2009, 2011
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.