Bignum(3)

🎀 NAME 🎀

Bignum(3) — this is the User Contributed Perl Documentation page for Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic. That's the whole vibe: big numbers, OpenSSL energy, Perl access. 💅

✨ SYNOPSIS ✨

okay so here's the little demo, bestie — copy-paste it exact:

use Crypt::OpenSSL::Bignum;

my $bn = Crypt::OpenSSL::Bignum->new_from_decimal( "1000" );
# or
my $bn = Crypt::OpenSSL::Bignum->new_from_word( 1000 );
# or
my $bn = Crypt::OpenSSL::Bignum->new_from_hex("3e8"); # no leading 0x
# or
my $bn = Crypt::OpenSSL::Bignum->new_from_bin(pack( "C*", 3, 232 ))

use Crypt::OpenSSL::Bignum::CTX;

sub print_factorial
{
  my( $n ) = @_;
  my $fac = Crypt::OpenSSL::Bignum->one();
  my $ctx = Crypt::OpenSSL::Bignum::CTX->new();
  foreach my $i (1 .. $n)
  {
    $fac->mul( Crypt::OpenSSL::Bignum->new_from_word( $i ), $ctx, $fac );
  }
  print "$n factorial is ", $fac->to_decimal(), "\n";
}

💖 DESCRIPTION 💖

Crypt::OpenSSL::Bignum provides access to OpenSSL multiprecision integer arithmetic libraries. Presently, many though not all of the arithmetic operations that OpenSSL provides are exposed to perl. In addition, this module can be used to provide access to bignum values produced by other OpenSSL modules, such as key parameters from Crypt::OpenSSL::RSA. 🦋

⚠️ NOTE: Many of the methods in this package can croak, so use eval, or Error.pm's try/catch mechanism to capture errors. no cap, wrap your calls.

---

🧚 Constructors 🧚

🌸 new_from_decimal 🌸

my $bn = Crypt::OpenSSL::Bignum->new_from_decimal($decimal_string);

Create a new Crypt::OpenSSL::Bignum object whose value is specified by the given decimal representation. Slay, decimal-style. 💖

🌺 new_from_hex 🌺

my $bn = Crypt::OpenSSL::Bignum->new_from_hex($hex_string); #no leading '0x'

Create a new Crypt::OpenSSL::Bignum object whose value is specified by the given hexidecimal representation. And yes, that's the exact spelling from the page — I'm not fixing it, I'm just reporting it. 💅

🦋 new_from_word 🦋

my $bn = Crypt::OpenSSL::Bignum->new_from_word($unsigned_integer);

Create a new Crypt::OpenSSL::Bignum object whose value will be the word given. Note that numbers represented by objects created using this method are necessarily between 0 and 2^32 - 1. tiny word energy, but valid. ✨

🎀 new_from_bin 🎀

my $bn = Crypt::OpenSSL::Bignum->new_from_bin($bin_buffer);

Create a new Crypt::OpenSSL::Bignum object whose value is specified by the given packed binary string (created by to_bin). Note that objects created using this method are necessarily nonnegative. 🌈

💜 new 💜

my $bn = Crypt::OpenSSL::Bignum->new;

Returns a new Crypt::OpenSSL::Bignum object representing 0. iconic zero behavior. ✨

⭐ zero ⭐

my $bn = Crypt::OpenSSL::Bignum->zero;

Returns a new Crypt::OpenSSL::Bignum object representing 0 (same as new). double-confirmed zero, bestie. 💫

👑 one 👑

my $bn = Crypt::OpenSSL::Bignum->one;

Returns a new Crypt::OpenSSL::Bignum object representing 1. main character number, honestly. 💅

🎲 rand 🎲

my $bn = Crypt::OpenSSL::Bignum->rand($bits, $top, $bottom)
# $bits, $top, $bottom are integers

generates a cryptographically strong pseudo-random number of bits bits in length and stores it in rnd. If top is -1, the most significant bit of the random number can be zero. If top is 0, it is set to 1, and if top is 1, the two most significant bits of the number will be set to 1, so that the product of two such random numbers will always have 2*bits length. If bottom is true, the number will be odd. randomness ate. 🔥

🍓 pseudo_rand 🍓

my $bn = Crypt::OpenSSL::Bignum->pseudo_rand($bits, $top, $bottom)
# $bits, $top, $bottom are integers

does the same, but pseudo-random numbers generated by this function are not necessarily unpredictable. They can be used for non-cryptographic purposes and for certain purposes in cryptographic protocols, but usually not for key generation etc. so like, cute for vibes, not for secrets. 🙈

🧚 rand_range 🧚

my $bn = Crypt::OpenSSL::Bignum->rand_range($bn_range)

