1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimBN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, 6e71b7053SJung-uk KimBN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, 7e71b7053SJung-uk KimBN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test 8e71b7053SJung-uk Kimfor primality 9e71b7053SJung-uk Kim 10e71b7053SJung-uk Kim=head1 SYNOPSIS 11e71b7053SJung-uk Kim 12e71b7053SJung-uk Kim #include <openssl/bn.h> 13e71b7053SJung-uk Kim 14e71b7053SJung-uk Kim int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, 15e71b7053SJung-uk Kim const BIGNUM *rem, BN_GENCB *cb); 16e71b7053SJung-uk Kim 17e71b7053SJung-uk Kim int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); 18e71b7053SJung-uk Kim 19e71b7053SJung-uk Kim int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, 20e71b7053SJung-uk Kim int do_trial_division, BN_GENCB *cb); 21e71b7053SJung-uk Kim 22e71b7053SJung-uk Kim int BN_GENCB_call(BN_GENCB *cb, int a, int b); 23e71b7053SJung-uk Kim 24e71b7053SJung-uk Kim BN_GENCB *BN_GENCB_new(void); 25e71b7053SJung-uk Kim 26e71b7053SJung-uk Kim void BN_GENCB_free(BN_GENCB *cb); 27e71b7053SJung-uk Kim 28e71b7053SJung-uk Kim void BN_GENCB_set_old(BN_GENCB *gencb, 29e71b7053SJung-uk Kim void (*callback)(int, int, void *), void *cb_arg); 30e71b7053SJung-uk Kim 31e71b7053SJung-uk Kim void BN_GENCB_set(BN_GENCB *gencb, 32e71b7053SJung-uk Kim int (*callback)(int, int, BN_GENCB *), void *cb_arg); 33e71b7053SJung-uk Kim 34e71b7053SJung-uk Kim void *BN_GENCB_get_arg(BN_GENCB *cb); 35e71b7053SJung-uk Kim 36e71b7053SJung-uk KimDeprecated: 37e71b7053SJung-uk Kim 38e71b7053SJung-uk Kim #if OPENSSL_API_COMPAT < 0x00908000L 39e71b7053SJung-uk Kim BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, 40e71b7053SJung-uk Kim BIGNUM *rem, void (*callback)(int, int, void *), 41e71b7053SJung-uk Kim void *cb_arg); 42e71b7053SJung-uk Kim 43e71b7053SJung-uk Kim int BN_is_prime(const BIGNUM *a, int checks, 44e71b7053SJung-uk Kim void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); 45e71b7053SJung-uk Kim 46e71b7053SJung-uk Kim int BN_is_prime_fasttest(const BIGNUM *a, int checks, 47e71b7053SJung-uk Kim void (*callback)(int, int, void *), BN_CTX *ctx, 48e71b7053SJung-uk Kim void *cb_arg, int do_trial_division); 49e71b7053SJung-uk Kim #endif 50e71b7053SJung-uk Kim 51e71b7053SJung-uk Kim=head1 DESCRIPTION 52e71b7053SJung-uk Kim 53e71b7053SJung-uk KimBN_generate_prime_ex() generates a pseudo-random prime number of 54*da327cd2SJung-uk Kimat least bit length B<bits>. The returned number is probably prime 55*da327cd2SJung-uk Kimwith a negligible error. 56*da327cd2SJung-uk Kim 57e71b7053SJung-uk KimIf B<ret> is not B<NULL>, it will be used to store the number. 58e71b7053SJung-uk Kim 59e71b7053SJung-uk KimIf B<cb> is not B<NULL>, it is used as follows: 60e71b7053SJung-uk Kim 61e71b7053SJung-uk Kim=over 2 62e71b7053SJung-uk Kim 63e71b7053SJung-uk Kim=item * 64e71b7053SJung-uk Kim 65e71b7053SJung-uk KimB<BN_GENCB_call(cb, 0, i)> is called after generating the i-th 66e71b7053SJung-uk Kimpotential prime number. 67e71b7053SJung-uk Kim 68e71b7053SJung-uk Kim=item * 69e71b7053SJung-uk Kim 70e71b7053SJung-uk KimWhile the number is being tested for primality, 71e71b7053SJung-uk KimB<BN_GENCB_call(cb, 1, j)> is called as described below. 72e71b7053SJung-uk Kim 73e71b7053SJung-uk Kim=item * 74e71b7053SJung-uk Kim 75e71b7053SJung-uk KimWhen a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called. 76e71b7053SJung-uk Kim 77e71b7053SJung-uk Kim=item * 78e71b7053SJung-uk Kim 79e71b7053SJung-uk KimThe callers of BN_generate_prime_ex() may call B<BN_GENCB_call(cb, i, j)> with 80e71b7053SJung-uk Kimother values as described in their respective man pages; see L</SEE ALSO>. 81e71b7053SJung-uk Kim 82e71b7053SJung-uk Kim=back 83e71b7053SJung-uk Kim 84e71b7053SJung-uk KimThe prime may have to fulfill additional requirements for use in 85e71b7053SJung-uk KimDiffie-Hellman key exchange: 86e71b7053SJung-uk Kim 87e71b7053SJung-uk KimIf B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> 88e71b7053SJung-uk Kim== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given 89e71b7053SJung-uk Kimgenerator. 90e71b7053SJung-uk Kim 91e71b7053SJung-uk KimIf B<safe> is true, it will be a safe prime (i.e. a prime p so 92e71b7053SJung-uk Kimthat (p-1)/2 is also prime). 93e71b7053SJung-uk Kim 94*da327cd2SJung-uk KimThe random generator must be seeded prior to calling BN_generate_prime_ex(). 95*da327cd2SJung-uk KimIf the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to 96*da327cd2SJung-uk Kimexternal circumstances (see L<RAND(7)>), the operation will fail. 97e71b7053SJung-uk Kim 98e71b7053SJung-uk KimBN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is 99e71b7053SJung-uk Kimprime. The following tests are performed until one of them shows that 100e71b7053SJung-uk KimB<p> is composite; if B<p> passes all these tests, it is considered 101e71b7053SJung-uk Kimprime. 102e71b7053SJung-uk Kim 103e71b7053SJung-uk KimBN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>, 104e71b7053SJung-uk Kimfirst attempts trial division by a number of small primes; 105e71b7053SJung-uk Kimif no divisors are found by this test and B<cb> is not B<NULL>, 106e71b7053SJung-uk KimB<BN_GENCB_call(cb, 1, -1)> is called. 107e71b7053SJung-uk KimIf B<do_trial_division == 0>, this test is skipped. 108e71b7053SJung-uk Kim 109e71b7053SJung-uk KimBoth BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin 110e71b7053SJung-uk Kimprobabilistic primality test with B<nchecks> iterations. If 111e71b7053SJung-uk KimB<nchecks == BN_prime_checks>, a number of iterations is used that 112e71b7053SJung-uk Kimyields a false positive rate of at most 2^-64 for random input. 113e71b7053SJung-uk KimThe error rate depends on the size of the prime and goes down for bigger primes. 114e71b7053SJung-uk KimThe rate is 2^-80 starting at 308 bits, 2^-112 at 852 bits, 2^-128 at 1080 bits, 115e71b7053SJung-uk Kim2^-192 at 3747 bits and 2^-256 at 6394 bits. 116e71b7053SJung-uk Kim 117e71b7053SJung-uk KimWhen the source of the prime is not random or not trusted, the number 118e71b7053SJung-uk Kimof checks needs to be much higher to reach the same level of assurance: 119e71b7053SJung-uk KimIt should equal half of the targeted security level in bits (rounded up to the 120e71b7053SJung-uk Kimnext integer if necessary). 121e71b7053SJung-uk KimFor instance, to reach the 128 bit security level, B<nchecks> should be set to 122e71b7053SJung-uk Kim64. 123e71b7053SJung-uk Kim 124e71b7053SJung-uk KimIf B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called 125e71b7053SJung-uk Kimafter the j-th iteration (j = 0, 1, ...). B<ctx> is a 126e71b7053SJung-uk Kimpre-allocated B<BN_CTX> (to save the overhead of allocating and 127e71b7053SJung-uk Kimfreeing the structure in a loop), or B<NULL>. 128e71b7053SJung-uk Kim 129e71b7053SJung-uk KimBN_GENCB_call() calls the callback function held in the B<BN_GENCB> structure 130e71b7053SJung-uk Kimand passes the ints B<a> and B<b> as arguments. There are two types of 131e71b7053SJung-uk KimB<BN_GENCB> structure that are supported: "new" style and "old" style. New 132e71b7053SJung-uk Kimprograms should prefer the "new" style, whilst the "old" style is provided 133e71b7053SJung-uk Kimfor backwards compatibility purposes. 134e71b7053SJung-uk Kim 135e71b7053SJung-uk KimA B<BN_GENCB> structure should be created through a call to BN_GENCB_new(), 136e71b7053SJung-uk Kimand freed through a call to BN_GENCB_free(). 137e71b7053SJung-uk Kim 138e71b7053SJung-uk KimFor "new" style callbacks a BN_GENCB structure should be initialised with a 139e71b7053SJung-uk Kimcall to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of 140e71b7053SJung-uk Kimtype B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>. 141e71b7053SJung-uk Kim"Old" style callbacks are the same except they are initialised with a call 142e71b7053SJung-uk Kimto BN_GENCB_set_old() and B<callback> is of type 143e71b7053SJung-uk KimB<void (*callback)(int, int, void *)>. 144e71b7053SJung-uk Kim 145e71b7053SJung-uk KimA callback is invoked through a call to B<BN_GENCB_call>. This will check 146e71b7053SJung-uk Kimthe type of the callback and will invoke B<callback(a, b, gencb)> for new 147e71b7053SJung-uk Kimstyle callbacks or B<callback(a, b, cb_arg)> for old style. 148e71b7053SJung-uk Kim 149e71b7053SJung-uk KimIt is possible to obtain the argument associated with a BN_GENCB structure 150e71b7053SJung-uk Kim(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. 151e71b7053SJung-uk Kim 152e71b7053SJung-uk KimBN_generate_prime() (deprecated) works in the same way as 153e71b7053SJung-uk KimBN_generate_prime_ex() but expects an old-style callback function 154e71b7053SJung-uk Kimdirectly in the B<callback> parameter, and an argument to pass to it in 155e71b7053SJung-uk Kimthe B<cb_arg>. BN_is_prime() and BN_is_prime_fasttest() 156e71b7053SJung-uk Kimcan similarly be compared to BN_is_prime_ex() and 157e71b7053SJung-uk KimBN_is_prime_fasttest_ex(), respectively. 158e71b7053SJung-uk Kim 159e71b7053SJung-uk Kim=head1 RETURN VALUES 160e71b7053SJung-uk Kim 161e71b7053SJung-uk KimBN_generate_prime_ex() return 1 on success or 0 on error. 162e71b7053SJung-uk Kim 163e71b7053SJung-uk KimBN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and 164e71b7053SJung-uk KimBN_is_prime_fasttest() return 0 if the number is composite, 1 if it is 165e71b7053SJung-uk Kimprime with an error probability of less than 0.25^B<nchecks>, and 166e71b7053SJung-uk Kim-1 on error. 167e71b7053SJung-uk Kim 168e71b7053SJung-uk KimBN_generate_prime() returns the prime number on success, B<NULL> otherwise. 169e71b7053SJung-uk Kim 170e71b7053SJung-uk KimBN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL> 171e71b7053SJung-uk Kimotherwise. 172e71b7053SJung-uk Kim 173e71b7053SJung-uk KimBN_GENCB_get_arg returns the argument previously associated with a BN_GENCB 174e71b7053SJung-uk Kimstructure. 175e71b7053SJung-uk Kim 176e71b7053SJung-uk KimCallback functions should return 1 on success or 0 on error. 177e71b7053SJung-uk Kim 178e71b7053SJung-uk KimThe error codes can be obtained by L<ERR_get_error(3)>. 179e71b7053SJung-uk Kim 180e71b7053SJung-uk Kim=head1 REMOVED FUNCTIONALITY 181e71b7053SJung-uk Kim 182e71b7053SJung-uk KimAs of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure 183e71b7053SJung-uk Kimdirectly, as in: 184e71b7053SJung-uk Kim 185e71b7053SJung-uk Kim BN_GENCB callback; 186e71b7053SJung-uk Kim 187e71b7053SJung-uk KimInstead applications should create a BN_GENCB structure using BN_GENCB_new: 188e71b7053SJung-uk Kim 189e71b7053SJung-uk Kim BN_GENCB *callback; 190e71b7053SJung-uk Kim callback = BN_GENCB_new(); 191e71b7053SJung-uk Kim if (!callback) 192e71b7053SJung-uk Kim /* error */ 193e71b7053SJung-uk Kim ... 194e71b7053SJung-uk Kim BN_GENCB_free(callback); 195e71b7053SJung-uk Kim 196e71b7053SJung-uk Kim=head1 SEE ALSO 197e71b7053SJung-uk Kim 198e71b7053SJung-uk KimL<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>, 199*da327cd2SJung-uk KimL<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, 200*da327cd2SJung-uk KimL<RAND(7)> 201e71b7053SJung-uk Kim 202e71b7053SJung-uk Kim=head1 HISTORY 203e71b7053SJung-uk Kim 2046935a639SJung-uk KimThe BN_GENCB_new(), BN_GENCB_free(), 2056935a639SJung-uk Kimand BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0. 206e71b7053SJung-uk Kim 207e71b7053SJung-uk Kim=head1 COPYRIGHT 208e71b7053SJung-uk Kim 209*da327cd2SJung-uk KimCopyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. 210e71b7053SJung-uk Kim 211e71b7053SJung-uk KimLicensed under the OpenSSL license (the "License"). You may not use 212e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 213e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 214e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 215e71b7053SJung-uk Kim 216e71b7053SJung-uk Kim=cut 217