1Crypt::GCrypt::MPI(3) User Contributed Perl DocumentationCrypt::GCrypt::MPI(3)
2
3
4

NAME

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

SYNOPSIS

10         use Crypt::GCrypt::MPI;
11
12         my $mpi = Crypt::GCrypt::MPI->new();
13

ABSTRACT

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

BASIC OPERATIONS

19   new()
20       Create a new multi-precision integer.
21
22         my $mpi = Crypt::GCrypt::MPI::new(
23           secure => 1,
24           value => 20,
25         );
26
27       No parameters are required.  If only one parameter is given, it is
28       treated as the "value" parameter.  Available parameters:
29
30       value
31           The initial value of the MPI.  This can be an integer, a string, or
32           another Crypt::GCrypt::MPI.  (It would also be nice to be able to
33           initialize it with a Math::Int).
34
35       secure
36           If this parameter evaluates to non-zero, initialize the MPI using
37           secure memory, if possible.
38
39       format
40           If the value is a string, the format parameter suggests how to
41           convert the string.  See CONVERSION FORMATS for the available
42           formats.  Defaults to Crypt::GCrypt::MPI::FMT_STD.
43
44   set()
45       Copies the value of the other Crypt::GCrypt::MPI object.
46
47         $mpi->set($othermpi);
48
49   swap()
50       Exchanges the value with the value of another Crypt::GCrpyt::MPI
51       object:
52
53         $mpi->swap($othermpi);
54
55   is_secure()
56       Returns true if the Crypt::GCrypt::MPI uses secure memory, where
57       possible.
58
59   cmp($other)
60       Compares this object against another Crypt::GCrypt::MPI object,
61       returning 0 if the two values are equal, positive if this value is
62       greater, negative if $other is greater.
63
64   mutually_prime($other)
65       Compares this object against another Crypt::GCrypt::MPI object,
66       returning true only if the two values share no factors in common other
67       than 1.
68
69   copy()
70       Returns a new Crypt::GCrypt::MPI object, with the contents identical to
71       this one.  This is different from using the assignment operator (=),
72       which just makes two references to the same object.  For example:
73
74        $b = new Crypt::GCrypt::MPI(15);
75        $a = $b;
76        $b->add(1); # $a points to the same object,
77                    # so both $a and $b contain 16.
78
79        $a = $b->copy(); # $a and $b are both 16, but
80                         # different objects; no risk of
81                         # double-free.
82        $b->add(1); # $a == 16, $b == 17
83
84       If $b is a Crypt::GCrypt::MPI object, then "$a = $b->copy();" is
85       identical to "$a = Crypt::GCrypt::MPI->new($b);"
86

CALCULATIONS

88       All calculation operations modify the object they are called on, and
89       return the same object, so you can chain them like this:
90
91        $g->addm($a, $m)->mulm($b, $m)->gcd($x);
92
93       If you don't want an operation to affect the initial object, use the
94       copy() operator:
95
96        $h = $g->copy()->addm($a, $m)->mulm($b, $m)->gcd($x);
97
98   add($other)
99       Adds the value of $other to this MPI.
100
101   addm($other, $modulus)
102       Adds the value of $other to this MPI, modulo the value of $modulus.
103
104   sub($other)
105       Subtracts the value of $other from this MPI.
106
107   subm($other, $modulus)
108       Subtracts the value of $other from this MPI, modulo the value of
109       $modulus.
110
111   mul($other)
112       Multiply this MPI by the value of $other.
113
114   mulm($other, $modulus)
115       Multiply this MPI by the value of $other, modulo the value of $modulus.
116
117   mul_2exp($e)
118       Multiply this MPI by 2 raised to the power of $e (this is a leftward
119       bitshift)
120
121   div($other)
122       Divide this MPI by the value of $other, leaving the integer quotient.
123       (This is integer division)
124
125   mod($other)
126       Divide this MPI by the value of $other, leaving the integer remainder.
127       (This is the modulus operation)
128
129   powm($other, $modulus)
130       Raise this MPI to the power of $other, modulo the value of $modulus.
131
132   invm($modulus)
133       Find the multiplicative inverse of this MPI, modulo $modulus.
134
135   gcd($other)
136       Find the greatest common divisor of this MPI and $other.
137

OUTPUT AND DEBUGGING

139   dump()
140       Send the MPI to the libgcrypt debugging stream.
141
142   print($format)
143       Return a string with the data of this MPI, in a given format.  See
144       CONVERSION FORMATS for the available formats.
145

CONVERSION FORMATS

147       The available printing and scanning formats are all in the
148       Crypt::GCrypt::MPI namespace, and have the same meanings as in gcrypt.
149
150   FMT_STD
151       Two's complement representation.
152
153   FMT_PGP
154       Same as FMT_STD, but with two-byte length header, as used in OpenPGP.
155       (Only works for non-negative values)
156
157   FMT_SSH
158       Same as FMT_STD, but with four-byte length header, as used by OpenSSH.
159
160   FMT_HEX
161       Hexadecimal string in ASCII.
162
163   FMT_USG
164       Simple unsigned integer.
165

BUGS AND FEEDBACK

167       Crypt::GCrypt::MPI does not currently auto-convert to and from
168       Math::BigInt objects, even though it should.
169
170       Other than that, here are no known bugs. You are very welcome to write
171       mail to the maintainer (aar@cpan.org) with your contributions,
172       comments, suggestions, bug reports or complaints.
173

AUTHORS AND CONTRIBUTORS

175       Daniel Kahn Gillmor <dkg@fifthhorseman.net>
176
177       Alessandro Ranellucci <aar@cpan.org>
178
180       Copyright © Daniel Kahn Gillmor.  Crypt::GCrypt::MPI is free software,
181       you may redistribute it and/or modify it under the same terms as Perl
182       itself.
183

ACKNOWLEDGEMENTS

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

DISCLAIMER

190       This software is provided by the copyright holders and contributors
191       ``as is'' and any express or implied warranties, including, but not
192       limited to, the implied warranties of merchantability and fitness for a
193       particular purpose are disclaimed. In no event shall the regents or
194       contributors be liable for any direct, indirect, incidental, special,
195       exemplary, or consequential damages (including, but not limited to,
196       procurement of substitute goods or services; loss of use, data, or
197       profits; or business interruption) however caused and on any theory of
198       liability, whether in contract, strict liability, or tort (including
199       negligence or otherwise) arising in any way out of the use of this
200       software, even if advised of the possibility of such damage.
201
202
203
204perl v5.30.1                      2020-01-29             Crypt::GCrypt::MPI(3)
Impressum