.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bignum 3pm"
.TH Bignum 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::OpenSSL::Bignum \- OpenSSL's multiprecision integer arithmetic
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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(), "\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
\&\fI\s-1NOTE\s0\fR: Many of the methods in this package can croak, so use eval, or
Error.pm's try/catch mechanism to capture errors.
.SH "Constructors"
.IX Header "Constructors"
.IP "new_from_decimal" 4
.IX Item "new_from_decimal"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->new_from_decimal($decimal_string);
.Ve
.Sp
Create a new Crypt::OpenSSL::Bignum object whose value is specified by
the given decimal representation.
.IP "new_from_hex" 4
.IX Item "new_from_hex"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->new_from_hex($hex_string); #no leading \*(Aq0x\*(Aq
.Ve
.Sp
Create a new Crypt::OpenSSL::Bignum object whose value is specified by
the given hexadecimal representation.
.IP "new_from_word" 4
.IX Item "new_from_word"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->new_from_word($unsigned_integer);
.Ve
.Sp
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.
.IP "new_from_bin" 4
.IX Item "new_from_bin"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->new_from_bin($bin_buffer);
.Ve
.Sp
Create a new Crypt::OpenSSL::Bignum object whose value is specified by
the given packed binary string (created by \*(L"to_bin\*(R"). Note that objects
created using this method are necessarily nonnegative.
.IP "new" 4
.IX Item "new"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->new;
.Ve
.Sp
Returns a new Crypt::OpenSSL::Bignum object representing 0
.IP "zero" 4
.IX Item "zero"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->zero;
.Ve
.Sp
Returns a new Crypt::OpenSSL::Bignum object representing 0 (same as new)
.IP "one" 4
.IX Item "one"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->one;
.Ve
.Sp
Returns a new Crypt::OpenSSL::Bignum object representing 1
.IP "rand" 4
.IX Item "rand"
.Vb 2
\& my $bn = Crypt::OpenSSL::Bignum\->rand($bits, $top, $bottom)
\& # $bits, $top, $bottom are integers
.Ve
.Sp
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.
.IP "pseudo_rand" 4
.IX Item "pseudo_rand"
.Vb 2
\& my $bn = Crypt::OpenSSL::Bignum\->pseudo_rand($bits, $top, $bottom)
\& # $bits, $top, $bottom are integers
.Ve
.Sp
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.
.IP "rand_range" 4
.IX Item "rand_range"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->rand_range($bn_range)
.Ve
.Sp
generates a cryptographically strong pseudo-random number rnd in the range 0
<lt>= rnd < range. \fBBN_pseudo_rand_range()\fR does the same, but is based on
\&\fBBN_pseudo_rand()\fR, and hence numbers generated by it are not necessarily
unpredictable.
.IP "bless_pointer" 4
.IX Item "bless_pointer"
.Vb 1
\& my $bn = Crypt::OpenSSL::Bignum\->bless_pointer($BIGNUM_ptr)
.Ve
.Sp
Given a pointer to a OpenSSL \s-1BIGNUM\s0 object in memory, construct and
return Crypt::OpenSSL::Bignum object around this.  Note that the
underlying \s-1BIGNUM\s0 object will be destroyed (via \fBBN_clear_free\fR\|(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.
.Sp
This method is intended only for use by \s-1XSUB\s0 writers writing code that
interfaces with OpenSSL library methods, and who wish to be able to
return a \s-1BIGNUM\s0 structure to perl as a Crypt::OpenSSL::Bignum object.
.SH "Instance Methods"
.IX Header "Instance Methods"
.IP "to_decimal" 4
.IX Item "to_decimal"
.Vb 1
\& my $decimal_string = $self\->to_decimal;
.Ve
.Sp
Return a decimal string representation of this object.
.IP "to_hex" 4
.IX Item "to_hex"
.Vb 1
\& my $hex_string = $self\->to_hex;
.Ve
.Sp
Return a hexadecimal string representation of this object.
.IP "to_bin" 4
.IX Item "to_bin"
.Vb 1
\& my $bin_buffer = $self\->to_bin;
.Ve
.Sp
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.
.IP "get_word" 4
.IX Item "get_word"
.Vb 1
\& my $unsigned_int = $self\->get_word;
.Ve
.Sp
Return a scalar integer representation of this object, if it can be
represented as an unsigned long.
.IP "is_zero" 4
.IX Item "is_zero"
.Vb 1
\& my $bool = $self\->is_zero;
.Ve
.Sp
Returns true of this object represents 0.
.IP "is_one" 4
.IX Item "is_one"
.Vb 1
\& my $bool = $self\->is_one;
.Ve
.Sp
Returns true of this object represents 1.
.IP "is_odd" 4
.IX Item "is_odd"
.Vb 1
\& my $bool = $self\->is_odd;
.Ve
.Sp
Returns true of this object represents an odd number.
.IP "add" 4
.IX Item "add"
.Vb 3
\& 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
.Ve
.Sp
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.
.IP "sub" 4
.IX Item "sub"
.Vb 3
\& 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
.Ve
.Sp
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.
.IP "mul" 4
.IX Item "mul"
.Vb 3
\& 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
.Ve
.Sp
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.
.IP "div" 4
.IX Item "div"
.Vb 3
\& my ($quotient, $remainder) = $self\->div($bn_b, $ctx);
\& # or
\& $self\->div($bn_b, $ctx, $quotient, $remainder);
.Ve
.Sp
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.
.IP "mod" 4
.IX Item "mod"
.Vb 3
\& my $remainder = $self\->mod($bn_b, $ctx);
\& # or
\& $self\->mod($bn_b, $ctx, $remainder);
.Ve
.Sp
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.
.IP "sqr" 4
.IX Item "sqr"
.Vb 2
\& my $new_bn_object = $self\->sqr($ctx);
\& # new object is created $self is not modified
.Ve
.Sp
This method returns the square (\f(CW\*(C`$self ** 2\*(C'\fR) of Crypt::OpenSSL::Bignum object.
.IP "exp" 4
.IX Item "exp"
.Vb 2
\& my $new_bn_object = $self\->exp($bn_exp, $ctx);
\& # new object is created $self is not modified
.Ve
.Sp
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.
.IP "mod_exp" 4
.IX Item "mod_exp"
.Vb 2
\& my $new_bn_object = $self\->exp_mod($bn_exp, $bn_mod, $ctx);
\& # new object is created $self is not modified
.Ve
.Sp
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.
.IP "mod_mul" 4
.IX Item "mod_mul"
.Vb 2
\& my $new_bn_object = $self\->mod_mul($bn_b, $bn_mod, $ctx);
\& # new object is created $self is not modified
.Ve
.Sp
This method returns \f(CW\*(C`($self * $bn_b) % $bn_mod\*(C'\fR, using the third argument,
a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
.IP "mod_inverse" 4
.IX Item "mod_inverse"
.Vb 2
\& my $new_bn_object = $self\->mod_inverse($bn_n, $ctx);
\& # new object is created $self is not modified
.Ve
.Sp
Computes the inverse of \f(CW$self\fR modulo \f(CW$bn_n\fR and returns the result in
a new Crypt::OpenSSL::Bignum object, using the second argument,
a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
.IP "gcd" 4
.IX Item "gcd"
.Vb 2
\& my $new_bn_object = $self\->gcd($bn_b, $ctx);
\& # new object is created $self is not modified
.Ve
.Sp
Computes the greatest common divisor of \f(CW$self\fR and \f(CW$bn_b\fR and returns the result in
a new Crypt::OpenSSL::Bignum object, using the second argument,
a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
.IP "cmp" 4
.IX Item "cmp"
.Vb 5
\& my $result = $self\->cmp($bn_b);
\& #returns:
\& # \-1 if self <  bn_b
\& #  0 if self == bn_b
\& #  1 if self >  bn_b
.Ve
.Sp
Comparison of values \f(CW$self\fR and \f(CW$bn_b\fR (Crypt::OpenSSL::Bignum objects).
.IP "ucmp" 4
.IX Item "ucmp"
.Vb 5
\& my $result = $self\->ucmp($bn_b);
\& #returns:
\& # \-1 if |self| <  |bn_b|
\& #  0 if |self| == |bn_b|
\& #  1 if |self| >  |bn_b|
.Ve
.Sp
Comparison using the absolute values of \f(CW$self\fR and \f(CW$bn_b\fR (Crypt::OpenSSL::Bignum objects).
.IP "equals" 4
.IX Item "equals"
.Vb 4
\& my $result = $self\->equals($bn_b);
\& #returns:
\& # 1 if self == bn_b
\& # 0 otherwise
.Ve
.IP "num_bits" 4
.IX Item "num_bits"
.Vb 1
\& my $bits = $self\->num_bits;
.Ve
.Sp
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 \f(CW\*(C`floor(log2(w)) + 1\*(C'\fR.
.IP "num_bytes" 4
.IX Item "num_bytes"
.Vb 1
\& my $bytes = $self\->num_bytes;
.Ve
.Sp
Returns the size of binary represenatation in bytes.
.IP "rshift" 4
.IX Item "rshift"
.Vb 2
\& my $new_bn_object = $self\->rshift($n);
\& # new object is created $self is not modified
.Ve
.Sp
Shifts a right by \f(CW$n\fR (integer) bits and places the result into a newly created Crypt::OpenSSL::Bignum object.
.IP "lshift" 4
.IX Item "lshift"
.Vb 2
\& my $new_bn_object = $self\->lshift($n);
\& # new object is created $self is not modified
.Ve
.Sp
Shifts a left by \f(CW$n\fR (integer) bits and places the result into a newly created Crypt::OpenSSL::Bignum object.
.IP "swap" 4
.IX Item "swap"
.Vb 2
\& 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);
.Ve
.Sp
Exchanges the values of two Crypt::OpenSSL::Bignum objects.
.IP "copy" 4
.IX Item "copy"
.Vb 1
\& my $new_bn_object = $self\->copy;
.Ve
.Sp
Returns a copy of this object.
.IP "pointer_copy" 4
.IX Item "pointer_copy"
.Vb 1
\& my $cloned_BIGNUM_ptr = $self\->pointer_copy($BIGNUM_ptr);
.Ve
.Sp
This method is intended only for use by \s-1XSUB\s0 writers wanting to have
access to the underlying \s-1BIGNUM\s0 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 \s-1IV\s0
can be cast to a BIGNUM* value.  This can then be passed to an \s-1XSUB\s0
which can work with the \s-1BIGNUM\s0 directly.  Note that the \s-1BIGNUM\s0 object
pointed to will be a copy of the \s-1BIGNUM\s0 object wrapped by the
instance; it is thus the responsibility of the client to free space
allocated by this \s-1BIGNUM\s0 object if and when it is done with it. See
also bless_pointer.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ian Robertson, iroberts@cpan.org
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<https://www.openssl.org/docs/crypto/bn.html>