NAME
BN_new, BN_init,
BN_clear, BN_free,
BN_clear_free —
allocate and free BIGNUMs
SYNOPSIS
#include
<openssl/bn.h>
BIGNUM *
BN_new(void);
void
BN_init(BIGNUM *);
void
BN_clear(BIGNUM *a);
void
BN_free(BIGNUM *a);
void
BN_clear_free(BIGNUM *a);
DESCRIPTION
The BN library performs arithmetic operations on integers of arbitrary size. It was written for use in public key cryptography, such as RSA and Diffie-Hellman.
It uses dynamic memory allocation for storing its data structures. That means that there is no limit on the size of the numbers manipulated by these functions, but return values must always be checked in case a memory allocation error has occurred.
The basic object in this library is a BIGNUM. It is used to hold a single large integer. This type should be considered opaque and fields should not be modified or accessed directly.
BN_new()
allocates and initializes a BIGNUM structure, in
particular setting the value to zero and the flags to
BN_FLG_MALLOCED. The security-relevant flag
BN_FLG_CONSTTIME is not set by default.
BN_init()
initializes an existing uninitialized BIGNUM. It is
deprecated and dangerous: see CAVEATS.
BN_clear()
is used to destroy sensitive data such as keys when they are no longer
needed. It erases the memory used by a and sets it to
the value 0.
BN_free()
frees the components of the BIGNUM and, if it was
created by BN_new(), also the structure itself.
BN_clear_free()
additionally overwrites the data before the memory is returned to the
system. If a is a NULL
pointer, no action occurs.
RETURN VALUES
BN_new() returns a pointer to the
BIGNUM. If the allocation fails, it returns
NULL and sets an error code that can be obtained by
ERR_get_error(3).
SEE ALSO
BN_add(3), BN_add_word(3), BN_BLINDING_new(3), BN_bn2bin(3), BN_cmp(3), BN_copy(3), BN_CTX_new(3), BN_CTX_start(3), BN_generate_prime(3), BN_get0_nist_prime_521(3), BN_mod_inverse(3), BN_mod_mul_montgomery(3), BN_mod_mul_reciprocal(3), BN_num_bytes(3), BN_rand(3), BN_set_bit(3), BN_set_flags(3), BN_set_negative(3), BN_swap(3), BN_zero(3)
HISTORY
BN_new(),
BN_clear(), BN_free(), and
BN_clear_free() first appeared in SSLeay 0.5.1 and
have been available since OpenBSD 2.4.
BN_init() first appeared in SSLeay 0.9.1
and has been available since OpenBSD 2.6.
CAVEATS
BN_init() must not be called on a
BIGNUM that was used and contains an actual number, or
the memory used for storing the number is leaked immediately. Besides, it
must not be called on a number allocated with
BN_new(), or the BIGNUM
structure itself will likely be leaked later on. It can only be used on
static BIGNUM structures, on
BIGNUM structures on the stack, or on
BIGNUM structures
malloc(3)'ed manually, but all of these options are discouraged
because they will no longer work once the BIGNUM data
type is made opaque.