Debian Codegraph @

upstream/debian-unstable/man3/BN_generate_prime.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BN_GENERATE_PRIME 3SSL"
58 .TH BN_GENERATE_PRIME 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime,
65 BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free,
66 BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime,
67 BN_is_prime, BN_is_prime_fasttest \- generate primes and test for primality
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/bn.h>
72 \&
73 \& int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,
74 \& const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,
75 \& BN_CTX *ctx);
76 \&
77 \& int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
78 \& const BIGNUM *rem, BN_GENCB *cb);
79 \&
80 \& int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);
81 \&
82 \& int BN_GENCB_call(BN_GENCB *cb, int a, int b);
83 \&
84 \& BN_GENCB *BN_GENCB_new(void);
85 \&
86 \& void BN_GENCB_free(BN_GENCB *cb);
87 \&
88 \& void BN_GENCB_set_old(BN_GENCB *gencb,
89 \& void (*callback)(int, int, void *), void *cb_arg);
90 \&
91 \& void BN_GENCB_set(BN_GENCB *gencb,
92 \& int (*callback)(int, int, BN_GENCB *), void *cb_arg);
93 \&
94 \& void *BN_GENCB_get_arg(BN_GENCB *cb);
95 .Ve
96 .PP
97 The following functions have been deprecated since OpenSSL 0.9.8, and can be
98 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
99 see \fBopenssl_user_macros\fR\|(7):
100 .PP
101 .Vb 3
102 \& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
103 \& BIGNUM *rem, void (*callback)(int, int, void *),
104 \& void *cb_arg);
105 \&
106 \& int BN_is_prime(const BIGNUM *p, int nchecks,
107 \& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);
108 \&
109 \& int BN_is_prime_fasttest(const BIGNUM *p, int nchecks,
110 \& void (*callback)(int, int, void *), BN_CTX *ctx,
111 \& void *cb_arg, int do_trial_division);
112 .Ve
113 .PP
114 The following functions have been deprecated since OpenSSL 3.0, and can be
115 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
116 see \fBopenssl_user_macros\fR\|(7):
117 .PP
118 .Vb 1
119 \& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
120 \&
121 \& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
122 \& int do_trial_division, BN_GENCB *cb);
123 .Ve
124 .SH DESCRIPTION
125 .IX Header "DESCRIPTION"
126 \&\fBBN_generate_prime_ex2()\fR generates a pseudo-random prime number of
127 at least bit length \fBbits\fR using the BN_CTX provided in \fBctx\fR. The value of
128 \&\fBctx\fR must not be NULL.
129 .PP
130 The returned number is probably prime with a negligible error.
131 The maximum error rate is 2^\-128.
132 It's 2^\-287 for a 512 bit prime, 2^\-435 for a 1024 bit prime,
133 2^\-648 for a 2048 bit prime, and lower than 2^\-882 for primes larger
134 than 2048 bit.
135 .PP
136 If \fBadd\fR is \fBNULL\fR the returned prime number will have exact bit
137 length \fBbits\fR with the top most two bits set.
138 .PP
139 If \fBret\fR is not \fBNULL\fR, it will be used to store the number.
140 .PP
141 If \fBcb\fR is not \fBNULL\fR, it is used as follows:
142 .IP \(bu 2
143 \&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th
144 potential prime number.
145 .IP \(bu 2
146 While the number is being tested for primality,
147 \&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below.
148 .IP \(bu 2
149 When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called.
150 .IP \(bu 2
151 The callers of \fBBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with
152 other values as described in their respective man pages; see "SEE ALSO".
153 .PP
154 The prime may have to fulfill additional requirements for use in
155 Diffie-Hellman key exchange:
156 .PP
157 If \fBadd\fR is not \fBNULL\fR, the prime will fulfill the condition p % \fBadd\fR
158 == \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fBNULL\fR) in order to suit a given
159 generator.
160 .PP
161 If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so
162 that (p\-1)/2 is also prime). If \fBsafe\fR is true, and \fBrem\fR == \fBNULL\fR
163 the condition will be p % \fBadd\fR == 3.
164 It is recommended that \fBadd\fR is a multiple of 4.
165 .PP
166 The random generator must be seeded prior to calling \fBBN_generate_prime_ex()\fR.
167 If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
168 external circumstances (see \fBRAND\fR\|(7)), the operation will fail.
169 The random number generator configured for the OSSL_LIB_CTX associated with
170 \&\fBctx\fR will be used.
171 .PP
172 \&\fBBN_generate_prime_ex()\fR is the same as \fBBN_generate_prime_ex2()\fR except that no
173 \&\fBctx\fR parameter is passed.
174 In this case the random number generator associated with the default OSSL_LIB_CTX
175 will be used.
176 .PP
177 \&\fBBN_check_prime()\fR, \fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
178 and \fBBN_is_prime_fasttest()\fR test if the number \fBp\fR is prime.
179 The functions tests until one of the tests shows that \fBp\fR is composite,
180 or all the tests passed.
181 If \fBp\fR passes all these tests, it is considered a probable prime.
182 .PP
183 The test performed on \fBp\fR are trial division by a number of small primes
184 and rounds of the Miller-Rabin probabilistic primality test.
185 .PP
186 The functions do at least 64 rounds of the Miller-Rabin test giving a maximum
187 false positive rate of 2^\-128.
188 If the size of \fBp\fR is more than 2048 bits, they do at least 128 rounds
189 giving a maximum false positive rate of 2^\-256.
190 .PP
191 If \fBnchecks\fR is larger than the minimum above (64 or 128), \fBnchecks\fR
192 rounds of the Miller-Rabin test will be done.
193 .PP
194 If \fBdo_trial_division\fR set to \fB0\fR, the trial division will be skipped.
195 \&\fBBN_is_prime_ex()\fR and \fBBN_is_prime()\fR always skip the trial division.
196 .PP
197 \&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR
198 and \fBBN_is_prime_fasttest()\fR are deprecated.
199 .PP
200 \&\fBBN_is_prime_fasttest()\fR and \fBBN_is_prime()\fR behave just like
201 \&\fBBN_is_prime_fasttest_ex()\fR and \fBBN_is_prime_ex()\fR respectively, but with the old
202 style callback.
203 .PP
204 \&\fBctx\fR is a preallocated \fBBN_CTX\fR (to save the overhead of allocating and
205 freeing the structure in a loop), or \fBNULL\fR.
206 .PP
207 If the trial division is done, and no divisors are found and \fBcb\fR
208 is not \fBNULL\fR, \fBBN_GENCB_call(cb, 1, \-1)\fR is called.
209 .PP
210 After each round of the Miller-Rabin probabilistic primality test,
211 if \fBcb\fR is not \fBNULL\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called
212 with \fBj\fR the iteration (j = 0, 1, ...).
213 .PP
214 \&\fBBN_GENCB_call()\fR calls the callback function held in the \fBBN_GENCB\fR structure
215 and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of
216 \&\fBBN_GENCB\fR structure that are supported: "new" style and "old" style. New
217 programs should prefer the "new" style, whilst the "old" style is provided
218 for backwards compatibility purposes.
219 .PP
220 A \fBBN_GENCB\fR structure should be created through a call to \fBBN_GENCB_new()\fR,
221 and freed through a call to \fBBN_GENCB_free()\fR. If the argument is NULL,
222 nothing is done.
223 .PP
224 For "new" style callbacks a BN_GENCB structure should be initialised with a
225 call to \fBBN_GENCB_set()\fR, where \fBgencb\fR is a \fBBN_GENCB *\fR, \fBcallback\fR is of
226 type \fBint (*callback)(int, int, BN_GENCB *)\fR and \fBcb_arg\fR is a \fBvoid *\fR.
227 "Old" style callbacks are the same except they are initialised with a call
228 to \fBBN_GENCB_set_old()\fR and \fBcallback\fR is of type
229 \&\fBvoid (*callback)(int, int, void *)\fR.
230 .PP
231 A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check
232 the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new
233 style callbacks or \fBcallback(a, b, cb_arg)\fR for old style.
234 .PP
235 It is possible to obtain the argument associated with a BN_GENCB structure
236 (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
237 .PP
238 \&\fBBN_generate_prime()\fR (deprecated) works in the same way as
239 \&\fBBN_generate_prime_ex()\fR but expects an old-style callback function
240 directly in the \fBcallback\fR parameter, and an argument to pass to it in
241 the \fBcb_arg\fR. \fBBN_is_prime()\fR and \fBBN_is_prime_fasttest()\fR
242 can similarly be compared to \fBBN_is_prime_ex()\fR and
243 \&\fBBN_is_prime_fasttest_ex()\fR, respectively.
244 .SH "RETURN VALUES"
245 .IX Header "RETURN VALUES"
246 \&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error.
247 .PP
248 \&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR,
249 \&\fBBN_is_prime_fasttest()\fR and BN_check_prime return 0 if the number is composite,
250 1 if it is prime with an error probability of less than 0.25^\fBnchecks\fR, and
251 \&\-1 on error.
252 .PP
253 \&\fBBN_generate_prime()\fR returns the prime number on success, \fBNULL\fR otherwise.
254 .PP
255 BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or \fBNULL\fR
256 otherwise.
257 .PP
258 BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
259 structure.
260 .PP
261 Callback functions should return 1 on success or 0 on error.
262 .PP
263 The error codes can be obtained by \fBERR_get_error\fR\|(3).
264 .SH "REMOVED FUNCTIONALITY"
265 .IX Header "REMOVED FUNCTIONALITY"
266 As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
267 directly, as in:
268 .PP
269 .Vb 1
270 \& BN_GENCB callback;
271 .Ve
272 .PP
273 Instead applications should create a BN_GENCB structure using BN_GENCB_new:
274 .PP
275 .Vb 6
276 \& BN_GENCB *callback;
277 \& callback = BN_GENCB_new();
278 \& if (!callback)
279 \& /* error */
280 \& ...
281 \& BN_GENCB_free(callback);
282 .Ve
283 .SH "SEE ALSO"
284 .IX Header "SEE ALSO"
285 \&\fBDH_generate_parameters\fR\|(3), \fBDSA_generate_parameters\fR\|(3),
286 \&\fBRSA_generate_key\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3),
287 \&\fBRAND\fR\|(7)
288 .SH HISTORY
289 .IX Header "HISTORY"
290 The \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR functions were
291 deprecated in OpenSSL 3.0.
292 .PP
293 The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR,
294 and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0.
295 .PP
296 \&\fBBN_check_prime()\fR was added in OpenSSL 3.0.
297 .SH COPYRIGHT
298 .IX Header "COPYRIGHT"
299 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
300 .PP
301 Licensed under the Apache License 2.0 (the "License"). You may not use
302 this file except in compliance with the License. You can obtain a copy
303 in the file LICENSE in the source distribution or at
304 <https://www.openssl.org/source/license.html>.