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