BN_NEW(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 BN_NEW — the one where we birth and yeet BIGNUMs

okay so first things first: this is BN_NEW(3), bestie — section 3, Library Functions Manual, the whole BN_new / BN_clear / BN_free / BN_clear_free girl squad. Buckle up 🎀

✨ NAME ✨

BN_new, BN_clear, BN_free, BN_clear_free — the four functions that allocate and free BIGNUMs. that's it, that's the job. 💖

🌸 SYNOPSIS 🌸

like, the library is “libcrypto”, and you gotta invite the header in first:

#include <openssl/bn.h>

then the actual cast, in order:

BIGNUM *
BN_new(void);

void
BN_clear(BIGNUM *a);

void
BN_free(BIGNUM *a);

void
BN_clear_free(BIGNUM *a);

no cap, that's the whole synopsis. 🦋

💫 DESCRIPTION 💫

so the BN library does arithmetic on integers of arbitrary size — like, any size, the number can be as big as it wants, no body shaming here 🔥. it was written for public key cryptography, such as RSA and Diffie-Hellman. iconic origin story fr fr.

it uses dynamic memory allocation to store its data structures. and what that means is there is no limit on the size of the numbers these functions can manipulate — but ⚠️ return values must always be checked in case a memory allocation error has occurred. always. check them. don't be that girl.

the basic object in this library is a BIGNUM. it holds a single large integer. that's its whole personality and it's serving 💅

  • BN_new() — allocates and initializes a BIGNUM structure. in particular it sets the value to zero and the flags to BN_FLG_MALLOCED. and important: the security-relevant flag BN_FLG_CONSTTIME is not set by default. like ever. you have to go get that yourself, bestie 🙈
  • BN_clear() — the sensitive-data destroyer. 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. bye bye secrets, you will not be missed 💀
  • BN_free() — frees the components of the BIGNUM and, if it was created by BN_new(), also the structure itself. the full cleanout 👑
  • BN_clear_free() — same vibe, but it additionally overwrites the data before the memory is returned to the system. the extra-paranoid, extra-thorough version. she ate, honestly 🍓
🫶 oh and: if a is a NULL pointer, no action occurs. nobody crashes, nobody screams, it's fine. very demure.

⭐ RETURN VALUES ⭐

BN_new() returns a pointer to the BIGNUM. and if the allocation fails? it returns NULL and sets an error code that you can grab with ERR_get_error(3). so like, check it. 😭

🧚 SEE ALSO 🧚

the whole extended universe, mwah:

iykyk 🌈

👑 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. like, they've been doing this since before we were born. legends only 💜

and that's the page!! 💖✨🎀🦋🌸💅

cute little sign-off: this one's from the Debian build, dated June 8, 2025, chillin' in the BN_NEW(3) slot of the Library Functions Manual. luv u, go check your return values 🫶⭐

📦 where this page comes from