Crypt::...om::Seed(3)

📦

version 0.03 · 7 versions

0.03 · alpine 3.24 (latest)
0.03 · arch rolling
0.03 · fedora 43
0.03 · ubuntu jammy
0.03 · fedora 44
0.03 · ubuntu noble, ubuntu resolute, ubuntu stonking
0.03 · debian bookworm, debian trixie

✨ NAME ✨

okay bestie, welcome to the Crypt::...om::Seed(3) page for Crypt::Random::Seed — User Contributed Perl Documentation, and it's literally all about getting strong randomness. 🫶

Crypt::Random::Seed — Simple method to get strong randomness. That's the whole vibe: a simple way to get a strong seed without spiraling. 💅

🦋 VERSION 🦋

Version 0.03. 🎀

🌈 SYNOPSIS 🌈

Here's the copy-paste mood board, verbatim:

         use Crypt::Random::Seed;

         my $source = new Crypt::Random::Seed;
         die "No strong sources exist" unless defined $source;
         my $seed_string = $source->random_bytes(4);
         my @seed_values = $source->random_values(4);

         # Only non-blocking sources
         my $nonblocking_source = Crypt::Random::Seed->new( NonBlocking=>1 );

         # Blacklist sources (never choose the listed sources)
         my $nowin32_source = Crypt::Random::Seed->new( Never=>['Win32'] );

         # Whitelist sources (only choose from these sources)
         my $devr_source = Crypt::Random::Seed->new( Only=>['TESHA2'] );

         # Supply a custom source.
         my $user_src = Crypt::Random::Seed->new( Source=>sub { myfunc(shift) } );
         # Or supply a list of [name, sub, is_blocking, is_strong]
         $user_src = Crypt::Random::Seed->new(
            Source=>['MyRandomFunction',sub {myfunc(shift)},0,1] );

         # Given a source there are a few things we can do:
         say "My randomness source is ", $source->name();
         say "I am a blocking source" if $source->is_blocking();
         say "I am a strong randomness source" if $source->is_strong()
         say "Four 8-bit numbers:",
             join(",", map { ord $source->random_bytes(1) } 1..4);'
         say "Four 32-bit numbers:", join(",", $source->random_values(4));

💖 DESCRIPTION 💖

Okay so this module gives you a simple mechanism to get strong randomness. Its main purpose is to provide a simple way to generate a seed for a PRNG such as Math::Random::ISAAC, for use in cryptographic key generation, or as the seed for an upstream module such as Bytes::Random::Secure. Flags for requiring non-blocking sources are allowed, and there's also a very simple method for plugging in a source. ✨

The randomness sources used are, in order:

