NAME

       Crypt::GCrypt::MPI - Perl interface to multi-precision integers from the GNU Cryptographic library

SYNOPSIS

         use Crypt::GCrypt::MPI;

         my $mpi = Crypt::GCrypt::MPI->new();

ABSTRACT

       Crypt::GCrypt::MPI provides an object interface to multi-precision integers from the C libgcrypt library.

BASIC OPERATIONS

   new()
       Create a new multi-precision integer.

         my $mpi = Crypt::GCrypt::MPI::new(
           secure => 1,
           value => 20,
         );

       No parameters are required.  If only one parameter is given, it is treated as the "value" parameter.
       Available parameters:

       value
           The  initial value of the MPI.  This can be an integer, a string, or another Crypt::GCrypt::MPI.  (It
           would also be nice to be able to initialize it with a Math::Int).

       secure
           If this parameter evaluates to non-zero, initialize the MPI using secure memory, if possible.

       format
           If the value is a string, the format parameter suggests how to convert the  string.   See  CONVERSION
           FORMATS for the available formats.  Defaults to Crypt::GCrypt::MPI::FMT_STD.

   set()
       Copies the value of the other Crypt::GCrypt::MPI object.

         $mpi->set($othermpi);

   swap()
       Exchanges the value with the value of another Crypt::GCrpyt::MPI object:

         $mpi->swap($othermpi);

   is_secure()
       Returns true if the Crypt::GCrypt::MPI uses secure memory, where possible.

   cmp($other)
       Compares  this object against another Crypt::GCrypt::MPI object, returning 0 if the two values are equal,
       positive if this value is greater, negative if $other is greater.

   mutually_prime($other)
       Compares this object against another Crypt::GCrypt::MPI object, returning true only  if  the  two  values
       share no factors in common other than 1.

   copy()
       Returns a new Crypt::GCrypt::MPI object, with the contents identical to this one.  This is different from
       using the assignment operator (=), which just makes two references to the same object.  For example:

        $b = new Crypt::GCrypt::MPI(15);
        $a = $b;
        $b->add(1); # $a points to the same object,
                    # so both $a and $b contain 16.

        $a = $b->copy(); # $a and $b are both 16, but
                         # different objects; no risk of
                         # double-free.
        $b->add(1); # $a == 16, $b == 17

       If   $b   is   a   Crypt::GCrypt::MPI   object,   then   "$a   =  $b->copy();"  is  identical  to  "$a  =
       Crypt::GCrypt::MPI->new($b);"

CALCULATIONS

       All calculation operations modify the object they are called on, and return the same object, so  you  can
       chain them like this:

        $g->addm($a, $m)->mulm($b, $m)->gcd($x);

       If you don't want an operation to affect the initial object, use the copy() operator:

        $h = $g->copy()->addm($a, $m)->mulm($b, $m)->gcd($x);

   add($other)
       Adds the value of $other to this MPI.

   addm($other, $modulus)
       Adds the value of $other to this MPI, modulo the value of $modulus.

   sub($other)
       Subtracts the value of $other from this MPI.

   subm($other, $modulus)
       Subtracts the value of $other from this MPI, modulo the value of $modulus.

   mul($other)
       Multiply this MPI by the value of $other.

   mulm($other, $modulus)
       Multiply this MPI by the value of $other, modulo the value of $modulus.

   mul_2exp($e)
       Multiply this MPI by 2 raised to the power of $e (this is a leftward bitshift)

   div($other)
       Divide this MPI by the value of $other, leaving the integer quotient.  (This is integer division)

   mod($other)
       Divide this MPI by the value of $other, leaving the integer remainder.  (This is the modulus operation)

   powm($other, $modulus)
       Raise this MPI to the power of $other, modulo the value of $modulus.

   invm($modulus)
       Find the multiplicative inverse of this MPI, modulo $modulus.

   gcd($other)
       Find the greatest common divisor of this MPI and $other.

OUTPUT AND DEBUGGING

   dump()
       Send the MPI to the libgcrypt debugging stream.

   print($format)
       Return  a  string with the data of this MPI, in a given format.  See CONVERSION FORMATS for the available
       formats.

CONVERSION FORMATS

       The available printing and scanning formats are all in the Crypt::GCrypt::MPI  namespace,  and  have  the
       same meanings as in gcrypt.

   FMT_STD
       Two's complement representation.

   FMT_PGP
       Same  as  FMT_STD,  but  with  two-byte  length header, as used in OpenPGP.  (Only works for non-negative
       values)

   FMT_SSH
       Same as FMT_STD, but with four-byte length header, as used by OpenSSH.

   FMT_HEX
       Hexadecimal string in ASCII.

   FMT_USG
       Simple unsigned integer.

BUGS AND FEEDBACK

       Crypt::GCrypt::MPI does not currently auto-convert to and  from  Math::BigInt  objects,  even  though  it
       should.

       Other  than  that,  here  are  no  known  bugs.  You  are  very  welcome  to write mail to the maintainer
       (aar@cpan.org) with your contributions, comments, suggestions, bug reports or complaints.

AUTHORS AND CONTRIBUTORS

       Daniel Kahn Gillmor <dkg@fifthhorseman.net>

       Alessandro Ranellucci <aar@cpan.org>

COPYRIGHT AND LICENSE

       Copyright © Daniel Kahn Gillmor.  Crypt::GCrypt::MPI is free software, you  may  redistribute  it  and/or
       modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

       This  module was initially inspired by the GCrypt.pm bindings made by Robert Bihlmeyer in 2002. Thanks to
       users who give feedback and submit patches (see Changelog).

DISCLAIMER

       This software is provided by the copyright holders and contributors ``as is'' and any express or  implied
       warranties,  including,  but  not limited to, the implied warranties of merchantability and fitness for a
       particular purpose are disclaimed. In no event shall the  regents  or  contributors  be  liable  for  any
       direct,  indirect,  incidental,  special, exemplary, or consequential damages (including, but not limited
       to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption)
       however caused and on any theory of liability, whether in contract, strict liability, or tort  (including
       negligence  or  otherwise)  arising  in  any  way out of the use of this software, even if advised of the
       possibility of such damage.

perl v5.38.2                                       2024-04-01                            Crypt::GCrypt::MPI(3pm)