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

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

<h1>DSA_generate_parameters(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_VALUE">RETURN VALUE</A>
	<LI><A HREF="#BUGS">BUGS</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>
DSA_generate_parameters - generate DSA parameters

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/dsa.h&gt;
</PRE>
<PRE> DSA *DSA_generate_parameters(int bits, unsigned char *seed,
                int seed_len, int *counter_ret, unsigned long *h_ret,
                void (*callback)(int, int, void *), void *cb_arg);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>DSA_generate_parameters()</CODE> generates primes p and q and a
generator g for use in the DSA.

</P>
<P>
<STRONG>bits</STRONG> is the length of the prime to be generated; the DSS allows a maximum of
1024 bits.

</P>
<P>
If <STRONG>seed</STRONG> is <STRONG>NULL</STRONG> or <STRONG>seed_len</STRONG>  &lt; 20, the primes will be generated at random. Otherwise, the seed is used to
generate them. If the given seed does not yield a prime q, a new random
seed is chosen and placed at <STRONG>seed</STRONG>.

</P>
<P>
<CODE>DSA_generate_parameters()</CODE> places the iteration count in *<STRONG>counter_ret</STRONG> and a counter used for finding a generator in *<STRONG>h_ret</STRONG>, unless these are <STRONG>NULL</STRONG>.

</P>
<P>
A callback function may be used to provide feedback about the progress of
the key generation. If <STRONG>callback</STRONG> is not <STRONG>NULL</STRONG>, it will be called as follows:

</P>
<UL>
<LI>
<P>
When a candidate for q is generated, <STRONG>callback(0, m++, cb_arg)</STRONG> is called (m is 0 for the first candidate).

</P>
<LI>
<P>
When a candidate for q has passed a test by trial division,
<STRONG>callback(1, -1, cb_arg)</STRONG> is called. While a candidate for q is tested by Miller-Rabin primality
tests,
<STRONG>callback(1, i, cb_arg)</STRONG> is called in the outer loop (once for each witness that confirms that the
candidate may be prime); i is the loop counter (starting at 0).

</P>
<LI>
<P>
When a prime q has been found, <STRONG>callback(2, 0, cb_arg)</STRONG> and
<STRONG>callback(3, 0, cb_arg)</STRONG> are called.

</P>
<LI>
<P>
Before a candidate for p (other than the first) is generated and tested,
<STRONG>callback(0, counter, cb_arg)</STRONG> is called.

</P>
<LI>
<P>
When a candidate for p has passed the test by trial division,
<STRONG>callback(1, -1, cb_arg)</STRONG> is called. While it is tested by the Miller-Rabin primality test,
<STRONG>callback(1, i, cb_arg)</STRONG> is called in the outer loop (once for each witness that confirms that the
candidate may be prime). i is the loop counter (starting at 0).

</P>
<LI>
<P>
When p has been found, <STRONG>callback(2, 1, cb_arg)</STRONG> is called.

</P>
<LI>
<P>
When the generator has been found, <STRONG>callback(3, 1, cb_arg)</STRONG> is called.

</P>
</UL>
<P>
<HR>
<H1><A NAME="RETURN_VALUE">RETURN VALUE</A></H1>
<P>
<CODE>DSA_generate_parameters()</CODE> returns a pointer to the DSA
structure, or
<STRONG>NULL</STRONG> if the parameter generation fails. 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="BUGS">BUGS</A></H1>
<P>
Seed lengths &gt; 20 are not supported.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/dsa.html#">dsa(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/DSA_new.html#">DSA_free(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>DSA_generate_parameters()</CODE> appeared in SSLeay 0.8. The <STRONG>cb_arg</STRONG>
argument was added in SSLeay 0.9.0. In versions up to OpenSSL 0.9.4, <STRONG>callback(1, ...)</STRONG> was called in the inner loop of the Miller-Rabin test whenever it reached
the squaring step (the parameters to <STRONG>callback</STRONG> did not reveal how many witnesses had been tested); since OpenSSL 0.9.5, <STRONG>callback(1, ...)</STRONG>
is called as in <CODE>BN_is_prime(3),</CODE> i.e. once for each witness.
=cut
</P>
:}