/usr/man/cat.3/BN_generate_prime.3

BN_generate_prime(3)         OpenSSL         BN_generate_prime(3)

NAME

     BN_generate_prime_ex, BN_is_prime_ex,
     BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_set_old,
     BN_GENCB_set, BN_generate_prime, BN_is_prime,
     BN_is_prime_fasttest - generate primes and test for
     primality

SYNOPSIS

      #include <openssl/bn.h>

      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);

      #define BN_GENCB_set_old(gencb, callback, cb_arg) ...

      #define BN_GENCB_set(gencb, callback, cb_arg) ...

     Deprecated:

      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);

DESCRIPTION

     BN_generate_prime_ex() generates a pseudo-random prime
     number of bit length bits.  If ret is not NULL, it will be
     used to store the number.

     If cb is not NULL, it is used as follows:

     o   BN_GENCB_call(cb, 0, i) is called after generating the
         i-th potential prime number.

     o   While the number is being tested for primality,
         BN_GENCB_call(cb, 1, j) is called as described below.

     o   When a prime has been found, BN_GENCB_call(cb, 2, i) is
         called.

1.0.2t               Last change: 2019-09-10                    1

BN_generate_prime(3)         OpenSSL         BN_generate_prime(3)

     The prime may have to fulfill additional requirements for
     use in Diffie-Hellman key exchange:

     If add is not NULL, the prime will fulfill the condition p %
     add == rem (p % add == 1 if rem == NULL) in order to suit a
     given generator.

     If safe 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 p is prime.  The following tests are performed until
     one of them shows that p is composite; if p passes all these
     tests, it is considered prime.

     BN_is_prime_fasttest_ex(), when called with
     do_trial_division == 1, first attempts trial division by a
     number of small primes; if no divisors are found by this
     test and cb is not NULL, BN_GENCB_call(cb, 1, -1) is called.
     If do_trial_division == 0, this test is skipped.

     Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform
     a Miller-Rabin probabilistic primality test with nchecks
     iterations. If nchecks == BN_prime_checks, a number of
     iterations is used that yields a false positive rate of at
     most 2^-64 for random input.  The error rate depends on the
     size of the prime and goes down for bigger primes.  The rate
     is 2^-80 starting at 308 bits, 2^-112 at 852 bits, 2^-128 at
     1080 bits, 2^-192 at 3747 bits and 2^-256 at 6394 bits.

     When the source of the prime is not random or not trusted,
     the number of checks needs to be much higher to reach the
     same level of assurance:  It should equal half of the
     targeted security level in bits (rounded up to the next
     integer if necessary).  For instance, to reach the 128 bit
     security level, nchecks should be set to 64.

     If cb is not NULL, BN_GENCB_call(cb, 1, j) is called after
     the j-th iteration (j = 0, 1, ...). ctx is a pre-allocated
     BN_CTX (to save the overhead of allocating and freeing the
     structure in a loop), or NULL.

     BN_GENCB_call calls the callback function held in the
     BN_GENCB structure and passes the ints a and b as arguments.
     There are two types of BN_GENCB 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.

1.0.2t               Last change: 2019-09-10                    2

BN_generate_prime(3)         OpenSSL         BN_generate_prime(3)

     For "new" style callbacks a BN_GENCB structure should be
     initialised with a call to BN_GENCB_set, where gencb is a
     BN_GENCB *, callback is of type int (*callback)(int, int,
     BN_GENCB *) and cb_arg is a void *.  "Old" style callbacks
     are the same except they are initialised with a call to
     BN_GENCB_set_old and callback is of type void
     (*callback)(int, int, void *).

     A callback is invoked through a call to BN_GENCB_call. This
     will check the type of the callback and will invoke
     callback(a, b, gencb) for new style callbacks or callback(a,
     b, cb_arg) for old style.

     BN_generate_prime (deprecated) works in the same way as
     BN_generate_prime_ex but expects an old style callback
     function directly in the callback parameter, and an argument
     to pass to it in the cb_arg. 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.

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^nchecks, and -1 on error.

     BN_generate_prime() returns the prime number on success,
     NULL otherwise.

     Callback functions should return 1 on success or 0 on error.

     The error codes can be obtained by ERR_get_error(3).

SEE ALSO

     bn(3), ERR_get_error(3), rand(3)

HISTORY

     The cb_arg arguments to BN_generate_prime() and to
     BN_is_prime() were added in SSLeay 0.9.0. The ret argument
     to BN_generate_prime() was added in SSLeay 0.9.1.
     BN_is_prime_fasttest() was added in OpenSSL 0.9.5.

1.0.2t               Last change: 2019-09-10                    3

See also BN_GENCB_call(3)
See also BN_GENCB_set(3)
See also BN_GENCB_set_old(3)
See also BN_generate_prime_ex(3)
See also BN_is_prime(3)
See also BN_is_prime_ex(3)
See also BN_is_prime_fasttest(3)
See also BN_is_prime_fasttest_ex(3)