Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic
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";
}
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.
- 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.
- 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 hexadecimal representation.
- 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.
- 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
- zero
-
my $bn = Crypt::OpenSSL::Bignum->zero;
Returns a new Crypt::OpenSSL::Bignum object representing 0 (same as
new)
- one
-
my $bn = Crypt::OpenSSL::Bignum->one;
Returns a new Crypt::OpenSSL::Bignum object representing 1
- 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.
- 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.
- 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.
- 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.
- to_decimal
-
my $decimal_string = $self->to_decimal;
Return a decimal string representation of this object.
- to_hex
-
my $hex_string = $self->to_hex;
Return a hexadecimal string representation of this object.
- to_bin
-
my $bin_buffer = $self->to_bin;
Return a packed binary string representation of this object. Note that sign
is ignored, so that to bin called on a Crypt::OpenSSL::Bignum object
representing a negative number returns the same value as it would called
on an object representing that number's absolute value.
- get_word
-
my $unsigned_int = $self->get_word;
Return 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 of this object represents 0.
- is_one
-
my $bool = $self->is_one;
Returns true of this object represents 1.
- is_odd
-
my $bool = $self->is_odd;
Returns true of this object represents an odd number.
- 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
This method 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 second argument is set to the
result and returned.
- 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
This method 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 second argument is
set to the result and returned.
- 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
This method 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 third
argument is set to the result and returned.
- div
-
my ($quotient, $remainder) = $self->div($bn_b, $ctx);
# or
$self->div($bn_b, $ctx, $quotient, $remainder);
This method returns a list consisting of 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, otherwise, the value of
third argument is set to the quotient. If a fourth argument is passed, the
value of the fourth argument is set to the remainder.
- mod
-
my $remainder = $self->mod($bn_b, $ctx);
# or
$self->mod($bn_b, $ctx, $remainder);
This method returns the remainder obtained by dividing this object by the
first argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
Crypt::OpenSSL::Bignum object is created for the return value. If a third
argument is passed, the value of third argument is set to the
remainder.
- sqr
-
my $new_bn_object = $self->sqr($ctx);
# new object is created $self is not modified
This method returns the square ("$self ** 2") of
Crypt::OpenSSL::Bignum object.
- exp
-
my $new_bn_object = $self->exp($bn_exp, $ctx);
# new object is created $self is not modified
This method returns the product of this object exponentiated by the first
argument (Crypt::OpenSSL::Bignum object), using the second argument, a
Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
- mod_exp
-
my $new_bn_object = $self->exp_mod($bn_exp, $bn_mod, $ctx);
# new object is created $self is not modified
This method returns the product of this object exponentiated by the first
argument (Crypt::OpenSSL::Bignum object), modulo the second argument (also
Crypt::OpenSSL::Bignum object), using the third argument, a
Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
- mod_mul
-
my $new_bn_object = $self->mod_mul($bn_b, $bn_mod, $ctx);
# new object is created $self is not modified
This method returns "($self * $bn_b) % $bn_mod", using the third
argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
- 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.
- 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.
- cmp
-
my $result = $self->cmp($bn_b);
#returns:
# -1 if self < bn_b
# 0 if self == bn_b
# 1 if self > bn_b
Comparison of values $self and $bn_b (Crypt::OpenSSL::Bignum objects).
- 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
(Crypt::OpenSSL::Bignum objects).
- equals
-
my $result = $self->equals($bn_b);
#returns:
# 1 if self == bn_b
# 0 otherwise
- num_bits
-
my $bits = $self->num_bits;
Returns the number of significant bits in a word. If we take 0x00000432 as
an example, it returns 11, not 16, not 32. Basically, except for a zero,
it returns "floor(log2(w)) + 1".
- num_bytes
-
my $bytes = $self->num_bytes;
Returns the size of binary represenatation in bytes.
- rshift
-
my $new_bn_object = $self->rshift($n);
# new object is created $self is not modified
Shifts a right by $n (integer) bits and places the result into a newly
created Crypt::OpenSSL::Bignum object.
- lshift
-
my $new_bn_object = $self->lshift($n);
# new object is created $self is not modified
Shifts a left by $n (integer) bits and places the result into a newly
created Crypt::OpenSSL::Bignum object.
- 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.
- copy
-
my $new_bn_object = $self->copy;
Returns a copy of this object.
- 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. Note that 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.
Ian Robertson,
[email protected]
<
https://www.openssl.org/docs/crypto/bn.html>