]>
Commit | Line | Data |
---|---|---|
4486d0cd UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, |
e35af275 MC |
6 | BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, |
7 | BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test | |
8 | for primality | |
4486d0cd UM |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/bn.h> | |
13 | ||
aebb9aac | 14 | int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, |
aafbe1cc MC |
15 | const BIGNUM *rem, BN_GENCB *cb); |
16 | ||
aebb9aac | 17 | int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); |
aafbe1cc | 18 | |
aebb9aac | 19 | int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, |
aafbe1cc MC |
20 | int do_trial_division, BN_GENCB *cb); |
21 | ||
22 | int BN_GENCB_call(BN_GENCB *cb, int a, int b); | |
23 | ||
e35af275 | 24 | BN_GENCB *BN_GENCB_new(void); |
aafbe1cc | 25 | |
e35af275 | 26 | void BN_GENCB_free(BN_GENCB *cb); |
aafbe1cc | 27 | |
e35af275 MC |
28 | void BN_GENCB_set_old(BN_GENCB *gencb, |
29 | void (*callback)(int, int, void *), void *cb_arg); | |
30 | ||
31 | void BN_GENCB_set(BN_GENCB *gencb, | |
32 | int (*callback)(int, int, BN_GENCB *), void *cb_arg); | |
33 | ||
34 | void *BN_GENCB_get_arg(BN_GENCB *cb); | |
aafbe1cc MC |
35 | |
36 | Deprecated: | |
37 | ||
98186eb4 | 38 | #if OPENSSL_API_COMPAT < 0x00908000L |
4486d0cd UM |
39 | BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, |
40 | BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); | |
41 | ||
1bc74519 | 42 | int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, |
4486d0cd UM |
43 | void *), BN_CTX *ctx, void *cb_arg); |
44 | ||
aff0825c BM |
45 | int BN_is_prime_fasttest(const BIGNUM *a, int checks, |
46 | void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, | |
47 | int do_trial_division); | |
98186eb4 | 48 | #endif |
cdd43b5b | 49 | |
4486d0cd UM |
50 | =head1 DESCRIPTION |
51 | ||
aafbe1cc | 52 | BN_generate_prime_ex() generates a pseudo-random prime number of |
a0490e02 | 53 | at least bit length B<bits>. |
cdd43b5b | 54 | If B<ret> is not B<NULL>, it will be used to store the number. |
4486d0cd | 55 | |
aafbe1cc | 56 | If B<cb> is not B<NULL>, it is used as follows: |
4486d0cd UM |
57 | |
58 | =over 4 | |
59 | ||
60 | =item * | |
61 | ||
aafbe1cc | 62 | B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th |
4486d0cd UM |
63 | potential prime number. |
64 | ||
65 | =item * | |
66 | ||
aafbe1cc MC |
67 | While the number is being tested for primality, |
68 | B<BN_GENCB_call(cb, 1, j)> is called as described below. | |
4486d0cd UM |
69 | |
70 | =item * | |
71 | ||
aafbe1cc | 72 | When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called. |
4486d0cd UM |
73 | |
74 | =back | |
75 | ||
76 | The prime may have to fulfill additional requirements for use in | |
77 | Diffie-Hellman key exchange: | |
78 | ||
cdd43b5b BM |
79 | If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> |
80 | == B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given | |
4486d0cd UM |
81 | generator. |
82 | ||
83 | If B<safe> is true, it will be a safe prime (i.e. a prime p so | |
84 | that (p-1)/2 is also prime). | |
85 | ||
aafbe1cc | 86 | The PRNG must be seeded prior to calling BN_generate_prime_ex(). |
4486d0cd UM |
87 | The prime number generation has a negligible error probability. |
88 | ||
aafbe1cc | 89 | BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is |
cdd43b5b | 90 | prime. The following tests are performed until one of them shows that |
aafbe1cc | 91 | B<p> is composite; if B<p> passes all these tests, it is considered |
cdd43b5b BM |
92 | prime. |
93 | ||
aafbe1cc | 94 | BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>, |
cdd43b5b | 95 | first attempts trial division by a number of small primes; |
aafbe1cc MC |
96 | if no divisors are found by this test and B<cb> is not B<NULL>, |
97 | B<BN_GENCB_call(cb, 1, -1)> is called. | |
cdd43b5b BM |
98 | If B<do_trial_division == 0>, this test is skipped. |
99 | ||
aafbe1cc MC |
100 | Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin |
101 | probabilistic primality test with B<nchecks> iterations. If | |
102 | B<nchecks == BN_prime_checks>, a number of iterations is used that | |
cdd43b5b | 103 | yields a false positive rate of at most 2^-80 for random input. |
4486d0cd | 104 | |
aafbe1cc | 105 | If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called |
cdd43b5b BM |
106 | after the j-th iteration (j = 0, 1, ...). B<ctx> is a |
107 | pre-allocated B<BN_CTX> (to save the overhead of allocating and | |
e74231ed | 108 | freeing the structure in a loop), or B<NULL>. |
cdd43b5b | 109 | |
aafbe1cc MC |
110 | BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure |
111 | and passes the ints B<a> and B<b> as arguments. There are two types of | |
112 | B<BN_GENCB> structure that are supported: "new" style and "old" style. New | |
113 | programs should prefer the "new" style, whilst the "old" style is provided | |
114 | for backwards compatibility purposes. | |
115 | ||
23a1d5e9 RS |
116 | A BN_GENCB structure should be created through a call to BN_GENCB_new(), |
117 | and freed through a call to BN_GENCB_free(). | |
e35af275 | 118 | |
aafbe1cc | 119 | For "new" style callbacks a BN_GENCB structure should be initialised with a |
2afb29b4 | 120 | call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of |
aafbe1cc MC |
121 | type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>. |
122 | "Old" style callbacks are the same except they are initialised with a call | |
2afb29b4 | 123 | to BN_GENCB_set_old() and B<callback> is of type |
aafbe1cc MC |
124 | B<void (*callback)(int, int, void *)>. |
125 | ||
126 | A callback is invoked through a call to B<BN_GENCB_call>. This will check | |
127 | the type of the callback and will invoke B<callback(a, b, gencb)> for new | |
128 | style callbacks or B<callback(a, b, cb_arg)> for old style. | |
129 | ||
e35af275 MC |
130 | It is possible to obtained the argument associated with a BN_GENCB structure |
131 | (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. | |
132 | ||
aafbe1cc MC |
133 | BN_generate_prime (deprecated) works in the same way as |
134 | BN_generate_prime_ex but expects an old style callback function | |
135 | directly in the B<callback> parameter, and an argument to pass to it in | |
136 | the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are | |
137 | deprecated and can be compared to BN_is_prime_ex and | |
138 | BN_is_prime_fasttest_ex respectively. | |
139 | ||
4486d0cd UM |
140 | =head1 RETURN VALUES |
141 | ||
aafbe1cc | 142 | BN_generate_prime_ex() return 1 on success or 0 on error. |
4486d0cd | 143 | |
aafbe1cc MC |
144 | BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and |
145 | BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is | |
146 | prime with an error probability of less than 0.25^B<nchecks>, and | |
4486d0cd UM |
147 | -1 on error. |
148 | ||
aafbe1cc MC |
149 | BN_generate_prime() returns the prime number on success, B<NULL> otherwise. |
150 | ||
e35af275 MC |
151 | BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL> |
152 | otherwise. | |
153 | ||
154 | BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB | |
155 | structure. | |
156 | ||
aafbe1cc MC |
157 | Callback functions should return 1 on success or 0 on error. |
158 | ||
9b86974e | 159 | The error codes can be obtained by L<ERR_get_error(3)>. |
4486d0cd | 160 | |
e35af275 MC |
161 | =head1 REMOVED FUNCTIONALITY |
162 | ||
163 | As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure | |
164 | directly, as in: | |
165 | ||
166 | BN_GENCB callback; | |
167 | ||
168 | Instead applications should create a BN_GENCB structure using BN_GENCB_new: | |
169 | ||
170 | BN_GENCB *callback; | |
171 | callback = BN_GENCB_new(); | |
172 | if(!callback) /* handle error */ | |
173 | ... | |
174 | BN_GENCB_free(callback); | |
175 | ||
4486d0cd UM |
176 | =head1 SEE ALSO |
177 | ||
9e183d22 | 178 | L<ERR_get_error(3)>, L<RAND_bytes(3)> |
4486d0cd UM |
179 | |
180 | =head1 HISTORY | |
181 | ||
a528d4f0 RS |
182 | BN_GENCB_new(), BN_GENCB_free(), |
183 | and BN_GENCB_get_arg() were added in OpenSSL 1.1.0 | |
4486d0cd | 184 | |
e2f92610 RS |
185 | =head1 COPYRIGHT |
186 | ||
9e183d22 | 187 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
188 | |
189 | Licensed under the OpenSSL license (the "License"). You may not use | |
190 | this file except in compliance with the License. You can obtain a copy | |
191 | in the file LICENSE in the source distribution or at | |
192 | L<https://www.openssl.org/source/license.html>. | |
193 | ||
194 | =cut |