GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
BN_GENERATE_PRIME(3) FreeBSD 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_oldgenerate primes and test for primality

#include <openssl/bn.h>

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

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

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

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

BN_GENCB *
BN_GENCB_new(void);

void
BN_GENCB_free(BN_GENCB *cb);

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

void *
BN_GENCB_get_arg(BN_GENCB *cb);

Deprecated:


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

() and BN_is_prime_fasttest_ex() test whether the number a is prime. In LibreSSL, both functions behave identically and use the Baillie-Pomerance-Selfridge-Wagstaff algorithm combined with checks Miller-Rabin rounds. The do_trial_division argument is ignored.

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.

In order to reduce the likelihood of a composite number passing the primality tests () and BN_is_prime_ex(), a number of rounds of the probabilistic Miller-Rabin test is performed. If checks is positive, it is used as the number of rounds; if it is zero or the special value BN_prime_checks, a suitable number of rounds is calculated from the bit length of a.

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 modulus is not NULL, a prime is generated that fulfills the condition ret % modulus = remainder. If the remainder argument is NULL, 1 is used as the desired remainder.
  • If the safe argument is non-zero, a safe prime is generated, that is, (ret - 1)/2 is also prime.

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

  • (cb, 0, serial_number) is called after generating a potential prime number.
  • The state_code of 1 is reserved for callbacks during primality testing, but LibreSSL performs no such callbacks.
  • When safe is non-zero and a safe prime has been found, BN_GENCB_call(cb, 2, serial_number) 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.

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.

BN_is_prime_ex() and BN_is_prime_fasttest_ex() 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().

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

BN_new(3), DH_generate_parameters(3), DSA_generate_parameters_ex(3), RSA_generate_key(3)

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 29, 2023 FreeBSD 14.3-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.