.\" -*- 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 "BN_rand 3"
.TH BN_rand 3 2019-12-20 1.0.2u OpenSSL
.\" 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
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range \- generate pseudo\-random number
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bn.h>
\&
\& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
\&
\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
\&
\& int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
\&
\& int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBBN_rand()\fR generates a cryptographically strong pseudo-random number of
\&\fBbits\fR in length and stores it in \fBrnd\fR.
If \fBbits\fR is less than zero, or too small to
accomodate the requirements specified by the \fBtop\fR and \fBbottom\fR
parameters, an error is returned.
If \fBtop\fR is \-1, the
most significant bit of the random number can be zero. If \fBtop\fR is 0,
it is set to 1, and if \fBtop\fR is 1, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*\fBbits\fR length.  If \fBbottom\fR is true, the
number will be odd. The value of \fBbits\fR must be zero or greater. If \fBbits\fR is
1 then \fBtop\fR cannot also be 1.
.PP
\&\fBBN_pseudo_rand()\fR does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
.PP
\&\fBBN_rand_range()\fR generates a cryptographically strong pseudo-random
number \fBrnd\fR in the range 0 <= \fBrnd\fR < \fBrange\fR.
\&\fBBN_pseudo_rand_range()\fR does the same, but is based on \fBBN_pseudo_rand()\fR,
and hence numbers generated by it are not necessarily unpredictable.
.PP
The PRNG must be seeded prior to calling \fBBN_rand()\fR or \fBBN_rand_range()\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The functions return 1 on success, 0 on error.
The error codes can be obtained by \fBERR_get_error\fR\|(3).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBbn\fR\|(3), \fBERR_get_error\fR\|(3), \fBrand\fR\|(3),
\&\fBRAND_add\fR\|(3), \fBRAND_bytes\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
\&\fBBN_rand()\fR is available in all versions of SSLeay and OpenSSL.
\&\fBBN_pseudo_rand()\fR was added in OpenSSL 0.9.5. The \fBtop\fR == \-1 case
and the function \fBBN_rand_range()\fR were added in OpenSSL 0.9.6a.
\&\fBBN_pseudo_rand_range()\fR was added in OpenSSL 0.9.6c.