# Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic - perldoc - [phpMan]

## NAME
    [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) - OpenSSL's multiprecision integer arithmetic

## SYNOPSIS
      use [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown);

      my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_decimal( "1000" );
      # or
      my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_word( 1000 );
      # or
      my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_hex("3e8"); # no leading 0x
      # or
      my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_bin(pack( "C*", 3, 232 ))

      use [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown);

      sub print_factorial
      {
        my( $n ) = @_;
        my $fac = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->one();
        my $ctx = [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown)->new();
        foreach my $i (1 .. $n)
        {
          $fac->mul( [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_word( $i ), $ctx, $fac );
        }
        print "$n factorial is ", $fac->to_decimal(), "\n";
      }

## DESCRIPTION
    [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ARSA/markdown).

    *NOTE*: Many of the methods in this package can croak, so use eval, or Error.pm's try/catch
    mechanism to capture errors.

## Constructors
    new_from_decimal
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_decimal($decimal_string);

        Create a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object whose value is specified by the given decimal
        representation.

    new_from_hex
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_hex($hex_string); #no leading '0x'

        Create a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object whose value is specified by the given hexadecimal
        representation.

    new_from_word
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_word($unsigned_integer);

        Create a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_bin($bin_buffer);

        Create a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new;

        Returns a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object representing 0

    zero
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->zero;

        Returns a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object representing 0 (same as new)

    one
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->one;

        Returns a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object representing 1

    rand
         my $bn = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->bless_pointer($BIGNUM_ptr)

        Given a pointer to a OpenSSL BIGNUM object in memory, construct and return
        [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object around this. Note that the underlying BIGNUM object will be
        destroyed (via [BN_clear_free(3ssl)](https://www.chedong.com/phpMan.php/man/BNclearfree/3ssl/markdown)) when the returned [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object.

## Instance Methods
    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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown) object, as a scratchpad. If only two arguments are
        passed, a new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown)
        object, as a scratchpad. If only two arguments are passed, new [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)
        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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown) object, as a scratchpad. [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object), using the second argument, a [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown)
        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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object), modulo the second argument (also [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)
        object), using the third argument, a [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object, using the second argument, a [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown)
        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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object, using the second argument, a [Crypt::OpenSSL::Bignum::CTX](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum%3A%3ACTX/markdown)
        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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) object.

    swap
         my $bn_a = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_decimal("1234567890001");
         my $bn_b = [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown)->new_from_decimal("1234567890002");

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

        Exchanges the values of two [Crypt::OpenSSL::Bignum](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AOpenSSL%3A%3ABignum/markdown) 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.

## AUTHOR
    Ian Robertson, <iroberts@cpan.org>

## SEE ALSO
    <<https://www.openssl.org/docs/crypto/bn.html>>