1Net::Random(3) User Contributed Perl Documentation Net::Random(3)
2
6 Net::Random - get random data from online sources
7
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 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 my $rand = Net::Random->new( # use random.org's randomness source,
21 src => 'random.org',
22 );
23 $number = $rand->get(); # get 1 random number
25
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 If you have set a http_proxy variable in your environment, this will be
37 honoured.
38 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 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
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 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 Currently, the only valid values of 'src' are 'qrng.anu.edu.au',
63 'fourmilab.ch' and 'random.org'.
64 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 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 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
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 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
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 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 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
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 Net::Random: Error talking to [your source]
120 and errors generated by the randomness sources, which look like:
122 Net::Random: [your source] [message]
124 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'ê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 If you want to implement your own fallback, you can catch those
132 warnings by using $SIG{__WARN__}. See "perldoc perlvar" for details.
133
135 I welcome feedback about my code, especially constructive criticism.
136
138 Copyright 2003 - 2012 David Cantrell <david@cantrell.org.uk>
139 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
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 Suggestions from the following people have been included:
151 Rich Rauenzahn
153 Suggested I allow use of an http_proxy;
154 Wiggins d Anconia
156 Suggested I mutter in the docs about security concerns;
157 Syed Assad
159 Suggested that I use the JSON interface for QRNG instead of
160 scraping the web site;
161 And patches from:
163 Mark Allen
165 code for using SSL;
166 Steve Wills
168 code for talking to qrng.anu.edu.au;
169
171 This module is also free-as-in-mason software.
172perl v5.38.0 2023-07-21 Net::Random(3)