.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Crypt::PRNG 3"
.TH Crypt::PRNG 3 2026-08-10 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Crypt::PRNG \- Cryptographically secure random number generator
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&   ### Functional interface:
\&   use Crypt::PRNG qw(random_bytes random_bytes_hex random_bytes_b64 random_bytes_b64u
\&                      random_string random_string_from rand irand);
\&
\&   my $octets = random_bytes(45);
\&   my $hex_string = random_bytes_hex(45);
\&   my $base64_string = random_bytes_b64(45);
\&   my $base64url_string = random_bytes_b64u(45);
\&   my $alphanumeric_string = random_string(30);
\&   my $string = random_string_from(\*(AqACGT\*(Aq, 64);
\&   my $floating_point_number_0_to_1 = rand;
\&   my $floating_point_number_0_to_88 = rand(88);
\&   my $unsigned_32bit_int = irand;
\&
\&   ### OO interface:
\&   use Crypt::PRNG;
\&
\&   my $prng = Crypt::PRNG\->new;  # defaults to ChaCha20
\&   my $rc4_prng = Crypt::PRNG\->new("RC4");
\&   my $seeded_prng = Crypt::PRNG\->new("RC4", "some data used for seeding PRNG");
\&
\&   my $octets = $prng\->bytes(45);
\&   my $hex_string = $prng\->bytes_hex(45);
\&   my $base64_string = $prng\->bytes_b64(45);
\&   my $base64url_string = $prng\->bytes_b64u(45);
\&   my $alphanumeric_string = $prng\->string(30);
\&   my $string = $prng\->string_from(\*(AqACGT\*(Aq, 64);
\&   my $floating_point_number_0_to_1 = $prng\->double;
\&   my $floating_point_number_0_to_88 = $prng\->double(88);
\&   my $unsigned_32bit_int = $prng\->int32;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides an interface to several pseudo\-random number generators (thread\-safe
and fork\-safe). The default algorithm is ChaCha20.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::PRNG qw(random_bytes random_string);
.Ve
.PP
Or all of them at once:
.PP
.Vb 1
\&  use Crypt::PRNG \*(Aq:all\*(Aq;
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
For all \f(CW\*(C`random_bytes*\*(C'\fR functions and the corresponding \f(CW\*(C`bytes*\*(C'\fR methods,
\&\f(CW$length\fR must not be greater than \f(CW1000000000\fR.
.SS random_bytes
.IX Subsection "random_bytes"
.Vb 2
\&   my $octets = random_bytes($length);
\&   # $length .. [integer] number of random bytes to generate
.Ve
.PP
Returns \f(CW$length\fR random octets as a binary string.
.SS random_bytes_hex
.IX Subsection "random_bytes_hex"
.Vb 2
\&   my $hex_string = random_bytes_hex($length);
\&   # $length .. [integer] number of random bytes (output string will be 2x longer)
.Ve
.PP
Returns \f(CW$length\fR random octets encoded as a lowercase hexadecimal string.
.SS random_bytes_b64
.IX Subsection "random_bytes_b64"
.Vb 2
\&   my $base64_string = random_bytes_b64($length);
\&   # $length .. [integer] number of random bytes to encode
.Ve
.PP
Returns \f(CW$length\fR random octets encoded as a Base64 string.
.SS random_bytes_b64u
.IX Subsection "random_bytes_b64u"
.Vb 2
\&   my $base64url_string = random_bytes_b64u($length);
\&   # $length .. [integer] number of random bytes to encode
.Ve
.PP
Returns \f(CW$length\fR random octets encoded as a Base64 URL\-safe string (RFC 4648 section 5).
.SS random_string_from
.IX Subsection "random_string_from"
.Vb 5
\&   my $string = random_string_from($range, $length);
\&   # $range  .. [string] alphabet of allowed characters
\&   # $length .. [integer] optional, number of characters (DEFAULT: 20)
\&   #e.g.
\&   my $dna_string = random_string_from("ABCD", 10);
.Ve
.PP
Returns a random string of \f(CW$length\fR characters chosen from \f(CW$range\fR.
The alphabet must contain between 1 and 65536 characters; longer alphabets
return \f(CW\*(C`undef\*(C'\fR.
.SS random_string
.IX Subsection "random_string"
.Vb 4
\&   my $alphanumeric_string = random_string($length);
\&   # $length .. [integer] optional, number of characters (DEFAULT: 20)
\&   #or
\&   my $default_alphanumeric_string = random_string;  # default length = 20
.Ve
.PP
Like \f(CW\*(C`random_string_from\*(C'\fR, but \f(CW$range\fR is fixed to
\&\f(CW\*(AqABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\*(Aq\fR.
.SS rand
.IX Subsection "rand"
.Vb 4
\&   my $n = rand;
\&   #or
\&   my $limited_n = rand($limit);
\&   # $limit .. [number] optional, upper bound (exclusive)
.Ve
.PP
Returns a random floating\-point number in the range \f(CW\*(C`[0,1)\*(C'\fR if called without
an argument, or \f(CW\*(C`[0,$limit)\*(C'\fR if \f(CW$limit\fR is given.
If \f(CW$limit\fR is \f(CW0\fR, this behaves as if no limit was given and returns a
value in \f(CW\*(C`[0,1)\*(C'\fR, matching Perl\*(Aqs built\-in \f(CW\*(C`rand\*(C'\fR.
.SS irand
.IX Subsection "irand"
.Vb 1
\&   my $i = irand;
.Ve
.PP
Returns a random unsigned 32\-bit integer in the range \f(CW\*(C`0 .. 0xFFFFFFFF\*(C'\fR.
.SH METHODS
.IX Header "METHODS"
Unless noted otherwise, assume \f(CW$prng\fR is an existing PRNG object created via
\&\f(CW\*(C`new\*(C'\fR, for example:
.PP
.Vb 1
\&   my $prng = Crypt::PRNG\->new;
.Ve
.SS new
.IX Subsection "new"
.Vb 5
\&   my $prng = Crypt::PRNG\->new;  # defaults to ChaCha20
\&   #or
\&   my $prng = Crypt::PRNG\->new($alg);
\&   #or
\&   my $prng = Crypt::PRNG\->new($alg, $seed);
\&
\&   # $alg  ... [string] algorithm name: \*(AqChaCha20\*(Aq (DEFAULT), \*(AqFortuna\*(Aq, \*(AqRC4\*(Aq (legacy; compatibility only), \*(AqSober128\*(Aq or \*(AqYarrow\*(Aq
\&   # $seed ... [binary string] optional, initial entropy for seeding the PRNG
.Ve
.PP
If \f(CW$seed\fR is not given, the PRNG is automatically seeded with 40 bytes
obtained via libtomcrypt\*(Aqs \f(CWrng_get_bytes()\fR platform RNG logic.
.PP
If \f(CW$seed\fR is specified it must be non\-empty for all algorithms. RC4 is
provided for legacy compatibility only, is not recommended for new designs, and
requires a seed of at least 5 bytes.
.SS add_entropy
.IX Subsection "add_entropy"
.Vb 4
\&  my $prng = Crypt::PRNG\->new;
\&  $prng\->add_entropy($random_data);
\&  #or
\&  $prng\->add_entropy();
.Ve
.PP
If called without parameter it uses 40 bytes obtained via libtomcrypt\*(Aqs
\&\f(CWrng_get_bytes()\fR platform RNG logic.
.PP
\&\fBNote:\fR You probably do not need this function. The module seeds itself on
initialization and reseeds after fork and thread creation.
.SS bytes
.IX Subsection "bytes"
.Vb 1
\&   my $octets = $prng\->bytes($length);
.Ve
.PP
See random_bytes
.SS bytes_hex
.IX Subsection "bytes_hex"
.Vb 1
\&   my $hex_string = $prng\->bytes_hex($length);
.Ve
.PP
See random_bytes_hex
.SS bytes_b64
.IX Subsection "bytes_b64"
.Vb 1
\&   my $base64_string = $prng\->bytes_b64($length);
.Ve
.PP
See random_bytes_b64
.SS bytes_b64u
.IX Subsection "bytes_b64u"
.Vb 1
\&   my $base64url_string = $prng\->bytes_b64u($length);
.Ve
.PP
See random_bytes_b64u
.SS string
.IX Subsection "string"
.Vb 3
\&   my $alphanumeric_string = $prng\->string($length);
\&   #or
\&   my $default_alphanumeric_string = $prng\->string;  # default length = 20
.Ve
.PP
See random_string
.SS string_from
.IX Subsection "string_from"
.Vb 1
\&   my $string = $prng\->string_from($range, $length);  # default length = 20
.Ve
.PP
See random_string_from
.SS double
.IX Subsection "double"
.Vb 3
\&   my $n = $prng\->double;
\&   #or
\&   my $limited_n = $prng\->double($limit);
.Ve
.PP
See rand
.SS int32
.IX Subsection "int32"
.Vb 1
\&   my $i = $prng\->int32;
.Ve
.PP
See irand
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Crypt::PRNG::ChaCha20, Crypt::PRNG::Fortuna, Crypt::PRNG::RC4,
Crypt::PRNG::Sober128, Crypt::PRNG::Yarrow
.PP
For generating random UUIDs see "random_v4uuid" in Crypt::Misc and "random_v7uuid" in Crypt::Misc.