User supplied. If the constructor is called with a Source defined, then it is used. It is not checked vs. other flags (NonBlocking, Never, Only). 🙈
Win32 Crypto API. This will use CryptGenRandom on Windows 2000 and RtlGenRand on Windows XP and newer. According to MSDN, these are well-seeded CSPRNGs (FIPS 186-2 or AES-CTR), so they will be non-blocking. 🔥
EGD / PRNGD. This looks for sockets that speak the EGD protocol (<http://egd.sourceforge.net/>), including PRNGD (<http://prngd.sourceforge.net/>). These are userspace entropy daemons that are commonly used by OpenSSL, OpenSSH, and GnuGP. The locations searched are /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool, and /etc/entropy. EGD is blocking, while PRNGD is non-blocking (like the Win32 API, it is really a seeded CSPRNG). However there is no way to tell them apart, so we treat it as blocking. If your O/S supports /dev/random, consider HAVEGED (<http://www.issihosts.com/haveged/>) as an alternative — a system daemon that refills /dev/random as needed. 🌸
/dev/random. The strong source of randomness on most UNIX-like systems. Cygwin uses this, though it maps to the Win32 API. On almost all systems this is a blocking source of randomness — if it runs out of estimated entropy, it will hang until more has come into the system. If this is an issue, which it often is on embedded devices, running a tool such as HAVEGED (<http://www.issihosts.com/haveged/>) will help immensely. 🫶
/dev/urandom. A nonblocking source of randomness that we label as weak, since it will continue providing output even if the actual entropy has been exhausted. 💀
TESHA2. Crypt::Random::TESHA2 is a Perl module that generates random bytes from an entropy pool fed with timer/scheduler variations. Measurements and tests are performed on installation to determine whether the source is considered strong or weak. This is entirely in portable userspace, which is good for ease of use, but really requires user verification that it is working as expected if we expect it to be strong. The concept is similar to Math::TrulyRandom though updated to something closer to what TrueRand 2.1 does vs. the obsolete version 1 that Math::TrulyRandom implements. It is very slow and has wide speed variability across platforms: the docs say they've seen numbers ranging from 40 to 150,000 bits per second. 😭

A source can also be supplied in the constructor. Each of these sources will have its debatable points about perceived strength. E.g. Why is /dev/urandom considered weak while Win32 is strong? Can any userspace method such as TrueRand or TESHA2 be considered strong? 🤔

🎀 SOURCE TABLE 🎀

This table summarizes the default sources. The columns are SOURCE, STRENGTH, BLOCKING, and NOTE:

RtlGenRandom — STRENGTH: Strong(1); BLOCKING: No; NOTE: Default WinXP+
CryptGenRandom — STRENGTH: Strong(1); BLOCKING: No; NOTE: Default Win2000
EGD — STRENGTH: Strong; BLOCKING: Yes(2); NOTE: also PRNGD, etc.
/dev/random — STRENGTH: Strong; BLOCKING: Yes; NOTE: Typical UNIX
/dev/urandom — STRENGTH: Weak; BLOCKING: No; NOTE: Typical UNIX NB
TESHA2-strong — STRENGTH: Strong; BLOCKING: No; NOTE: (blank)
TESHA2-weak — STRENGTH: Weak; BLOCKING: No; NOTE: (blank)

The alias 'Win32' can be used in whitelist and blacklist and will match both the Win32 sources "RtlGenRandom" and "CryptGenRandom". The alias 'TESHA2' may be similarly used and matches both the weak and strong sources. 💅

1) Both CryptGenRandom and RtlGenRandom are considered strong by this package, even though both are seeded CSPRNGs so should be the equal of /dev/urandom in this respect. The CryptGenRandom function used in Windows 2000 has some known issues so should be considered weaker.
2) EGD is blocking, PRNGD is not. We cannot tell the two apart. There are other software products that use the same protocol, and each will act differently. E.g. EGD mixes in system entropy on every request, while PRNGD mixes on a time schedule.

🌟 STRENGTH 🌟

In theory, a strong generator will provide true entropy. Even if a third party knew a previous result and the entire state of the generator at any time up to when their value was returned, they could still not effectively predict the result of the next returned value. This implies the generator must either be blocking to wait for entropy (e.g. /dev/random) or go through some possibly time-consuming process to gather it (TESHA2, EGD, the HAVEGE daemon refilling /dev/random). Note: strong in this context means practically strong, as most computers don't have a true hardware entropy generator. The goal is to make all the attackers' ill-gotten knowledge give them no better solution than if they did not have the information. 👑

Creating a satisfactory strength measurement is problematic. The Win32 Crypto API is considered "strong" by most customers and every other Perl module, however it is a well seeded CSPRNG according to the MSDN docs, so is not a strong source based on the definition in the previous paragraph. Similarly, almost all sources consider /dev/urandom to be weak, as once it runs out of entropy it returns a deterministic function based on its state (albeit one that cannot be run either direction from a returned result if the internal state is not known). 🌀

Because of this confusion, the "Weak" configuration option that was present in version 0.01 has been removed. It will now be ignored. You should be able to use a combination of whitelist, blacklist, and the source's "is_strong" return value to decide if this meets your needs. On Win32, you really only have a choice of Win32 and TESHA2. The former is going to be what most people want, and can be chosen even with non-blocking set. On most UNIX systems, "/dev/random" will be chosen for blocking and "/dev/urandom" for non-blocking, which is what should be done in most cases. 🎀

