1Net::Random(3)        User Contributed Perl Documentation       Net::Random(3)
2
3
4

NAME

6       Net::Random - get random data from online sources
7

SYNOPSIS

9         my $rand = Net::Random->new( # use fourmilab.ch's randomness source,
10           src => 'fourmilab.ch',     # and return results from 1 to 2000
11           min => 1,
12           max => 2000
13         );
14         @numbers = $rand->get(5);    # get 5 numbers
15
16         my $rand = Net::Random->new( # use qrng.anu.edu.au's randomness source,
17           src => 'qrng.anu.edu.au',  # with no explicit range - so values will
18         );                           # be in the default range from 0 to 255
19
20         my $rand = Net::Random->new( # use random.org's randomness source,
21           src => 'random.org',
22         );
23
24         $number = $rand->get();      # get 1 random number
25

OVERVIEW

27       The three sources of randomness above correspond to
28       <https://www.fourmilab.ch/cgi-bin/uncgi/Hotbits?nbytes=1024&fmt=hex>,
29       <https://random.org/cgi-bin/randbyte?nbytes=1024&format=hex> and
30       <https://qrng.anu.edu.au/API/jsonI.php?length=1024&size=1&type=uint8>.
31       We always get chunks of 1024 bytes at a time, storing it in a pool
32       which is used up as and when needed.  The pool is shared between all
33       objects using the same randomness source.  When we run out of
34       randomness we go back to the source for more juicy random goodness.
35
36       If you have set a http_proxy variable in your environment, this will be
37       honoured.
38
39       While we always fetch 1024 bytes, data can be used up one, two, three
40       or four bytes at a time, depending on the range between the minimum and
41       maximum desired values.  There may be a noticeable delay while more
42       random data is fetched.
43
44       The maintainers of all the randomness sources claim that their data is
45       *truly* random.  A some simple tests show that they are certainly more
46       random than the rand() function on this 'ere machine.
47

METHODS

49       new The constructor returns a Net::Random object.  It takes named
50           parameters, of which one - 'src' - is compulsory, telling the
51           module where to get its random data from.  The 'min' and 'max'
52           parameters are optional, and default to 0 and 255 respectively.
53           Both must be integers, and 'max' must be at least min+1.  The
54           maximum value of 'max' is 2^32-1, the largest value that can be
55           stored in a 32-bit int, or 0xFFFFFFFF.  The range between min and
56           max can not be greater than 0xFFFFFFFF either.
57
58           You may also set 'ssl' to 0 if you wish to retrieve data using
59           plaintext (or outbound SSL is prohibited in your network
60           environment for some reason)
61
62           Currently, the only valid values of 'src' are 'qrng.anu.edu.au',
63           'fourmilab.ch' and 'random.org'.
64
65       get Takes a single optional parameter, which must be a positive
66           integer.  This determines how many random numbers are to be
67           returned and, if not specified, defaults to 1.
68
69           If it fails to retrieve data, we return undef.  Note that
70           random.org and fourmilab.ch ration their random data.  If you hit
71           your quota, we spit out a warning.  See the section on ERROR
72           HANDLING below.
73
74           Be careful with context. If you call it in list context, you'll
75           always get a list of results back, even if you only ask for one. If
76           you call it in scalar context you'll either get back a random
77           number if you asked for one result, or an array-ref if you asked
78           for multiple results.
79

BUGS

81       Doesn't handle really BIGNUMs.  Patches are welcome to make it use
82       Math::BigInt internally.  Note that you'll need to calculate how many
83       random bytes to use per result.  I strongly suggest only using BigInts
84       when absolutely necessary, because they are slooooooow.
85
86       Tests are a bit lame.  Really needs to test the results to make sure
87       they're as random as the input (to make sure I haven't introduced any
88       bias).
89

SECURITY CONCERNS

91       True randomness is very useful for cryptographic applications.
92       Unfortunately, I can not recommend using this module to produce such
93       random data.  While some simple testing shows that we can be fairly
94       confident that it is random, and the published methodologies on all the
95       sites used looks sane, you can not, unfortunately, trust that you are
96       getting unique data (ie, someone else might get the same bytes as you),
97       that they don't log who gets what data, or that no-one is intercepting
98       it en route to surreptitiously make a copy..
99
100       Be aware that if you use an http_proxy - or if your upstream uses a
101       transparent proxy like some of the more shoddy consumer ISPs do - then
102       that is another place that your randomness could be compromised.  Even
103       if using https a sophisticated attacker may be able to intercept your
104       data, because I make no effort to verify the sources' SSL certificates
105       (I'd love to receive a patch to do this) and even if I did, there have
106       been cases when trusted CAs issued bogus certificates, which could be
107       used in MITM attacks.
108
109       I should stress that I *do* trust all the site maintainers to give me
110       data that is sufficiently random and unique for my own uses, but I can
111       not recommend that you do too.  As in any security situation, you need
112       to perform your own risk analysis.
113

ERROR HANDLING

115       There are two types of error that this module can emit which aren't
116       your fault.  Those are network errors, in which case it emits a
117       warning:
118
119         Net::Random: Error talking to [your source]
120
121       and errors generated by the randomness sources, which look like:
122
123         Net::Random: [your source] [message]
124
125       Once you hit either of these errors, it means that either you have run
126       out of randomness and can't get any more, or you are very close to
127       running out of randomness.  Because this module's raison d'&ecirc;tre
128       is to provide a source of truly random data when you don't have your
129       own one available, it does not provide any pseudo-random fallback.
130
131       If you want to implement your own fallback, you can catch those
132       warnings by using $SIG{__WARN__}.  See "perldoc perlvar" for details.
133

FEEDBACK

135       I welcome feedback about my code, especially constructive criticism.
136
138       Copyright 2003 - 2012 David Cantrell <david@cantrell.org.uk>
139
140       This software is free-as-in-speech software, and may be used,
141       distributed, and modified under the terms of either the GNU General
142       Public Licence version 2 or the Artistic Licence. It's up to you which
143       one you use. The full text of the licences can be found in the files
144       GPL2.txt and ARTISTIC.txt, respectively.
145

THANKS TO

147       Thanks are also due to the maintainers of the randomness sources.  See
148       their web sites for details on how to praise them.
149
150       Suggestions from the following people have been included:
151
152       Rich Rauenzahn
153           Suggested I allow use of an http_proxy;
154
155       Wiggins d Anconia
156           Suggested I mutter in the docs about security concerns;
157
158       Syed Assad
159           Suggested that I use the JSON interface for QRNG instead of
160           scraping the web site;
161
162       And patches from:
163
164       Mark Allen
165           code for using SSL;
166
167       Steve Wills
168           code for talking to qrng.anu.edu.au;
169

CONSPIRACY

171       This module is also free-as-in-mason software.
172
173
174
175perl v5.38.0                      2023-07-21                    Net::Random(3)
Impressum