#use wml::openssl-macros area=docs page=BN_rand

<title>Documents, BN_rand(3)</title>

<h1>BN_rand(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
BN_rand, BN_pseudo_rand - generate pseudo-random number

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bn.h&gt;
</PRE>
<PRE> int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
</PRE>
<PRE> int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
</PRE>
<PRE> int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
</PRE>
<PRE> int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BN_rand()</CODE> generates a cryptographically strong pseudo-random
number of
<STRONG>bits</STRONG> bits in length and stores it in <STRONG>rnd</STRONG>. If <STRONG>top</STRONG> is -1, the most significant bit of the random number can be zero. If <STRONG>top</STRONG> is 0, it is set to 1, and if <STRONG>top</STRONG> 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*<STRONG>bits</STRONG> length. If <STRONG>bottom</STRONG> is true, the number will be odd.

</P>
<P>
<CODE>BN_pseudo_rand()</CODE> 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.

</P>
<P>
<CODE>BN_rand_range()</CODE> generates a cryptographically strong
pseudo-random number <STRONG>rnd</STRONG> in the range 0 &lt;lt&gt;= <STRONG>rnd</STRONG>  &lt;  <STRONG>range</STRONG>. <CODE>BN_pseudo_rand_range()</CODE> does the same, but is based on
<CODE>BN_pseudo_rand(),</CODE> and hence numbers generated by it are not
necessarily unpredictable.

</P>
<P>
The PRNG must be seeded prior to calling <CODE>BN_rand()</CODE> or
<CODE>BN_rand_range().</CODE>

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
The functions return 1 on success, 0 on error. The error codes can be
obtained by <A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/bn.html#">bn(3)</A>, <A HREF="../crypto/ERR_get_error.html#">ERR_get_error(3)</A>, <A HREF="../crypto/rand.html#">rand(3)</A>,
<A HREF="../crypto/RAND_add.html#">RAND_add(3)</A>, <A HREF="../crypto/RAND_bytes.html#">RAND_bytes(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>BN_rand()</CODE> is available in all versions of SSLeay and OpenSSL.
<CODE>BN_pseudo_rand()</CODE> was added in OpenSSL 0.9.5. The <STRONG>top</STRONG> == -1 case and the function <CODE>BN_rand_range()</CODE> were added in
OpenSSL 0.9.6a. <CODE>BN_pseudo_rand_range()</CODE> was added in OpenSSL
0.9.6c.

</P>
:}