generates a cryptographically strong pseudo-random number rnd in the range 0 <lt>= rnd < range. BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(), and hence numbers generated by it are not necessarily unpredictable. range check: passed, but read the caveat, bestie. 💀

🌟 bless_pointer 🌟

my $bn = Crypt::OpenSSL::Bignum->bless_pointer($BIGNUM_ptr)

Given a pointer to a OpenSSL BIGNUM object in memory, construct and return Crypt::OpenSSL::Bignum object around this. Note that the underlying BIGNUM object will be destroyed (via BN_clear_free(3ssl)) when the returned Crypt::OpenSSL::Bignum object is no longer referenced, so the pointer passed to this method should only be referenced via the returned perl object after calling bless_pointer. 🫶

This method is intended only for use by XSUB writers writing code that interfaces with OpenSSL library methods, and who wish to be able to return a BIGNUM structure to perl as a Crypt::OpenSSL::Bignum object. iykyk. 💜

✨ Instance Methods ✨

okay so now we're in the method era, bestie — this is where the Crypt::OpenSSL::Bignum object actually does stuff. every method below is on $self, and all the code is copied exactly because we do not play with literals 💅

to_decimal

my $decimal_string = $self->to_decimal;

returns a decimal string representation of this object. cute, readable, base-10 slay 🎀

to_hex

my $hex_string = $self->to_hex;

returns a hexadecimal string representation of this object ✨

to_bin

my $bin_buffer = $self->to_bin;

returns a packed binary string representation of this object.

⚠️ heads up bestie: sign is ignored here. so to_bin called on a Crypt::OpenSSL::Bignum object representing a negative number returns the same value as it would if called on an object representing that number's absolute value 💀

get_word

my $unsigned_int = $self->get_word;

returns a scalar integer representation of this object, if it can be represented as an unsigned long.

is_zero

my $bool = $self->is_zero;

returns true if this object represents 0. zero behavior check, iconic 🫶

is_one

my $bool = $self->is_one;

returns true if this object represents 1. the main character number, honestly 👑

is_odd

my $bool = $self->is_odd;

returns true if this object represents an odd number. odd numbers ate, no cap 🌈

add

my $new_bn_object = $self->add($bn_b); # $new_bn_object = $self + $bn_b
# or
$self->add($bn_b, $result_bn);         # $result_bn = $self + $bn_b

returns the sum of this object and the first argument. if only one argument is passed, a new Crypt::OpenSSL::Bignum object is created for the return value; otherwise, the value of the second argument is set to the result and returned. math but make it adorable 💖

sub

my $new_bn_object = $self->sub($bn_b); # $new_bn_object = $self - $bn_b
# or
$self->sub($bn_b, $result_bn);         # $result_bn = $self - $bn_b

returns the difference of this object and the first argument. if only one argument is passed, a new Crypt::OpenSSL::Bignum object is created for the return value; otherwise, the value of the second argument is set to the result and returned. subtraction with main character energy 😌

mul

my $new_bn_object = $self->mul($bn_b, $ctx); # $new_bn_object = $self * $bn_b
# or
$self->mul($bn_b, $ctx, $result_bn);         # $result_bn = $self * $bn_b

returns the product of this object and the first argument, using the second argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. if only two arguments are passed, a new Crypt::OpenSSL::Bignum object is created for the return value; otherwise, the value of the third argument is set to the result and returned. multiply era 🔥

div

my ($quotient, $remainder) = $self->div($bn_b, $ctx);
# or
$self->div($bn_b, $ctx, $quotient, $remainder);

returns a list consisting of the quotient and the remainder obtained by dividing this object by the first argument, using the second argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad.

if only two arguments are passed, new Crypt::OpenSSL::Bignum objects are created for both return values. if a third argument is passed, the value of the third argument is set to the quotient. if a fourth argument is passed, the value of the fourth argument is set to the remainder. division but it brought a friend 🦋

mod

my $remainder = $self->mod($bn_b, $ctx);
# or
$self->mod($bn_b, $ctx, $remainder);

returns the remainder obtained by dividing this object by the first argument, with a Crypt::OpenSSL::Bignum::CTX object as a scratchpad.

a Crypt::OpenSSL::Bignum object is created for the return value. if a third argument is passed, the value of the third argument is set to the remainder. remainder behavior, cute and slightly mysterious 🌸

sqr

my $new_bn_object = $self->sqr($ctx);
# new object is created $self is not modified

returns the square ("$self ** 2") of the Crypt::OpenSSL::Bignum object. new object is created, $self is not modified. squaring up, literally 💅

exp

my $new_bn_object = $self->exp($bn_exp, $ctx);
# new object is created $self is not modified

returns the product of this object exponentiated by the first argument (a Crypt::OpenSSL::Bignum object), using the second argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. new object is created, $self is not modified. exponentiation said make it dramatic ✨

