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