OpenBSD manual page server

Manual Page Search Parameters

BN_GENERATE_PRIME(3) Library Functions Manual BN_GENERATE_PRIME(3)

BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_generate_prime_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, BN_GENCB_set, BN_GENCB_get_arg, BN_GENCB_set_old, BN_generate_prime, BN_is_prime, BN_is_prime_fasttestgenerate primes and test for primality

#include <openssl/bn.h>

BN_is_prime_ex(const BIGNUM *a, int nchecks, BN_CTX *ctx, BN_GENCB *cb);

BN_is_prime_fasttest_ex(const BIGNUM *a, int nchecks, BN_CTX *ctx, int do_trial_division, BN_GENCB *cb);

BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *modulus, const BIGNUM *remainder, BN_GENCB *cb);

BN_GENCB_call(BN_GENCB *cb, int state_code, int serial_number);


BN_GENCB_free(BN_GENCB *cb);

BN_GENCB_set(BN_GENCB *cb, int (*cb_fp)(int, int, BN_GENCB *), void *cb_arg);

void *
BN_GENCB_get_arg(BN_GENCB *cb);


BN_GENCB_set_old(BN_GENCB *cb, void (*cb_fp)(int, int, void *), void *cb_arg);

BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *modulus, BIGNUM *remainder, void (*cb_fp)(int, int, void *), void *cb_arg);

BN_is_prime(const BIGNUM *a, int checks, void (*cb_fp)(int, int, void *), BN_CTX *ctx, void *cb_arg);

BN_is_prime_fasttest(const BIGNUM *a, int checks, void (*cb_fp)(int, int, void *), BN_CTX *ctx, void *cb_arg, int do_trial_division);

() and () test whether the number a is prime. In LibreSSL, both functions behave identically, use the Baillie-Pomerance-Selfridge-Wagstaff algorithm, and ignore the checks and do_trial_division arguments.

It is unknown whether any composite number exists that the Baillie-PSW algorithm misclassifies as a prime. Some suspect that there may be infinitely many such numbers, but not a single one is currently known. It is known that no such number exists below 2^64.

If NULL is passed for the ctx argument, these function allocate a BN_CTX object internally when they need one and free it before returning. Alternatively, to save the overhead of allocating and freeing that object for each call, the caller can pre-allocate a BN_CTX object and pass it in the ctx argument.

() generates a pseudo-random prime number of at least bit length bits and places it in ret. Primality of ret is tested internally using BN_is_prime_ex(). Consequently, for bits larger than 64, it is theoretically possible that this function might place a composite number into ret; the probability of such an event is unknown but very small.

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

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

In all cases, the serial_number is the number of candidates that have already been discarded for not being prime; that is, serial_number is 0 for the first candidate and then incremented whenever a new candidate is generated.

() calls the callback function held in cb and passes the state_code and the serial_number as arguments. If cb is NULL or does not contain a callback function, no action occurs.

() allocates a new BN_GENCB object.

() frees cb. If cb is NULL, no action occurs.

() initialises cb to use the callback function pointer cb_fp and the additional callback argument cb_arg.

The deprecated function () initialises cb to use the old-style callback function pointer cb_fp and the additional callback argument cb_arg.

() is a deprecated wrapper around BN_GENCB_set_old() and BN_generate_prime_ex(). In contrast to BN_generate_prime_ex(), if NULL is passed for the ret argument, a new BIGNUM object is allocated and returned.

Similarly, () and () are deprecated wrappers around BN_GENCB_set_old() and BN_is_prime_ex().

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 a very small error probability, or -1 on error.

BN_generate_prime_ex() returns 1 on success or 0 on error.

BN_GENCB_call() returns 1 on success, including when cb is NULL or does not contain a callback function, or 0 on error.

BN_GENCB_new() returns a pointer to the newly allocated BN_GENCB object or NULL if memory allocation fails.

The callback functions pointed to by the cb_fp arguments are supposed to return 1 on success or 0 on error.

BN_GENCB_get_arg() returns the cb_arg pointer that was previously stored in cb using BN_GENCB_set() or BN_GENCB_set_old().

BN_generate_prime() returns the prime number on success or NULL on failure.

In some cases, error codes can be obtained by ERR_get_error(3).

BN_new(3), DH_generate_parameters(3), DSA_generate_parameters(3), RSA_generate_key(3)

BN_generate_prime() and BN_is_prime() first appeared in SSLeay 0.5.1 and had their cb_arg argument added in SSLeay 0.9.0. These two functions have been available since OpenBSD 2.4.

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.

November 24, 2022 OpenBSD-7.3