1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
61 . tm Index:\\$1\t\\n%\t"\\$2"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
88 . \" simple accents for nroff and troff
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
132 .\" ========================================================================
134 .IX Title "BN_generate_prime 3"
135 .TH BN_generate_prime 3 "2010-02-27" "0.9.8m" "OpenSSL"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
141 BN_generate_prime, BN_is_prime, BN_is_prime_fasttest \- generate primes and test for primality
143 .IX Header "SYNOPSIS"
145 \& #include <openssl/bn.h>
147 \& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
148 \& BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
150 \& int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
151 \& void *), BN_CTX *ctx, void *cb_arg);
153 \& int BN_is_prime_fasttest(const BIGNUM *a, int checks,
154 \& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
155 \& int do_trial_division);
158 .IX Header "DESCRIPTION"
159 \&\fIBN_generate_prime()\fR generates a pseudo-random prime number of \fBnum\fR
161 If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
163 If \fBcallback\fR is not \fB\s-1NULL\s0\fR, it is called as follows:
165 \&\fBcallback(0, i, cb_arg)\fR is called after generating the i\-th
166 potential prime number.
168 While the number is being tested for primality, \fBcallback(1, j,
169 cb_arg)\fR is called as described below.
171 When a prime has been found, \fBcallback(2, i, cb_arg)\fR is called.
173 The prime may have to fulfill additional requirements for use in
174 Diffie-Hellman key exchange:
176 If \fBadd\fR is not \fB\s-1NULL\s0\fR, the prime will fulfill the condition p % \fBadd\fR
177 == \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fB\s-1NULL\s0\fR) in order to suit a given
180 If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
181 that (p\-1)/2 is also prime).
183 The \s-1PRNG\s0 must be seeded prior to calling \fIBN_generate_prime()\fR.
184 The prime number generation has a negligible error probability.
186 \&\fIBN_is_prime()\fR and \fIBN_is_prime_fasttest()\fR test if the number \fBa\fR is
187 prime. The following tests are performed until one of them shows that
188 \&\fBa\fR is composite; if \fBa\fR passes all these tests, it is considered
191 \&\fIBN_is_prime_fasttest()\fR, when called with \fBdo_trial_division == 1\fR,
192 first attempts trial division by a number of small primes;
193 if no divisors are found by this test and \fBcallback\fR is not \fB\s-1NULL\s0\fR,
194 \&\fBcallback(1, \-1, cb_arg)\fR is called.
195 If \fBdo_trial_division == 0\fR, this test is skipped.
197 Both \fIBN_is_prime()\fR and \fIBN_is_prime_fasttest()\fR perform a Miller-Rabin
198 probabilistic primality test with \fBchecks\fR iterations. If
199 \&\fBchecks == BN_prime_checks\fR, a number of iterations is used that
200 yields a false positive rate of at most 2^\-80 for random input.
202 If \fBcallback\fR is not \fB\s-1NULL\s0\fR, \fBcallback(1, j, cb_arg)\fR is called
203 after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
204 pre-allocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
205 freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
207 .IX Header "RETURN VALUES"
208 \&\fIBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
210 \&\fIBN_is_prime()\fR returns 0 if the number is composite, 1 if it is
211 prime with an error probability of less than 0.25^\fBchecks\fR, and
214 The error codes can be obtained by \fIERR_get_error\fR\|(3).
216 .IX Header "SEE ALSO"
217 \&\fIbn\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3)
220 The \fBcb_arg\fR arguments to \fIBN_generate_prime()\fR and to \fIBN_is_prime()\fR
221 were added in SSLeay 0.9.0. The \fBret\fR argument to \fIBN_generate_prime()\fR
222 was added in SSLeay 0.9.1.
223 \&\fIBN_is_prime_fasttest()\fR was added in OpenSSL 0.9.5.