]>
Commit | Line | Data |
---|---|---|
4486d0cd UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
42619397 | 5 | BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime, |
2934be91 MC |
6 | BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, |
7 | BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime, | |
8 | BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality | |
4486d0cd UM |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/bn.h> | |
13 | ||
2934be91 MC |
14 | int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe, |
15 | const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb, | |
16 | BN_CTX *ctx); | |
17 | ||
aebb9aac | 18 | int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, |
e9b77246 | 19 | const BIGNUM *rem, BN_GENCB *cb); |
aafbe1cc | 20 | |
42619397 | 21 | int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb); |
aafbe1cc MC |
22 | |
23 | int BN_GENCB_call(BN_GENCB *cb, int a, int b); | |
24 | ||
e35af275 | 25 | BN_GENCB *BN_GENCB_new(void); |
aafbe1cc | 26 | |
e35af275 | 27 | void BN_GENCB_free(BN_GENCB *cb); |
aafbe1cc | 28 | |
e35af275 | 29 | void BN_GENCB_set_old(BN_GENCB *gencb, |
e9b77246 | 30 | void (*callback)(int, int, void *), void *cb_arg); |
e35af275 MC |
31 | |
32 | void BN_GENCB_set(BN_GENCB *gencb, | |
e9b77246 | 33 | int (*callback)(int, int, BN_GENCB *), void *cb_arg); |
e35af275 MC |
34 | |
35 | void *BN_GENCB_get_arg(BN_GENCB *cb); | |
aafbe1cc | 36 | |
3dbf8243 MC |
37 | The following functions have been deprecated since OpenSSL 0.9.8, and can be |
38 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
39 | see L<openssl_user_macros(7)>: | |
aafbe1cc | 40 | |
4486d0cd | 41 | BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, |
e9b77246 BB |
42 | BIGNUM *rem, void (*callback)(int, int, void *), |
43 | void *cb_arg); | |
4486d0cd | 44 | |
42619397 | 45 | int BN_is_prime(const BIGNUM *p, int nchecks, |
e9b77246 | 46 | void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); |
4486d0cd | 47 | |
42619397 | 48 | int BN_is_prime_fasttest(const BIGNUM *p, int nchecks, |
e9b77246 BB |
49 | void (*callback)(int, int, void *), BN_CTX *ctx, |
50 | void *cb_arg, int do_trial_division); | |
cdd43b5b | 51 | |
3dbf8243 MC |
52 | The following functions have been deprecated since OpenSSL 3.0, and can be |
53 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
54 | see L<openssl_user_macros(7)>: | |
42619397 KR |
55 | |
56 | int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); | |
57 | ||
58 | int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, | |
59 | int do_trial_division, BN_GENCB *cb); | |
60 | ||
4486d0cd UM |
61 | =head1 DESCRIPTION |
62 | ||
2934be91 MC |
63 | BN_generate_prime_ex2() generates a pseudo-random prime number of |
64 | at least bit length B<bits> using the BN_CTX provided in B<ctx>. The value of | |
65 | B<ctx> must not be NULL. | |
42619397 | 66 | |
2934be91 | 67 | The returned number is probably prime with a negligible error. |
42619397 KR |
68 | The maximum error rate is 2^-128. |
69 | It's 2^-287 for a 512 bit prime, 2^-435 for a 1024 bit prime, | |
70 | 2^-648 for a 2048 bit prime, and lower than 2^-882 for primes larger | |
71 | than 2048 bit. | |
72 | ||
03b9393e BE |
73 | If B<add> is B<NULL> the returned prime number will have exact bit |
74 | length B<bits> with the top most two bits set. | |
262c0088 | 75 | |
cdd43b5b | 76 | If B<ret> is not B<NULL>, it will be used to store the number. |
4486d0cd | 77 | |
aafbe1cc | 78 | If B<cb> is not B<NULL>, it is used as follows: |
4486d0cd | 79 | |
2f61bc2e | 80 | =over 2 |
4486d0cd UM |
81 | |
82 | =item * | |
83 | ||
aafbe1cc | 84 | B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th |
4486d0cd UM |
85 | potential prime number. |
86 | ||
87 | =item * | |
88 | ||
aafbe1cc MC |
89 | While the number is being tested for primality, |
90 | B<BN_GENCB_call(cb, 1, j)> is called as described below. | |
4486d0cd UM |
91 | |
92 | =item * | |
93 | ||
aafbe1cc | 94 | When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called. |
4486d0cd | 95 | |
bd93f1ac BB |
96 | =item * |
97 | ||
98 | The callers of BN_generate_prime_ex() may call B<BN_GENCB_call(cb, i, j)> with | |
99 | other values as described in their respective man pages; see L</SEE ALSO>. | |
100 | ||
4486d0cd UM |
101 | =back |
102 | ||
103 | The prime may have to fulfill additional requirements for use in | |
104 | Diffie-Hellman key exchange: | |
105 | ||
cdd43b5b BM |
106 | If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> |
107 | == B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given | |
4486d0cd UM |
108 | generator. |
109 | ||
110 | If B<safe> is true, it will be a safe prime (i.e. a prime p so | |
03b9393e BE |
111 | that (p-1)/2 is also prime). If B<safe> is true, and B<rem> == B<NULL> |
112 | the condition will be p % B<add> == 3. | |
113 | It is recommended that B<add> is a multiple of 4. | |
4486d0cd | 114 | |
262c0088 DMSP |
115 | The random generator must be seeded prior to calling BN_generate_prime_ex(). |
116 | If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to | |
117 | external circumstances (see L<RAND(7)>), the operation will fail. | |
b4250010 | 118 | The random number generator configured for the OSSL_LIB_CTX associated with |
2934be91 MC |
119 | B<ctx> will be used. |
120 | ||
121 | BN_generate_prime_ex() is the same as BN_generate_prime_ex2() except that no | |
122 | B<ctx> parameter is passed. | |
b4250010 | 123 | In this case the random number generator associated with the default OSSL_LIB_CTX |
2934be91 | 124 | will be used. |
4486d0cd | 125 | |
42619397 KR |
126 | BN_check_prime(), BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() |
127 | and BN_is_prime_fasttest() test if the number B<p> is prime. | |
128 | The functions tests until one of the tests shows that B<p> is composite, | |
129 | or all the tests passed. | |
130 | If B<p> passes all these tests, it is considered a probable prime. | |
131 | ||
132 | The test performed on B<p> are trial division by a number of small primes | |
133 | and rounds of the of the Miller-Rabin probabilistic primality test. | |
134 | ||
135 | The functions do at least 64 rounds of the Miller-Rabin test giving a maximum | |
136 | false positive rate of 2^-128. | |
137 | If the size of B<p> is more than 2048 bits, they do at least 128 rounds | |
138 | giving a maximum false positive rate of 2^-256. | |
139 | ||
140 | If B<nchecks> is larger than the minimum above (64 or 128), B<nchecks> | |
141 | rounds of the Miller-Rabin test will be done. | |
142 | ||
143 | If B<do_trial_division> set to B<0>, the trial division will be skipped. | |
144 | BN_is_prime_ex() and BN_is_prime() always skip the trial division. | |
145 | ||
146 | BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() | |
147 | and BN_is_prime_fasttest() are deprecated. | |
148 | ||
149 | BN_is_prime_fasttest() and BN_is_prime() behave just like | |
150 | BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old | |
151 | style call back. | |
152 | ||
490c8711 | 153 | B<ctx> is a preallocated B<BN_CTX> (to save the overhead of allocating and |
e74231ed | 154 | freeing the structure in a loop), or B<NULL>. |
cdd43b5b | 155 | |
42619397 KR |
156 | If the trial division is done, and no divisors are found and B<cb> |
157 | is not B<NULL>, B<BN_GENCB_call(cb, 1, -1)> is called. | |
158 | ||
159 | After each round of the Miller-Rabin probabilistic primality test, | |
160 | if B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called | |
161 | with B<j> the iteration (j = 0, 1, ...). | |
162 | ||
b3696a55 | 163 | BN_GENCB_call() calls the callback function held in the B<BN_GENCB> structure |
aafbe1cc MC |
164 | and passes the ints B<a> and B<b> as arguments. There are two types of |
165 | B<BN_GENCB> structure that are supported: "new" style and "old" style. New | |
166 | programs should prefer the "new" style, whilst the "old" style is provided | |
167 | for backwards compatibility purposes. | |
168 | ||
b3696a55 | 169 | A B<BN_GENCB> structure should be created through a call to BN_GENCB_new(), |
23a1d5e9 | 170 | and freed through a call to BN_GENCB_free(). |
e35af275 | 171 | |
aafbe1cc | 172 | For "new" style callbacks a BN_GENCB structure should be initialised with a |
2afb29b4 | 173 | call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of |
aafbe1cc MC |
174 | type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>. |
175 | "Old" style callbacks are the same except they are initialised with a call | |
2afb29b4 | 176 | to BN_GENCB_set_old() and B<callback> is of type |
aafbe1cc MC |
177 | B<void (*callback)(int, int, void *)>. |
178 | ||
179 | A callback is invoked through a call to B<BN_GENCB_call>. This will check | |
180 | the type of the callback and will invoke B<callback(a, b, gencb)> for new | |
181 | style callbacks or B<callback(a, b, cb_arg)> for old style. | |
182 | ||
a21285b3 | 183 | It is possible to obtain the argument associated with a BN_GENCB structure |
e35af275 MC |
184 | (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. |
185 | ||
b3696a55 RS |
186 | BN_generate_prime() (deprecated) works in the same way as |
187 | BN_generate_prime_ex() but expects an old-style callback function | |
aafbe1cc | 188 | directly in the B<callback> parameter, and an argument to pass to it in |
b3696a55 RS |
189 | the B<cb_arg>. BN_is_prime() and BN_is_prime_fasttest() |
190 | can similarly be compared to BN_is_prime_ex() and | |
191 | BN_is_prime_fasttest_ex(), respectively. | |
aafbe1cc | 192 | |
4486d0cd UM |
193 | =head1 RETURN VALUES |
194 | ||
aafbe1cc | 195 | BN_generate_prime_ex() return 1 on success or 0 on error. |
4486d0cd | 196 | |
42619397 KR |
197 | BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime(), |
198 | BN_is_prime_fasttest() and BN_check_prime return 0 if the number is composite, | |
199 | 1 if it is prime with an error probability of less than 0.25^B<nchecks>, and | |
4486d0cd UM |
200 | -1 on error. |
201 | ||
aafbe1cc MC |
202 | BN_generate_prime() returns the prime number on success, B<NULL> otherwise. |
203 | ||
e35af275 MC |
204 | BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL> |
205 | otherwise. | |
206 | ||
207 | BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB | |
208 | structure. | |
209 | ||
aafbe1cc MC |
210 | Callback functions should return 1 on success or 0 on error. |
211 | ||
9b86974e | 212 | The error codes can be obtained by L<ERR_get_error(3)>. |
4486d0cd | 213 | |
e35af275 MC |
214 | =head1 REMOVED FUNCTIONALITY |
215 | ||
216 | As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure | |
217 | directly, as in: | |
218 | ||
219 | BN_GENCB callback; | |
220 | ||
221 | Instead applications should create a BN_GENCB structure using BN_GENCB_new: | |
222 | ||
223 | BN_GENCB *callback; | |
224 | callback = BN_GENCB_new(); | |
2947af32 BB |
225 | if (!callback) |
226 | /* error */ | |
e35af275 MC |
227 | ... |
228 | BN_GENCB_free(callback); | |
229 | ||
4486d0cd UM |
230 | =head1 SEE ALSO |
231 | ||
bd93f1ac | 232 | L<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>, |
262c0088 DMSP |
233 | L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, |
234 | L<RAND(7)> | |
4486d0cd UM |
235 | |
236 | =head1 HISTORY | |
237 | ||
93b39c85 TM |
238 | The BN_is_prime_ex() and BN_is_prime_fasttest_ex() functions were |
239 | deprecated in OpenSSL 3.0. | |
240 | ||
fc5ecadd DMSP |
241 | The BN_GENCB_new(), BN_GENCB_free(), |
242 | and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0. | |
4486d0cd | 243 | |
42619397 KR |
244 | BN_check_prime() was added in OpenSSL 3.0. |
245 | ||
e2f92610 RS |
246 | =head1 COPYRIGHT |
247 | ||
a28d06f3 | 248 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 249 | |
4746f25a | 250 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
251 | this file except in compliance with the License. You can obtain a copy |
252 | in the file LICENSE in the source distribution or at | |
253 | L<https://www.openssl.org/source/license.html>. | |
254 | ||
255 | =cut |