.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .\" ======================================================================== .\" .IX Title "BSD::arc4random 3pm" .TH BSD::arc4random 3pm 2024-03-07 "perl v5.38.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 BSD::arc4random \- Perl interface to the arc4 random number generator .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 10 \& use BSD::arc4random qw(:all); \& $v = arc4random(); \& $v = arc4random_uniform($hz); \& if (!BSD::arc4random::have_kintf()) { \& $v = arc4random_addrandom("entropy to pass to the system"); \& } else { \& $v = arc4random_pushb("entropy to pass to the system"); \& $v = arc4random_pushk("entropy to pass to the kernel"); \& } \& $s = arc4random_bytes(16, "entropy to pass to libc"); \& arc4random_stir(); \& $s = arc4random_bytes(16); \& print $RANDOM; .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This set of functions maps the \fBarc4random\fR\|(3) family of libc functions into Perl code. All functions listed below are ithreads-safe. The internal XS functions are not, but you are not supposed to call them, either. .PP On module load, perl's internal PRNG is re-seeded, as a bonus, using \&\fBsrand\fR with an argument calculated from using \fBarc4random_pushb\fR on some entropy returned from \fBrand\fR's previous state. .SS "LOW-LEVEL FUNCTIONS" .IX Subsection "LOW-LEVEL FUNCTIONS" .IP \fBarc4random\fR() 4 .IX Item "arc4random()" This function returns an unsigned 32\-bit integer random value. .IP \fBarc4random_addrandom\fR(\fIpbuf\fR) 4 .IX Item "arc4random_addrandom(pbuf)" This function adds the entropy from \fIpbuf\fR into the libc pool and returns an unsigned 32\-bit integer random value from it. .IP \fBarc4random_pushb\fR(\fIpbuf\fR) 4 .IX Item "arc4random_pushb(pbuf)" This function first pushes the \fIpbuf\fR argument to the kernel if possible, then the entropy returned by the kernel into the libc pool, then returns an unsigned 32\-bit integer random value from it. .IP \fBarc4random_pushk\fR(\fIpbuf\fR) 4 .IX Item "arc4random_pushk(pbuf)" This function first pushes the \fIpbuf\fR argument to the kernel if possible, then returns an unsigned 32\-bit integer random value from the kernel. .Sp This function is deprecated. Use \fBarc4random_pushb\fR instead. .IP \fBarc4random_stir\fR() 4 .IX Item "arc4random_stir()" This procedure attempts to retrieve new entropy from the kernel and add it to the libc pool. Usually, this means you must have access to the \fBurandom\fR\|(4) device; create it inside \fBchroot\fR\|(2) jails first if you use them. .IP \fBhave_kintf\fR() 4 .IX Item "have_kintf()" This constant function returns 1 if \fBarc4random_pushb\fR and/or \&\fBarc4random_pushk\fR actually call the kernel interfaces, 0 if they merely map to \fBarc4random_addrandom\fR instead. .SS "HIGH-LEVEL FUNCTIONS" .IX Subsection "HIGH-LEVEL FUNCTIONS" .IP "\fBarc4random_bytes\fR(\fInum\fR[, \fIpbuf\fR])" 4 .IX Item "arc4random_bytes(num[, pbuf])" This function returns a string containing as many random bytes as requested by the integral argument \fInum\fR. An optional \fIpbuf\fR argument is passed to the system first. .IP \fBarc4random_uniform\fR(\fIupper_bound\fR) 4 .IX Item "arc4random_uniform(upper_bound)" Calculate a uniformly distributed random number less than upper_bound avoiding "modulo bias". .SS "PACKAGE VARIABLES" .IX Subsection "PACKAGE VARIABLES" .ie n .IP \fR\fB$RANDOM\fR\fB\fR 4 .el .IP \fR\f(CB$RANDOM\fR\fB\fR 4 .IX Item "$RANDOM" The \fR\f(CB$RANDOM\fR\fB\fR returns a random value in the range [0;\ 32767] on each read attempt and pushes any value it is assigned to the kernel. It is tied at module load time. .IP "tie \fIvariable\fR, 'BSD::arc4random'[, \fImax\fR]" 4 .IX Item "tie variable, 'BSD::arc4random'[, max]" You can tie any scalar variable to this package; the \fImax\fR argument is the maximum number returned; if undefined, 0 or >=\ 0xFFFFFFFF, no bound is used, and values in the range [0;\ 2**32\-1] are returned. They will behave like \fR\f(CB$RANDOM\fR\fB\fR. .SH AUTHOR .IX Header "AUTHOR" Thorsten Glaser .SH "SEE ALSO" .IX Header "SEE ALSO" The \fBarc4random\fR\|(3) manual page, available online at: .PP Perl's rand and srand functions via perlfunc and perlfaq4. .PP The \fBrandex.pl\fR plugin for Irssi, implementing the MirOS RANDEX protocol (entropy exchange over IRC), with CVSweb at: .PP when it's done being written. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2008, 2009, 2010, 2011 Thorsten "mirabilos" Glaser Copyright (c) 2009 Benny Siegert Credits to Sebastian "Vutral" Schwarz .PP This module is covered by the MirOS Licence: .PP The original C implementation of arc4random_uniform was contributed by Damien Miller from OpenBSD, with simplifications by Jinmei Tatuya.