1Crypt::GCrypt::MPI(3) User Contributed Perl DocumentationCrypt::GCrypt::MPI(3)
2
6 Crypt::GCrypt::MPI - Perl interface to multi-precision integers from
7 the GNU Cryptographic library
8
10 use Crypt::GCrypt::MPI;
11 my $mpi = Crypt::GCrypt::MPI->new();
13
15 Crypt::GCrypt::MPI provides an object interface to multi-precision
16 integers from the C libgcrypt library.
17
19 new()
20 Create a new multi-precision integer.
21 my $mpi = Crypt::GCrypt::MPI::new(
23 secure => 1,
24 value => 20,
25 );
26 No parameters are required. If only one parameter is given, it is
28 treated as the "value" parameter. Available parameters:
29 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 secure
36 If this parameter evaluates to non-zero, initialize the MPI using
37 secure memory, if possible.
38 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 set()
45 Copies the value of the other Crypt::GCrypt::MPI object.
46 $mpi->set($othermpi);
48 swap()
50 Exchanges the value with the value of another Crypt::GCrpyt::MPI
51 object:
52 $mpi->swap($othermpi);
54 is_secure()
56 Returns true if the Crypt::GCrypt::MPI uses secure memory, where
57 possible.
58 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 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 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 $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 $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 If $b is a Crypt::GCrypt::MPI object, then "$a = $b->copy();" is
85 identical to "$a = Crypt::GCrypt::MPI->new($b);"
86
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 $g->addm($a, $m)->mulm($b, $m)->gcd($x);
92 If you don't want an operation to affect the initial object, use the
94 copy() operator:
95 $h = $g->copy()->addm($a, $m)->mulm($b, $m)->gcd($x);
97 add($other)
99 Adds the value of $other to this MPI.
100 addm($other, $modulus)
102 Adds the value of $other to this MPI, modulo the value of $modulus.
103 sub($other)
105 Subtracts the value of $other from this MPI.
106 subm($other, $modulus)
108 Subtracts the value of $other from this MPI, modulo the value of
109 $modulus.
110 mul($other)
112 Multiply this MPI by the value of $other.
113 mulm($other, $modulus)
115 Multiply this MPI by the value of $other, modulo the value of $modulus.
116 mul_2exp($e)
118 Multiply this MPI by 2 raised to the power of $e (this is a leftward
119 bitshift)
120 div($other)
122 Divide this MPI by the value of $other, leaving the integer quotient.
123 (This is integer division)
124 mod($other)
126 Divide this MPI by the value of $other, leaving the integer remainder.
127 (This is the modulus operation)
128 powm($other, $modulus)
130 Raise this MPI to the power of $other, modulo the value of $modulus.
131 invm($modulus)
133 Find the multiplicative inverse of this MPI, modulo $modulus.
134 gcd($other)
136 Find the greatest common divisor of this MPI and $other.
137
139 dump()
140 Send the MPI to the libgcrypt debugging stream.
141 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
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 FMT_STD
151 Two's complement representation.
152 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 FMT_SSH
158 Same as FMT_STD, but with four-byte length header, as used by OpenSSH.
159 FMT_HEX
161 Hexadecimal string in ASCII.
162 FMT_USG
164 Simple unsigned integer.
165
167 Crypt::GCrypt::MPI does not currently auto-convert to and from
168 Math::BigInt objects, even though it should.
169 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
175 Daniel Kahn Gillmor <dkg@fifthhorseman.net>
176 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
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
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.
201perl v5.38.0 2023-07-20 Crypt::GCrypt::MPI(3)