.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "Crypt::GCrypt::MPI 3pm"
.TH Crypt::GCrypt::MPI 3pm "2018-11-02" "perl v5.28.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::GCrypt::MPI \- Perl interface to multi\-precision integers from the GNU Cryptographic library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Crypt::GCrypt::MPI;
\&
\&  my $mpi = Crypt::GCrypt::MPI\->new();
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Crypt::GCrypt::MPI provides an object interface to multi-precision
integers from the C libgcrypt library.
.SH "BASIC OPERATIONS"
.IX Header "BASIC OPERATIONS"
.SS "\fBnew()\fP"
.IX Subsection "new()"
Create a new multi-precision integer.
.PP
.Vb 4
\&  my $mpi = Crypt::GCrypt::MPI::new(
\&    secure => 1,
\&    value => 20,
\&  );
.Ve
.PP
No parameters are required.  If only one parameter is given, it is
treated as the \*(L"value\*(R" parameter.  Available parameters:
.IP "value" 4
.IX Item "value"
The initial value of the \s-1MPI.\s0  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).
.IP "secure" 4
.IX Item "secure"
If this parameter evaluates to non-zero, initialize the \s-1MPI\s0 using
secure memory, if possible.
.IP "format" 4
.IX Item "format"
If the value is a string, the format parameter suggests how to convert
the string.  See \s-1CONVERSION FORMATS\s0 for the available formats.
Defaults to Crypt::GCrypt::MPI::FMT_STD.
.SS "\fBset()\fP"
.IX Subsection "set()"
Copies the value of the other Crypt::GCrypt::MPI object.
.PP
.Vb 1
\&  $mpi\->set($othermpi);
.Ve
.SS "\fBswap()\fP"
.IX Subsection "swap()"
Exchanges the value with the value of another Crypt::GCrpyt::MPI
object:
.PP
.Vb 1
\&  $mpi\->swap($othermpi);
.Ve
.SS "\fBis_secure()\fP"
.IX Subsection "is_secure()"
Returns true if the Crypt::GCrypt::MPI uses secure memory, where
possible.
.SS "cmp($other)"
.IX Subsection "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 \f(CW$other\fR is greater.
.SS "mutually_prime($other)"
.IX Subsection "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.
.SS "\fBcopy()\fP"
.IX Subsection "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:
.PP
.Vb 4
\& $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
.Ve
.PP
If \f(CW$b\fR is a Crypt::GCrypt::MPI object, then \*(L"$a = \f(CW$b\fR\->\fBcopy()\fR;\*(R" is
identical to \*(L"$a = Crypt::GCrypt::MPI\->new($b);\*(R"
.SH "CALCULATIONS"
.IX Header "CALCULATIONS"
All calculation operations modify the object they are called on, and
return the same object, so you can chain them like this:
.PP
.Vb 1
\& $g\->addm($a, $m)\->mulm($b, $m)\->gcd($x);
.Ve
.PP
If you don't want an operation to affect the initial object, use the
\&\fBcopy()\fR operator:
.PP
.Vb 1
\& $h = $g\->copy()\->addm($a, $m)\->mulm($b, $m)\->gcd($x);
.Ve
.SS "add($other)"
.IX Subsection "add($other)"
Adds the value of \f(CW$other\fR to this \s-1MPI.\s0
.ie n .SS "addm($other, $modulus)"
.el .SS "addm($other, \f(CW$modulus\fP)"
.IX Subsection "addm($other, $modulus)"
Adds the value of \f(CW$other\fR to this \s-1MPI,\s0 modulo the value of \f(CW$modulus\fR.
.SS "sub($other)"
.IX Subsection "sub($other)"
Subtracts the value of \f(CW$other\fR from this \s-1MPI.\s0
.ie n .SS "subm($other, $modulus)"
.el .SS "subm($other, \f(CW$modulus\fP)"
.IX Subsection "subm($other, $modulus)"
Subtracts the value of \f(CW$other\fR from this \s-1MPI,\s0 modulo the value of \f(CW$modulus\fR.
.SS "mul($other)"
.IX Subsection "mul($other)"
Multiply this \s-1MPI\s0 by the value of \f(CW$other\fR.
.ie n .SS "mulm($other, $modulus)"
.el .SS "mulm($other, \f(CW$modulus\fP)"
.IX Subsection "mulm($other, $modulus)"
Multiply this \s-1MPI\s0 by the value of \f(CW$other\fR, modulo the value of \f(CW$modulus\fR.
.SS "mul_2exp($e)"
.IX Subsection "mul_2exp($e)"
Multiply this \s-1MPI\s0 by 2 raised to the power of \f(CW$e\fR (this is a leftward
bitshift)
.SS "div($other)"
.IX Subsection "div($other)"
Divide this \s-1MPI\s0 by the value of \f(CW$other\fR, leaving the integer quotient.
(This is integer division)
.SS "mod($other)"
.IX Subsection "mod($other)"
Divide this \s-1MPI\s0 by the value of \f(CW$other\fR, leaving the integer remainder.
(This is the modulus operation)
.ie n .SS "powm($other, $modulus)"
.el .SS "powm($other, \f(CW$modulus\fP)"
.IX Subsection "powm($other, $modulus)"
Raise this \s-1MPI\s0 to the power of \f(CW$other\fR, modulo the value of \f(CW$modulus\fR.
.SS "invm($modulus)"
.IX Subsection "invm($modulus)"
Find the multiplicative inverse of this \s-1MPI,\s0 modulo \f(CW$modulus\fR.
.SS "gcd($other)"
.IX Subsection "gcd($other)"
Find the greatest common divisor of this \s-1MPI\s0 and \f(CW$other\fR.
.SH "OUTPUT AND DEBUGGING"
.IX Header "OUTPUT AND DEBUGGING"
.SS "\fBdump()\fP"
.IX Subsection "dump()"
Send the \s-1MPI\s0 to the libgcrypt debugging stream.
.SS "print($format)"
.IX Subsection "print($format)"
Return a string with the data of this \s-1MPI,\s0 in a given format.  See
\&\s-1CONVERSION FORMATS\s0 for the available formats.
.SH "CONVERSION FORMATS"
.IX Header "CONVERSION FORMATS"
The available printing and scanning formats are all in the
Crypt::GCrypt::MPI namespace, and have the same meanings as in gcrypt.
.SS "\s-1FMT_STD\s0"
.IX Subsection "FMT_STD"
Two's complement representation.
.SS "\s-1FMT_PGP\s0"
.IX Subsection "FMT_PGP"
Same as \s-1FMT_STD,\s0 but with two-byte length header, as used in OpenPGP.
(Only works for non-negative values)
.SS "\s-1FMT_SSH\s0"
.IX Subsection "FMT_SSH"
Same as \s-1FMT_STD,\s0 but with four-byte length header, as used by OpenSSH.
.SS "\s-1FMT_HEX\s0"
.IX Subsection "FMT_HEX"
Hexadecimal string in \s-1ASCII.\s0
.SS "\s-1FMT_USG\s0"
.IX Subsection "FMT_USG"
Simple unsigned integer.
.SH "BUGS AND FEEDBACK"
.IX Header "BUGS AND FEEDBACK"
Crypt::GCrypt::MPI does not currently auto-convert to and from
Math::BigInt objects, even though it should.
.PP
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.
.SH "AUTHORS AND CONTRIBUTORS"
.IX Header "AUTHORS AND CONTRIBUTORS"
Daniel Kahn Gillmor <dkg@fifthhorseman.net>
.PP
Alessandro Ranellucci <aar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "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.
.SH "ACKNOWLEDGEMENTS"
.IX Header "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).
.SH "DISCLAIMER"
.IX Header "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.