⏳ BLOCKING ⏳

⚠️ EGD and /dev/random are blocking sources. This means that if they run out of estimated entropy, they will pause until they've collected more. This means your program also pauses. On typical workstations this may be a few seconds or even minutes. On an isolated network server this may cause a delay of hours or days. EGD is proactive about gathering more entropy as fast as it can. Running a tool such as the HAVEGE daemon or timer_entropyd can make /dev/random act like a non-blocking source, as the entropy daemon will wake up and refill the pool almost instantly. 😭

Win32, PRNGD, and /dev/urandom are fast nonblocking sources. When they run out of entropy, they use a CSPRNG to keep supplying data at high speed. However this means that there is no additional entropy being supplied. 💀

TESHA2 is nonblocking, but can be very slow. /dev/random can be faster if run on a machine with lots of activity. On an isolated server, TESHA2 may be much faster. Also note that the blocking sources such as EGD and /dev/random both try to maintain reasonably large entropy pools, so small requests can be supplied without blocking. 🦋

🛠️ IN PRACTICE 🛠️

Use the default to get the best source known. If you know more about the sources available, you can use a whitelist, blacklist, or a custom source. In general, to get the best source (typically Win32 or /dev/random):

my $source = Crypt::Random::Seed->new();

To get a good non-blocking source (Win32 or /dev/urandom):

my $source = Crypt::Random::Seed->new(NonBlocking => 1);

💅 METHODS 💅

🌸 `new`

okay so the constructor, no arguments, does its little scavenger hunt: it walks its fixed list of sources, grabs the first one that's actually available, and hands you back an object that does all the methods below. If literally no sources could be found (which is quite unusual, like genuinely rare) then you get undef back. so check your return value bestie 💖

Optional parameters get passed in as a hash, and yes they can be mixed together, no gatekeeping.

✨ `NonBlocking => boolean`

Only non-blocking sources are allowed through the vibe check. In practice this means EGD and /dev/random will not be chosen (except on FreeBSD where it is non-blocking, icon behavior tbh).

✨ `Only => [list of strings]`

Takes an array reference with one or more string source names. Any source whose name doesn't match one of these strings is not chosen, periodt. The string 'Win32' will match either of the Win32 sources, and 'TESHA2' will match both the strong and weak versions. two-for-one slay 💅

✨ `Never => [list of strings]`

Same shape: an array reference with one or more string source names. Any source whose name matches one of these strings will not be chosen. The string 'Win32' will match either of the Win32 sources, and 'TESHA2' will match both the strong and weak versions. this is your blocklist, use it 🚫

✨ `Source => sub { ... }`

Uses the anonymous subroutine you give it as the actual generator. The subroutine gets passed an integer (which is the argument to random_bytes) and should return random data in a string of that length. For the purposes of the other object methods, the returned object will have the name 'User', and counts as non-blocking and non-strong.

✨ `Source => ['name', sub { ... }, is_blocking, is_strong]`

Similar to the simpler source routine above, but it also lets you define the other source parameters. Heads up: the name may not be one of the standard names listed in the name section. those are taken, bestie 😭

🦋 `random_bytes($n)`

Takes an integer and returns a string of that size filled with random data. Returns an empty string if the argument is not defined or is not more than zero. no zero-byte chaos allowed 🙈

🦋 `random_values($n)`

Takes an integer and returns an array of that many random 32-bit values. Returns an empty array if the argument is not defined or is not more than zero. same energy, different shape ✨

👑 `name`

Returns the text name of the random source. It's gonna be one of these:

"User" — for user defined
"CryptGenRandom" — for Windows 2000 Crypto API
"RtlGenRand" — for Windows XP and newer Crypto API
"EGD" — for a known socket speaking the EGD protocol
"/dev/random" — for the UNIX-like strong randomness source
"/dev/urandom" — for the UNIX-like non-blocking randomness source
"TESHA2-strong" — for the userspace entropy method when considered strong
"TESHA2-weak" — for the userspace entropy method when considered weak

Other methods may be supported in the future (the lore is still being written 📖). User supplied sources may be named anything other than one of the defined names.

