From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/BN_generate_prime.pod | 194 ++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/BN_generate_prime.pod (limited to 'openssl-1.1.0h/doc/crypto/BN_generate_prime.pod') diff --git a/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod b/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod new file mode 100644 index 0000000..c97536b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, +BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, +BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test +for primality + +=head1 SYNOPSIS + + #include + + int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, + const BIGNUM *rem, BN_GENCB *cb); + + int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); + + int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, + int do_trial_division, BN_GENCB *cb); + + int BN_GENCB_call(BN_GENCB *cb, int a, int b); + + BN_GENCB *BN_GENCB_new(void); + + void BN_GENCB_free(BN_GENCB *cb); + + void BN_GENCB_set_old(BN_GENCB *gencb, + void (*callback)(int, int, void *), void *cb_arg); + + void BN_GENCB_set(BN_GENCB *gencb, + int (*callback)(int, int, BN_GENCB *), void *cb_arg); + + void *BN_GENCB_get_arg(BN_GENCB *cb); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, + BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); + + int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, + void *), BN_CTX *ctx, void *cb_arg); + + int BN_is_prime_fasttest(const BIGNUM *a, int checks, + void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, + int do_trial_division); + #endif + +=head1 DESCRIPTION + +BN_generate_prime_ex() generates a pseudo-random prime number of +at least bit length B. +If B is not B, it will be used to store the number. + +If B is not B, it is used as follows: + +=over 2 + +=item * + +B is called after generating the i-th +potential prime number. + +=item * + +While the number is being tested for primality, +B is called as described below. + +=item * + +When a prime has been found, B is called. + +=back + +The prime may have to fulfill additional requirements for use in +Diffie-Hellman key exchange: + +If B is not B, the prime will fulfill the condition p % B +== B (p % B == 1 if B == B) in order to suit a given +generator. + +If B is true, it will be a safe prime (i.e. a prime p so +that (p-1)/2 is also prime). + +The PRNG must be seeded prior to calling BN_generate_prime_ex(). +The prime number generation has a negligible error probability. + +BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B

is +prime. The following tests are performed until one of them shows that +B

is composite; if B

passes all these tests, it is considered +prime. + +BN_is_prime_fasttest_ex(), when called with B, +first attempts trial division by a number of small primes; +if no divisors are found by this test and B is not B, +B is called. +If B, this test is skipped. + +Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin +probabilistic primality test with B iterations. If +B, a number of iterations is used that +yields a false positive rate of at most 2^-80 for random input. + +If B is not B, B is called +after the j-th iteration (j = 0, 1, ...). B is a +pre-allocated B (to save the overhead of allocating and +freeing the structure in a loop), or B. + +BN_GENCB_call calls the callback function held in the B structure +and passes the ints B and B as arguments. There are two types of +B structure that are supported: "new" style and "old" style. New +programs should prefer the "new" style, whilst the "old" style is provided +for backwards compatibility purposes. + +A BN_GENCB structure should be created through a call to BN_GENCB_new(), +and freed through a call to BN_GENCB_free(). + +For "new" style callbacks a BN_GENCB structure should be initialised with a +call to BN_GENCB_set(), where B is a B, B is of +type B and B is a B. +"Old" style callbacks are the same except they are initialised with a call +to BN_GENCB_set_old() and B is of type +B. + +A callback is invoked through a call to B. This will check +the type of the callback and will invoke B for new +style callbacks or B for old style. + +It is possible to obtained the argument associated with a BN_GENCB structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. + +BN_generate_prime (deprecated) works in the same way as +BN_generate_prime_ex but expects an old style callback function +directly in the B parameter, and an argument to pass to it in +the B. Similarly BN_is_prime and BN_is_prime_fasttest are +deprecated and can be compared to BN_is_prime_ex and +BN_is_prime_fasttest_ex respectively. + +=head1 RETURN VALUES + +BN_generate_prime_ex() return 1 on success or 0 on error. + +BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and +BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is +prime with an error probability of less than 0.25^B, and +-1 on error. + +BN_generate_prime() returns the prime number on success, B otherwise. + +BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B +otherwise. + +BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB +structure. + +Callback functions should return 1 on success or 0 on error. + +The error codes can be obtained by L. + +=head1 REMOVED FUNCTIONALITY + +As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure +directly, as in: + + BN_GENCB callback; + +Instead applications should create a BN_GENCB structure using BN_GENCB_new: + + BN_GENCB *callback; + callback = BN_GENCB_new(); + if(!callback) /* handle error */ + ... + BN_GENCB_free(callback); + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +BN_GENCB_new(), BN_GENCB_free(), +and BN_GENCB_get_arg() were added in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3