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