BN_BN2BIN(3)

📦 version 4.1.0, in opensuse-leap 16.0

🎀 BN_BN2BIN(3) 🎀

okay bestie, welcome to the BN_BN2BIN(3) page from the Library Functions Manual 💅 this is the whole format conversions situation for BIGNUMs, and it is genuinely iconic. no cap, we're turning numbers into bytes and strings and back again — let's go ✨

🌸 NAME 🌸

BN_bn2bin, BN_bn2binpad, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_asc2bn, BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn — format conversions 🦋

✨ SYNOPSIS ✨

copy these signatures exactly, bestie, character for character — i don't make the rules 💅

#include <openssl/bn.h>

int
BN_bn2bin(const BIGNUM *a, unsigned char *to);

int
BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);

BIGNUM *
BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);

int
BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);

BIGNUM *
BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);

char *
BN_bn2hex(const BIGNUM *a);

char *
BN_bn2dec(const BIGNUM *a);

int
BN_hex2bn(BIGNUM **ap, const char *str);

int
BN_dec2bn(BIGNUM **ap, const char *str);

int
BN_asc2bn(BIGNUM **ap, const char *str);

int
BN_print(BIO *fp, const BIGNUM *a);

int
BN_print_fp(FILE *fp, const BIGNUM *a);

int
BN_bn2mpi(const BIGNUM *a, unsigned char *to);

BIGNUM *
BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);

🍓 DESCRIPTION 🍓

okay so here's the tea, function by function 🫶

  • BN_bn2bin() — converts the absolute value of a into big-endian form and stores it at to. to must point to BN_num_bytes(a) bytes of memory. not optional, bestie 💀
  • BN_bn2binpad() — also converts the absolute value of a into big-endian form and stores it at to. tolen indicates the length of the output buffer *to. The result is padded with zeros if necessary. If tolen is less than BN_num_bytes(a), an error is returned. rude but fair 🎀
  • BN_bin2bn() — converts the positive integer in big-endian form of length len at s into a BIGNUM and places it in ret. If ret is NULL, a new BIGNUM is created. fresh BIGNUM just dropped ✨
  • BN_bn2lebinpad() and BN_lebin2bn() — identical to BN_bn2binpad() and BN_bin2bn() except the buffer *to is in little-endian format. same energy, different byte order 🦋
  • BN_bn2hex() and BN_bn2dec() — return printable strings containing the hexadecimal and decimal encoding of a respectively. For negative numbers, the string is prefaced with a leading minus sign. The string must be freed later using free(3). yes bestie, free it — that's the whole vibe 💅
  • BN_hex2bn() — interprets str as a hexadecimal number. The string may start with a minus sign (‘-’). Conversion stops at the first byte that is not a hexadecimal digit. The number is converted to a BIGNUM and stored in **ap. If *ap is NULL, a new BIGNUM is created. If ap is NULL, it only computes the number's length in hexadecimal digits, also counting the leading minus sign if there is one. A "negative zero" is converted to zero. BN_dec2bn() is the same using the decimal system. negative zero said not today 😭
  • BN_asc2bn() — infers the number base from an optional prefix. If str starts with 0x or 0X, it calls BN_hex2bn(), otherwise BN_dec2bn(). If the number is negative, the minus sign can be given before or after the prefix. prefix detective behavior 🔥
  • BN_print() and BN_print_fp() — write the hexadecimal encoding of a, with a leading minus sign for negative numbers, to the BIO or FILE fp. print it, hex it, slay it 💖
  • BN_bn2mpi() and BN_mpi2bn() — convert BIGNUMs from and to a format that consists of the number's length in bytes represented as a 4-byte big-endian number, and the number itself in big-endian format, where the most significant bit signals a negative number (the representation of numbers with the MSB set is prefixed with a NUL byte). okay this one is giving very structured 🌈
  • BN_bn2mpi() — stores the representation of a at to, where *to must be large enough to hold the result. The size can be determined by calling BN_bn2mpi(a, NULL). size check first, bestie ⭐
  • BN_mpi2bn() — converts the len bytes long representation at s to a BIGNUM and stores it at ret, or in a newly allocated BIGNUM if ret is NULL. new BIGNUM if you need one 🫶

💖 RETURN VALUES 💖

  • BN_bn2bin() — returns the length of the big-endian number placed at to. 📏
  • BN_bn2binpad() and BN_bn2lebinpad() — return the number of bytes written or -1 if the supplied buffer is too small. too small = no thanks 🙈
  • BN_bin2bn() and BN_lebin2bn() — return the BIGNUM, or NULL on error.
  • BN_bn2hex() and BN_bn2dec() — return a NUL-terminated string, or NULL on error. BN_hex2bn() and BN_dec2bn() return the number's length in hexadecimal or decimal digits, also counting the leading minus sign if there is one, or 0 on error, in which case no new BIGNUM is created. BN_asc2bn() returns 1 on success or 0 on error, in which case no new BIGNUM is created. error path said no new BIGNUM 💀
  • BN_print_fp() and BN_print() — return 1 on success, 0 on write errors. 📝
  • BN_bn2mpi() — returns the length of the representation. BN_mpi2bn() returns the BIGNUM, or NULL on error. 🎀
friendly reminder: The error codes can be obtained by ERR_get_error(3). go get the receipts, bestie 🔍

🦋 SEE ALSO 🦋

the whole friend group, honestly 🫶

🌈 HISTORY 🌈

  • BN_bn2bin(), BN_bin2bn(), and BN_print() first appeared in SSLeay 0.5.1. BN_print_fp() first appeared in SSLeay 0.6.0. BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi(), and BN_mpi2bn() first appeared in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4. vintage but still serving 💚
  • BN_asc2bin() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9. yep, that's exactly how it's written in the history section 😭
  • BN_bn2binpad(), BN_bn2lebinpad(), and BN_lebin2bn() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.0. newer era unlocked ✨

💖 okay that's the whole page! this cutie is from the Debian crew, dated July 9, 2023, and it's the BN_BN2BIN(3) page. mwah! 💋🫶

📦 where this page comes from