NAME

SYNOPSIS

  my $rand = Net::Random->new( # use fourmilab.ch's randomness source,
    src => 'fourmilab.ch',     # and return results from 1 to 2000
    min => 1,
    max => 2000
  );
  @numbers = $rand->get(5);    # get 5 numbers

  my $rand = Net::Random->new( # use qrng.anu.edu.au's randomness source,
    src => 'qrng.anu.edu.au',  # with no explicit range - so values will
  );                           # be in the default range from 0 to 255

  my $rand = Net::Random->new( # use random.org's randomness source,
    src => 'random.org',
  );

  $number = $rand->get();      # get 1 random number

OVERVIEW

If you have set a http_proxy variable in your environment, this will be honoured.

While we always fetch 1024 bytes, data can be used up one, two, three or four bytes at a time, depending on the range between the minimum and maximum desired values. There may be a noticeable delay while more random data is fetched.

The maintainers of all the randomness sources claim that their data is *truly* random. A some simple tests show that they are certainly more random than the "rand()" function on this 'ere machine.

METHODS

new

The constructor returns a Net::Random object. It takes named parameters, of which one - 'src' - is compulsory, telling the module where to get its random data from. The 'min' and 'max' parameters are optional, and default to 0 and 255 respectively. Both must be integers, and 'max' must be at least min+1. The maximum value of 'max' is 2^32-1, the largest value that can be stored in a 32-bit int, or 0xFFFFFFFF. The range between min and max can not be greater than 0xFFFFFFFF either.

You may also set 'ssl' to 0 if you wish to retrieve data using plaintext (or outbound SSL is prohibited in your network environment for some reason)

Currently, the only valid values of 'src' are 'qrng.anu.edu.au', 'fourmilab.ch' and 'random.org'.

get

Takes a single optional parameter, which must be a positive integer. This determines how many random numbers are to be returned and, if not specified, defaults to 1.

If it fails to retrieve data, we return undef. Note that random.org and fourmilab.ch ration their random data. If you hit your quota, we spit out a warning. See the section on ERROR HANDLING below.

Be careful with context. If you call it in list context, you'll always get a list of results back, even if you only ask for one. If you call it in scalar context you'll either get back a random number if you asked for one result, or an array-ref if you asked for multiple results.

BUGS

Tests are a bit lame. Really needs to test the results to make sure they're as random as the input (to make sure I haven't introduced any bias).

SECURITY CONCERNS

Be aware that if you use an http_proxy - or if your upstream uses a transparent proxy like some of the more shoddy consumer ISPs do - then that is another place that your randomness could be compromised. Even if using https a sophisticated attacker may be able to intercept your data, because I make no effort to verify the sources' SSL certificates (I'd love to receive a patch to do this) and even if I did, there have been cases when trusted CAs issued bogus certificates, which could be used in MITM attacks.

I should stress that I *do* trust all the site maintainers to give me data that is sufficiently random and unique for my own uses, but I can not recommend that you do too. As in any security situation, you need to perform your own risk analysis.

ERROR HANDLING

  Net::Random: Error talking to [your source]

and errors generated by the randomness sources, which look like:

  Net::Random: [your source] [message]

Once you hit either of these errors, it means that either you have run out of randomness and can't get any more, or you are very close to running out of randomness. Because this module's raison d'être is to provide a source of truly random data when you don't have your own one available, it does not provide any pseudo-random fallback.

If you want to implement your own fallback, you can catch those warnings by using $SIG{__WARN__}. See "perldoc perlvar" for details.

FEEDBACK

AUTHOR, COPYRIGHT and LICENCE

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

THANKS TO

Suggestions from the following people have been included:

Rich Rauenzahn

Suggested I allow use of an http_proxy;

Wiggins d Anconia

Suggested I mutter in the docs about security concerns;

Syed Assad

Suggested that I use the JSON interface for QRNG instead of scraping the web site;

And patches from:

Mark Allen

code for using SSL;

Steve Wills

code for talking to qrng.anu.edu.au;

CONSPIRACY