BN_GENERATE_PRIME(3) | Library Functions Manual | BN_GENERATE_PRIME(3) |

`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

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

`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:

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

`BN_generate_prime_ex`

() generates a pseudo-random prime
number of at least bit length `NULL`

, it will be used
to store the number.
If `cb` is not `NULL`

,
it is used as follows:

`BN_GENCB_call`

(`cb`,`0`,`i`) is called after generating the i-th potential prime number.- While the number is being tested for primality,
`BN_GENCB_call`

(`cb`,`1`,`j`) is called as described below. - When a prime has been found,
`BN_GENCB_call`

(`cb`,`2`,`i`) is called. - The callers of
`BN_generate_prime_ex`

() may call`BN_GENCB_call`

() with other values as described in their respective manual pages; see SEE ALSO.

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 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^-80 for random input.

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` structures 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 `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.

It is possible to obtain 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
`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.

`BN_generate_prime_ex`

() returns 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.

`BN_GENCB_new`

() returns a pointer to a
`BN_GENCB` structure on success, or
`NULL`

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 ERR_get_error(3).

`BN_generate_prime`

() and
`BN_is_prime`

() first appeared in SSLeay 0.5.1 and had
their The `ret` argument to
`BN_generate_prime`

() was added in SSLeay 0.9.1 and
OpenBSD 2.6.

`BN_is_prime_fasttest`

() first appeared in
OpenSSL 0.9.5 and has been available since OpenBSD
2.7.

`BN_generate_prime_ex`

(),
`BN_is_prime_ex`

(),
`BN_is_prime_fasttest_ex`

(),
`BN_GENCB_call`

(),
`BN_GENCB_set_old`

(), and
`BN_GENCB_set`

() first appeared in OpenSSL 0.9.8 and
have been available since OpenBSD 4.5.

`BN_GENCB_new`

(),
`BN_GENCB_free`

(), and
`BN_GENCB_get_arg`

() first appeared in OpenSSL 1.1.0
and have been available since OpenBSD 6.3.

December 21, 2018 | OpenBSD-current |