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

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

<h1>BN_generate_prime(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_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and
test for primality

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bn.h&gt;
</PRE>
<PRE> BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
     BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
</PRE>
<PRE> int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, 
     void *), BN_CTX *ctx, void *cb_arg);
</PRE>
<PRE> int BN_is_prime_fasttest(const BIGNUM *a, int checks,
     void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
     int do_trial_division);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BN_generate_prime()</CODE> generates a pseudo-random prime number of <STRONG>num</STRONG>
bits. If <STRONG>ret</STRONG> is not <STRONG>NULL</STRONG>, it will be used to store the number.

</P>
<P>
If <STRONG>callback</STRONG> is not <STRONG>NULL</STRONG>, it is called as follows:

</P>
<UL>
<LI>
<P>
<STRONG>callback(0, i, cb_arg)</STRONG> is called after generating the i-th potential prime number.

</P>
<LI>
<P>
While the number is being tested for primality, <STRONG>callback(1, j,
cb_arg)</STRONG> is called as described below.

</P>
<LI>
<P>
When a prime has been found, <STRONG>callback(2, i, cb_arg)</STRONG> is called.

</P>
</UL>
<P>
The prime may have to fulfill additional requirements for use in
Diffie-Hellman key exchange:

</P>
<P>
If <STRONG>add</STRONG> is not <STRONG>NULL</STRONG>, the prime will fulfill the condition p % <STRONG>add</STRONG>
== <STRONG>rem</STRONG> (p % <STRONG>add</STRONG> == 1 if <STRONG>rem</STRONG> == <STRONG>NULL</STRONG>) in order to suit a given generator.

</P>
<P>
If <STRONG>safe</STRONG> is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 is also
prime).

</P>
<P>
The PRNG must be seeded prior to calling <CODE>BN_generate_prime().</CODE>
The prime number generation has a negligible error probability.

</P>
<P>
<CODE>BN_is_prime()</CODE> and <CODE>BN_is_prime_fasttest()</CODE> test if
the number <STRONG>a</STRONG> is prime. The following tests are performed until one of them shows that
<STRONG>a</STRONG> is composite; if <STRONG>a</STRONG> passes all these tests, it is considered prime.

</P>
<P>
<CODE>BN_is_prime_fasttest(),</CODE> when called with <STRONG>do_trial_division == 1</STRONG>, first attempts trial division by a number of small primes; if no divisors
are found by this test and <STRONG>callback</STRONG> is not <STRONG>NULL</STRONG>,
<STRONG>callback(1, -1, cb_arg)</STRONG> is called. If <STRONG>do_trial_division == 0</STRONG>, this test is skipped.

</P>
<P>
Both <CODE>BN_is_prime()</CODE> and <CODE>BN_is_prime_fasttest()</CODE>
perform a Miller-Rabin probabilistic primality test with <STRONG>checks</STRONG> iterations. If
<STRONG>checks == BN_prime_checks</STRONG>, a number of iterations is used that yields a false positive rate of at
most 2^-80 for random input.

</P>
<P>
If <STRONG>callback</STRONG> is not <STRONG>NULL</STRONG>, <STRONG>callback(1, j, cb_arg)</STRONG> is called after the j-th iteration (j = 0, 1, ...). <STRONG>ctx</STRONG> is a pre-allocated <STRONG>BN_CTX</STRONG> (to save the overhead of allocating and freeing the structure in a loop),
or <STRONG>NULL</STRONG>.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BN_generate_prime()</CODE> returns the prime number on success, <STRONG>NULL</STRONG> otherwise.

</P>
<P>
<CODE>BN_is_prime()</CODE> returns 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^<STRONG>checks</STRONG>, and -1 on error.

</P>
<P>
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>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
The <STRONG>cb_arg</STRONG> arguments to <CODE>BN_generate_prime()</CODE> and to
<CODE>BN_is_prime()</CODE> were added in SSLeay 0.9.0. The <STRONG>ret</STRONG> argument to <CODE>BN_generate_prime()</CODE> was added in SSLeay 0.9.1.
<CODE>BN_is_prime_fasttest()</CODE> was added in OpenSSL 0.9.5.

</P>
:}