1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
60 . tm Index:\\$1\t\\n%\t"\\$2"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "BN_GENERATE_PRIME 3"
132 .TH BN_GENERATE_PRIME 3 "2018-09-11" "1.1.1" "OpenSSL"
133 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
134 .\" way too many mistakes in technical documents.
138 BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime, BN_is_prime, BN_is_prime_fasttest \- generate primes and test for primality
140 .IX Header "SYNOPSIS"
142 \& #include <openssl/bn.h>
144 \& int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
145 \& const BIGNUM *rem, BN_GENCB *cb);
147 \& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
149 \& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
150 \& int do_trial_division, BN_GENCB *cb);
152 \& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
154 \& BN_GENCB *BN_GENCB_new(void);
156 \& void BN_GENCB_free(BN_GENCB *cb);
158 \& void BN_GENCB_set_old(BN_GENCB *gencb,
159 \& void (*callback)(int, int, void *), void *cb_arg);
161 \& void BN_GENCB_set(BN_GENCB *gencb,
162 \& int (*callback)(int, int, BN_GENCB *), void *cb_arg);
164 \& void *BN_GENCB_get_arg(BN_GENCB *cb);
170 \& #if OPENSSL_API_COMPAT < 0x00908000L
171 \& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
172 \& BIGNUM *rem, void (*callback)(int, int, void *),
175 \& int BN_is_prime(const BIGNUM *a, int checks,
176 \& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
178 \& int BN_is_prime_fasttest(const BIGNUM *a, int checks,
179 \& void (*callback)(int, int, void *), BN_CTX *ctx,
180 \& void *cb_arg, int do_trial_division);
184 .IX Header "DESCRIPTION"
185 \&\fIBN_generate_prime_ex()\fR generates a pseudo-random prime number of
186 at least bit length \fBbits\fR.
187 If \fBret\fR is not \fB\s-1NULL\s0\fR, it will be used to store the number.
189 If \fBcb\fR is not \fB\s-1NULL\s0\fR, it is used as follows:
191 \&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
192 potential prime number.
194 While the number is being tested for primality,
195 \&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below.
197 When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
199 The callers of \fIBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with
200 other values as described in their respective man pages; see \*(L"\s-1SEE ALSO\*(R"\s0.
202 The prime may have to fulfill additional requirements for use in
203 Diffie-Hellman key exchange:
205 If \fBadd\fR is not \fB\s-1NULL\s0\fR, the prime will fulfill the condition p % \fBadd\fR
206 == \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fB\s-1NULL\s0\fR) in order to suit a given
209 If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
210 that (p\-1)/2 is also prime).
212 The \s-1PRNG\s0 must be seeded prior to calling \fIBN_generate_prime_ex()\fR.
213 The prime number generation has a negligible error probability.
215 \&\fIBN_is_prime_ex()\fR and \fIBN_is_prime_fasttest_ex()\fR test if the number \fBp\fR is
216 prime. The following tests are performed until one of them shows that
217 \&\fBp\fR is composite; if \fBp\fR passes all these tests, it is considered
220 \&\fIBN_is_prime_fasttest_ex()\fR, when called with \fBdo_trial_division == 1\fR,
221 first attempts trial division by a number of small primes;
222 if no divisors are found by this test and \fBcb\fR is not \fB\s-1NULL\s0\fR,
223 \&\fBBN_GENCB_call(cb, 1, \-1)\fR is called.
224 If \fBdo_trial_division == 0\fR, this test is skipped.
226 Both \fIBN_is_prime_ex()\fR and \fIBN_is_prime_fasttest_ex()\fR perform a Miller-Rabin
227 probabilistic primality test with \fBnchecks\fR iterations. If
228 \&\fBnchecks == BN_prime_checks\fR, a number of iterations is used that
229 yields a false positive rate of at most 2^\-64 for random input.
230 The error rate depends on the size of the prime and goes down for bigger primes.
231 The rate is 2^\-80 starting at 308 bits, 2^\-112 at 852 bits, 2^\-128 at 1080 bits,
232 2^\-192 at 3747 bits and 2^\-256 at 6394 bits.
234 When the source of the prime is not random or not trusted, the number
235 of checks needs to be much higher to reach the same level of assurance:
236 It should equal half of the targeted security level in bits (rounded up to the
237 next integer if necessary).
238 For instance, to reach the 128 bit security level, \fBnchecks\fR should be set to
241 If \fBcb\fR is not \fB\s-1NULL\s0\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
242 after the j\-th iteration (j = 0, 1, ...). \fBctx\fR is a
243 pre-allocated \fB\s-1BN_CTX\s0\fR (to save the overhead of allocating and
244 freeing the structure in a loop), or \fB\s-1NULL\s0\fR.
246 \&\fIBN_GENCB_call()\fR calls the callback function held in the \fB\s-1BN_GENCB\s0\fR structure
247 and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
248 \&\fB\s-1BN_GENCB\s0\fR structure that are supported: \*(L"new\*(R" style and \*(L"old\*(R" style. New
249 programs should prefer the \*(L"new\*(R" style, whilst the \*(L"old\*(R" style is provided
250 for backwards compatibility purposes.
252 A \fB\s-1BN_GENCB\s0\fR structure should be created through a call to \fIBN_GENCB_new()\fR,
253 and freed through a call to \fIBN_GENCB_free()\fR.
255 For \*(L"new\*(R" style callbacks a \s-1BN_GENCB\s0 structure should be initialised with a
256 call to \fIBN_GENCB_set()\fR, where \fBgencb\fR is a \fB\s-1BN_GENCB\s0 *\fR, \fBcallback\fR is of
257 type \fBint (*callback)(int, int, \s-1BN_GENCB\s0 *)\fR and \fBcb_arg\fR is a \fBvoid *\fR.
258 \&\*(L"Old\*(R" style callbacks are the same except they are initialised with a call
259 to \fIBN_GENCB_set_old()\fR and \fBcallback\fR is of type
260 \&\fBvoid (*callback)(int, int, void *)\fR.
262 A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check
263 the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new
264 style callbacks or \fBcallback(a, b, cb_arg)\fR for old style.
266 It is possible to obtain the argument associated with a \s-1BN_GENCB\s0 structure
267 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
269 \&\fIBN_generate_prime()\fR (deprecated) works in the same way as
270 \&\fIBN_generate_prime_ex()\fR but expects an old-style callback function
271 directly in the \fBcallback\fR parameter, and an argument to pass to it in
272 the \fBcb_arg\fR. \fIBN_is_prime()\fR and \fIBN_is_prime_fasttest()\fR
273 can similarly be compared to \fIBN_is_prime_ex()\fR and
274 \&\fIBN_is_prime_fasttest_ex()\fR, respectively.
276 .IX Header "RETURN VALUES"
277 \&\fIBN_generate_prime_ex()\fR return 1 on success or 0 on error.
279 \&\fIBN_is_prime_ex()\fR, \fIBN_is_prime_fasttest_ex()\fR, \fIBN_is_prime()\fR and
280 \&\fIBN_is_prime_fasttest()\fR return 0 if the number is composite, 1 if it is
281 prime with an error probability of less than 0.25^\fBnchecks\fR, and
284 \&\fIBN_generate_prime()\fR returns the prime number on success, \fB\s-1NULL\s0\fR otherwise.
286 BN_GENCB_new returns a pointer to a \s-1BN_GENCB\s0 structure on success, or \fB\s-1NULL\s0\fR
289 BN_GENCB_get_arg returns the argument previously associated with a \s-1BN_GENCB\s0
292 Callback functions should return 1 on success or 0 on error.
294 The error codes can be obtained by \fIERR_get_error\fR\|(3).
295 .SH "REMOVED FUNCTIONALITY"
296 .IX Header "REMOVED FUNCTIONALITY"
297 As of OpenSSL 1.1.0 it is no longer possible to create a \s-1BN_GENCB\s0 structure
301 \& BN_GENCB callback;
304 Instead applications should create a \s-1BN_GENCB\s0 structure using BN_GENCB_new:
307 \& BN_GENCB *callback;
308 \& callback = BN_GENCB_new();
312 \& BN_GENCB_free(callback);
315 .IX Header "SEE ALSO"
316 \&\fIDH_generate_parameters\fR\|(3), \fIDSA_generate_parameters\fR\|(3),
317 \&\fIRSA_generate_key\fR\|(3), \fIERR_get_error\fR\|(3), \fIRAND_bytes\fR\|(3)
320 \&\fIBN_GENCB_new()\fR, \fIBN_GENCB_free()\fR,
321 and \fIBN_GENCB_get_arg()\fR were added in OpenSSL 1.1.0
323 .IX Header "COPYRIGHT"
324 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
326 Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
327 this file except in compliance with the License. You can obtain a copy
328 in the file \s-1LICENSE\s0 in the source distribution or at
329 <https://www.openssl.org/source/license.html>.