mod_exp

my $new_bn_object = $self->exp_mod($bn_exp, $bn_mod, $ctx);
# new object is created $self is not modified

returns the product of this object exponentiated by the first argument (a Crypt::OpenSSL::Bignum object), modulo the second argument (also a Crypt::OpenSSL::Bignum object), using the third argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. new object is created, $self is not modified. yes the method heading is mod_exp and the call is exp_mod; we keep the code exactly, bestie 🧚

mod_mul

my $new_bn_object = $self->mod_mul($bn_b, $bn_mod, $ctx);
# new object is created $self is not modified

returns ($self * $bn_b) % $bn_mod, using the third argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. new object is created, $self is not modified. modular multiplication with a little garnish 🍓

mod_inverse

my $new_bn_object = $self->mod_inverse($bn_n, $ctx);
# new object is created $self is not modified

computes the inverse of $self modulo $bn_n and returns the result in a new Crypt::OpenSSL::Bignum object, using the second argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. new object is created, $self is not modified. inverse behavior, lowkey iconic 💜

gcd

my $new_bn_object = $self->gcd($bn_b, $ctx);
# new object is created $self is not modified

computes the greatest common divisor of $self and $bn_b and returns the result in a new Crypt::OpenSSL::Bignum object, using the second argument — a Crypt::OpenSSL::Bignum::CTX object — as a scratchpad. new object is created, $self is not modified. greatest common divisor, greatest common slay 🌟

cmp

my $result = $self->cmp($bn_b);
#returns:
# -1 if self <  bn_b
#  0 if self == bn_b
#  1 if self >  bn_b

compares the values $self and $bn_b (both Crypt::OpenSSL::Bignum objects). vibe check returns -1, 0, or 1 as above 👀

ucmp

my $result = $self->ucmp($bn_b);
#returns:
# -1 if |self| <  |bn_b|
#  0 if |self| == |bn_b|
#  1 if |self| >  |bn_b|

comparison using the absolute values of $self and $bn_b (both Crypt::OpenSSL::Bignum objects). absolute-value comparison, no negative energy allowed 💖

equals

my $result = $self->equals($bn_b);
#returns:
# 1 if self == bn_b
# 0 otherwise

returns 1 if self == bn_b, and 0 otherwise. direct equality, no crumbs 🎀

num_bits

my $bits = $self->num_bits;

returns the number of significant bits in a word. take 0x00000432 as an example: it returns 11, not 16, not 32. basically, except for a zero, it returns floor(log2(w)) + 1. bit math said be precise 📏

num_bytes

my $bytes = $self->num_bytes;

returns the size of the binary representation in bytes. byte count, periodt 🦋

rshift

my $new_bn_object = $self->rshift($n);
# new object is created $self is not modified

shifts $self right by $n (integer) bits and places the result into a newly created Crypt::OpenSSL::Bignum object. new object is created, $self is not modified. right shift, right on 🌸

lshift

my $new_bn_object = $self->lshift($n);
# new object is created $self is not modified

shifts $self left by $n (integer) bits and places the result into a newly created Crypt::OpenSSL::Bignum object. new object is created, $self is not modified. left shift said we're going places ✨

swap

my $bn_a = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890001");
my $bn_b = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890002");

$bn_a->swap($bn_b);
# or
$bn_b->swap($bn_a);

exchanges the values of two Crypt::OpenSSL::Bignum objects. swap era, we love a mutual exchange 🤝

copy

my $new_bn_object = $self->copy;

returns a copy of this object. clone behavior, but make it cute 🫶

pointer_copy

my $cloned_BIGNUM_ptr = $self->pointer_copy($BIGNUM_ptr);

this method is intended only for use by XSUB writers wanting to have access to the underlying BIGNUM structure referenced by a Crypt::OpenSSL::Bignum perl object, so that they can pass them to other routines in the OpenSSL library.

it returns a perl scalar whose IV can be cast to a BIGNUM* value. this can then be passed to an XSUB which can work with the BIGNUM directly.

⚠️ important bestie: the BIGNUM object pointed to will be a copy of the BIGNUM object wrapped by the instance. it is thus the responsibility of the client to free space allocated by this BIGNUM object if and when it is done with it. see also bless_pointer. this is advanced XSUB territory, not casual vibes 💀

---

🌈 AUTHOR 🌈

Ian Robertson, iroberts@cpan.org — shoutout to Ian, author icon 👑

🦋 SEE ALSO 🦋

<https://www.openssl.org/docs/crypto/bn.html> — the OpenSSL bn docs are right there, iykyk 📚

---

okay bye bestie, this was Bignum(3) from perl v5.42.2, dated 2025-06-30 — mwah, go forth and bignum responsibly 💋💖