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

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

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 at least 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:

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

For "new" style callbacks a
`BN_GENCB` structure should be initialised with a call
to the macro
`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 the macro
`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`

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

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

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

## SEE ALSO

## 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.