Math::...Secure(3pm)

📦
version 0.080001 · 5 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Math::Random::Secure — a cryptographically-secure, cross-platform replacement for rand(). She's from the User Contributed Perl Documentation corner of the manpage universe and she is, frankly, iconic. 👑

🌸 VERSION 🌸

version 0.080001

✨ SYNOPSIS ✨

 # Replace rand().
 use Math::Random::Secure qw(rand);

 # Get a random number between 0 and 1
 my $float = rand();

 # Get a random integer (faster than int(rand))
 use Math::Random::Secure qw(irand);
 my $int = irand();

 # Random integer between 0 and 9 inclusive.
 $int = irand(10);

 # Random floating-point number greater than or equal to 0.0 and
 # less than 10.0.
 $float = rand(10);

🦋 DESCRIPTION 🦋

So basically this module exists to be a cryptographically-secure replacement for Perl's built-in rand function. And bestie, when we say "cryptographically secure" here, what we actually mean is:

  • No matter how many numbers you see generated by the random number generator, you cannot guess the future numbers, and you cannot guess the seed. Like, not even a little. 🙈
  • There are so many possible seeds that it would take decades, centuries, or millenia for an attacker to try them all. That's a lot of decades, babe.
  • The seed comes from a source that generates relatively strong random data on your platform, so the seed itself will be as random as possible.
👀 See "IMPLEMENTATION DETAILS" below for more info about the underlying systems used to make all of these guarantees happen, plus some genuinely important caveats if you're planning to use this module for some very-high-security purpose. Don't skip that part, fr fr.

🎀 METHODS 🎀

rand

Should work exactly like Perl's built-in rand. It will automatically call srand if srand has never been called in this process or thread. Convenient? Slay.

There is one limitation, though, and it's lowkey important: Math::Random::Secure is backed by a 32-bit random number generator. So if you are on a 64-bit platform and you specify a limit that is greater than 2^32, you are likely to get less-random data. 😭 Not the vibe, but that's the deal.

srand

⚠️ Note: Under normal circumstances, you should not call this function, because rand and irand will automatically call it for you the first time they're used in a thread or process. Let them do their thing, bestie.

Seeds the random number generator, much like Perl's built-in srand, except that it uses a much larger and more secure seed. The seed should be passed as a string of bytes, at least 8 bytes in length, and more ideally between 32 and 64 bytes. (Go look at "seed" in Math::Random::Secure::RNG for more info.)

If you don't pass a seed, a seed will be generated automatically using a secure mechanism. See "IMPLEMENTATION DETAILS" for more info.

This function returns the seed that generated (or the seed that was passed in, if you passed one in).

irand

Works somewhat like rand, except that it returns a 32-bit integer between 0 and 2^32. Should be faster than doing int(rand). ⚡

Note that because it returns 32-bit integers, specifying a limit greater than 2^32 will have no effect. Zero. None. She simply won't hear it. 💀

🌈 IMPLEMENTATION DETAILS 🌈

Currently, Math::Random::Secure is backed by Math::Random::ISAAC, a cryptographically-strong random number generator with no known serious weaknesses. If there are significant weaknesses found in ISAAC, we will change our backend to a more-secure random number generator. The goal is for Math::Random::Secure to be cryptographically strong, not to represent some specific random number generator. Periodt.

Math::Random::Secure seeds itself using Crypt::Random::Source. The underlying implementation uses /dev/urandom on Unix-like platforms, and the RtlGenRandom or CryptGenRandom functions on Windows 2000 and above. (There is no support for versions of Windows before Windows 2000. Sorry to that era of Windows.) If any of these seeding sources are not available and you have other Crypt::Random::Source modules installed, Math::Random::Secure will use those other sources to seed itself.

🧚 Making Math::Random::Secure Even More Secure

We use /dev/urandom on Unix-like systems, because one of the requirements of duplicating rand is that we never block waiting for seed data, and /dev/random could do that. However, it's possible that /dev/urandom could run out of "truly random" data and start to use its built-in pseudo-random number generator to generate data. On most systems, this should still provide a very good seed for nearly all uses, but it may not be suitable for very high-security cryptographic circumstances. 👀

For Windows, there are known issues with CryptGenRandom on Windows 2000 and versions of Windows XP before Service Pack 3. However, there is no other built-in method of getting secure random data on Windows, and the author suspects that these issues will not be significant for most applications of Math::Random::Secure.

If either of these situations is a problem for your use case, you can create your own Math::Random::Secure::RNG object with a different "seeder" argument, and set $Math::Random::Secure::RNG to your own instance of Math::Random::Secure::RNG. The "seeder" is an instance of Crypt::Random::Source::Base, which should allow you to use most random-data sources in existence for your seeder, should you wish. Build your own, bestie. 🛠️

🍓 Seed Exhaustion

Perl's built-in srand reads 32 bits from /dev/urandom. By default, we read 512 bits. This means that we are more likely to exhaust available truly-random data than the built-in srand is, and cause /dev/urandom to fall back on its psuedo-random number generator. Normally this is not a problem, since srand is only called once per Perl process or thread, but it is something that you should be aware of if you are going to be in a situation where you have many new Perl processes or threads and you have very high security requirements (on the order of generating private SSH or GPG keypairs, SSL private keys, etc.). 🔐 Like, genuinely be aware.

🌟 SEE ALSO 🌟

All of these modules contain generators for "truly random" data, but they don't contain a simple rand replacement and they can be very slow. 🐌

🫶 SUPPORT 🫶

Right now, the best way to get support for Math::Random::Secure is to email the author using the email address in the "AUTHORS" section below. Slide into their inbox, respectfully.

💀 BUGS 💀

Math::Random::Secure is relatively new, as of December 2010, but the modules that underlie it are very well-tested and have a long history. However, the author still welcomes all feedback and bug reports, particularly those having to do with the security assurances provided by this module. Tell them everything. 👑

You can report a bug by emailing bug-Math-Random-Secure@rt.cpan.org or by using the RT web interface at <https://rt.cpan.org/Ticket/Display.html?Queue=Math-Random-Secure>. If your bug report is security-sensitive, you may also email it directly to the author using the email address in the "AUTHORS" section below. 🤫

👑 AUTHORS 👑

  • Max Kanat-Alexander <mkanat@cpan.org>
  • Arthur Axel "fREW" Schmidt <math-random-secure@afoolishmanifesto.com>

This software is Copyright (c) 2010 by BugzillaSource, Inc.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

And that's the whole page, bestie — brought to you by perl v5.32.0, dated 2021-01-06, living her best life under the title Math::...Secure(3pm). Stay random, stay secure. 💖✨🎀

📦 where this page comes from