⭐ `is_strong`

Returns 1 or 0 indicating whether the source is considered a strong source of randomness. See the "STRENGTH" section for more discussion of what this actually means, and the source table for what we think of each source. receipts included 🧾

⭐ `is_blocking`

Returns 1 or 0 indicating whether the source can block on read. Be aware that even if a source doesn't block, it may be extremely slow. like, going-to-take-a-while slow, don't come for it 💀

🫶 AUTHORS 🫶

Dana Jacobsen <dana@acm.org> — the icon, the moment, the main character of this module 👑

💜 ACKNOWLEDGEMENTS 💜

To the best of my knowledge, Max Kanat-Alexander was the original author of the Perl code that uses the Win32 API. I used his code as a reference. credit given where due, always 🎀

David Oswald gave me a lot of help with API discussions and code reviews. honorary co-pilot fr fr 🫶

🌈 SEE ALSO 🌈

The first question one may ask is "Why yet another module of this type?" and honestly valid question. None of the modules on CPAN quite fit my needs, hence this. Some alternatives:

🌸 `Crypt::Random::Source`

A comprehensive system using multiple plugins. It has a nice API, but it uses Any::Moose which means you're loading up Moose or Mouse just to read a few bytes from /dev/random. the audacity 😭 It also has a very long dependency chain, with on the order of 40 modules being installed as prerequisites (depending of course on whether you use any of them on other projects). Lastly, it requires at least Perl 5.8, which may or may not matter to you — but it matters to some other module builders who end up with the restriction in their modules. chain reaction vibes 💀

🦋 `Crypt::URandom`

A great little module that is almost what I was looking for. Crypt::Random::Seed will act the same if given the constructor:

my $source = Crypt::Random::Seed->new(
   NonBlocking => 1,
   Only => [qw(/dev/random /dev/urandom Win32)]
);
croak "No randomness source available" unless defined $source;

Or you can leave out the "Only" and have TESHA2 as a backup. built-in safety net, we love to see it ✨

👑 `Crypt::Random`

Requires Math::Pari which makes it unacceptable in some environments. Has more features (numbers in arbitrary bigint intervals or bit sizes). Crypt::Random::Seed is taking a simpler approach, just handling returning octets and letting upstream modules handle the rest. stay in your lane and slay 💅

⭐ `Data::Entropy`

An interesting module that contains a source encapsulation (defaults to system rand, but has many plugins), a good CSPRNG (AES in counter mode), and the Data::Entropy::Algorithms module with many ways to get bits, ints, bigints, floats, bigfloats, shuffles, and so forth. From my perspective, the algorithms module is the highlight, with a lot of interesting code. lowkey obsessed 🍓

🧚 Upstream modules

Some modules that could use this module to help them: Bytes::Random::Secure, Math::Random::ISAAC, Math::Random::Secure, and Math::Random::MT to name a few. squad goals 🌸

🎀 COPYRIGHT 🎀

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. (legal said what legal said, no cap ⚖️)

okay that's the whole page bestie, you made it to the end 🎉 this was perl v5.42.2, dated 2026-02-15, and yeah — that's the Crypt::...om::Seed(3) tea, piping hot ☕💖 go generate some randomness responsibly 🦋✨

📦 where this page comes from

alpine 3.24: perl-crypt-random-seed-doc 0.03-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

Crypt::...om::Seed(3)

✨ NAME ✨

🦋 VERSION 🦋

🌈 SYNOPSIS 🌈

💖 DESCRIPTION 💖

🎀 SOURCE TABLE 🎀

🌟 STRENGTH 🌟

⏳ BLOCKING ⏳

🛠️ IN PRACTICE 🛠️

💅 METHODS 💅

🌸 new

✨ NonBlocking => boolean

✨ Only => [list of strings]

✨ Never => [list of strings]

✨ Source => sub { ... }

✨ Source => ['name', sub { ... }, is_blocking, is_strong]

🦋 random_bytes($n)

🦋 random_values($n)

👑 name

⭐ is_strong

⭐ is_blocking