1Bignum(3) User Contributed Perl Documentation Bignum(3)
2
6 Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic
7
9 use Crypt::OpenSSL::Bignum;
10 my $bn = Crypt::OpenSSL::Bignum->new_from_decimal( "1000" );
12 # or
13 my $bn = Crypt::OpenSSL::Bignum->new_from_word( 1000 );
14 # or
15 my $bn = Crypt::OpenSSL::Bignum->new_from_hex("3e8"); # no leading 0x
16 # or
17 my $bn = Crypt::OpenSSL::Bignum->new_from_bin(pack( "C*", 3, 232 ))
18 use Crypt::OpenSSL::Bignum::CTX;
20 sub print_factorial
22 {
23 my( $n ) = @_;
24 my $fac = Crypt::OpenSSL::Bignum->one();
25 my $ctx = Crypt::OpenSSL::Bignum::CTX->new();
26 foreach my $i (1 .. $n)
27 {
28 $fac->mul( Crypt::OpenSSL::Bignum->new_from_word( $i ), $ctx, $fac );
29 }
30 print "$n factorial is ", $fac->to_decimal(), "\n";
31 }
32
34 Crypt::OpenSSL::Bignum provides access to OpenSSL multiprecision
35 integer arithmetic libraries. Presently, many though not all of the
36 arithmetic operations that OpenSSL provides are exposed to perl. In
37 addition, this module can be used to provide access to bignum values
38 produced by other OpenSSL modules, such as key parameters from
39 Crypt::OpenSSL::RSA.
40 NOTE: Many of the methods in this package can croak, so use eval, or
42 Error.pm's try/catch mechanism to capture errors.
43
45 new_from_decimal
46 my $bn = Crypt::OpenSSL::Bignum->new_from_decimal($decimal_string);
47 Create a new Crypt::OpenSSL::Bignum object whose value is specified
49 by the given decimal representation.
50 new_from_hex
52 my $bn = Crypt::OpenSSL::Bignum->new_from_hex($hex_string); #no leading '0x'
53 Create a new Crypt::OpenSSL::Bignum object whose value is specified
55 by the given hexidecimal representation.
56 new_from_word
58 my $bn = Crypt::OpenSSL::Bignum->new_from_word($unsigned_integer);
59 Create a new Crypt::OpenSSL::Bignum object whose value will be the
61 word given. Note that numbers represented by objects created using
62 this method are necessarily between 0 and 2^32 - 1.
63 new_from_bin
65 my $bn = Crypt::OpenSSL::Bignum->new_from_bin($bin_buffer);
66 Create a new Crypt::OpenSSL::Bignum object whose value is specified
68 by the given packed binary string (created by "to_bin"). Note that
69 objects created using this method are necessarily nonnegative.
70 new
72 my $bn = Crypt::OpenSSL::Bignum->new;
73 Returns a new Crypt::OpenSSL::Bignum object representing 0
75 zero
77 my $bn = Crypt::OpenSSL::Bignum->zero;
78 Returns a new Crypt::OpenSSL::Bignum object representing 0 (same as
80 new)
81 one
83 my $bn = Crypt::OpenSSL::Bignum->one;
84 Returns a new Crypt::OpenSSL::Bignum object representing 1
86 rand
88 my $bn = Crypt::OpenSSL::Bignum->rand($bits, $top, $bottom)
89 # $bits, $top, $bottom are integers
90 generates a cryptographically strong pseudo-random number of bits
92 bits in length and stores it in rnd. If top is -1, the most
93 significant bit of the random number can be zero. If top is 0, it
94 is set to 1, and if top is 1, the two most significant bits of the
95 number will be set to 1, so that the product of two such random
96 numbers will always have 2*bits length. If bottom is true, the
97 number will be odd.
98 pseudo_rand
100 my $bn = Crypt::OpenSSL::Bignum->pseudo_rand($bits, $top, $bottom)
101 # $bits, $top, $bottom are integers
102 does the same, but pseudo-random numbers generated by this function
104 are not necessarily unpredictable. They can be used for non-
105 cryptographic purposes and for certain purposes in cryptographic
106 protocols, but usually not for key generation etc.
107 rand_range
109 my $bn = Crypt::OpenSSL::Bignum->rand_range($bn_range)
110 generates a cryptographically strong pseudo-random number rnd in
112 the range 0 <lt>= rnd < range. BN_pseudo_rand_range() does the
113 same, but is based on BN_pseudo_rand(), and hence numbers generated
114 by it are not necessarily unpredictable.
115 bless_pointer
117 my $bn = Crypt::OpenSSL::Bignum->bless_pointer($BIGNUM_ptr)
118 Given a pointer to a OpenSSL BIGNUM object in memory, construct and
120 return Crypt::OpenSSL::Bignum object around this. Note that the
121 underlying BIGNUM object will be destroyed (via
122 BN_clear_free(3ssl)) when the returned Crypt::OpenSSL::Bignum
123 object is no longer referenced, so the pointer passed to this
124 method should only be referenced via the returned perl object after
125 calling bless_pointer.
126 This method is intended only for use by XSUB writers writing code
128 that interfaces with OpenSSL library methods, and who wish to be
129 able to return a BIGNUM structure to perl as a
130 Crypt::OpenSSL::Bignum object.
131
133 to_decimal
134 my $decimal_string = $self->to_decimal;
135 Return a decimal string representation of this object.
137 to_hex
139 my $hex_string = $self->to_hex;
140 Return a hexidecimal string representation of this object.
142 to_bin
144 my $bin_buffer = $self->to_bin;
145 Return a packed binary string representation of this object. Note
147 that sign is ignored, so that to bin called on a
148 Crypt::OpenSSL::Bignum object representing a negative number
149 returns the same value as it would called on an object representing
150 that number's absolute value.
151 get_word
153 my $unsigned_int = $self->get_word;
154 Return a scalar integer representation of this object, if it can be
156 represented as an unsigned long.
157 is_zero
159 my $bool = $self->is_zero;
160 Returns true of this object represents 0.
162 is_one
164 my $bool = $self->is_one;
165 Returns true of this object represents 1.
167 is_odd
169 my $bool = $self->is_odd;
170 Returns true of this object represents an odd number.
172 add
174 my $new_bn_object = $self->add($bn_b); # $new_bn_object = $self + $bn_b
175 # or
176 $self->add($bn_b, $result_bn); # $result_bn = $self + $bn_b
177 This method returns the sum of this object and the first argument.
179 If only one argument is passed, a new Crypt::OpenSSL::Bignum object
180 is created for the return value; otherwise, the value of second
181 argument is set to the result and returned.
182 sub
184 my $new_bn_object = $self->sub($bn_b); # $new_bn_object = $self - $bn_b
185 # or
186 $self->sub($bn_b, $result_bn); # $result_bn = $self - $bn_b
187 This method returns the difference of this object and the first
189 argument. If only one argument is passed, a new
190 Crypt::OpenSSL::Bignum object is created for the return value;
191 otherwise, the value of second argument is set to the result and
192 returned.
193 mul
195 my $new_bn_object = $self->mul($bn_b, $ctx); # $new_bn_object = $self * $bn_b
196 # or
197 $self->mul($bn_b, $ctx, $result_bn); # $result_bn = $self * $bn_b
198 This method returns the product of this object and the first
200 argument, using the second argument, a Crypt::OpenSSL::Bignum::CTX
201 object, as a scratchpad. If only two arguments are passed, a new
202 Crypt::OpenSSL::Bignum object is created for the return value;
203 otherwise, the value of third argument is set to the result and
204 returned.
205 div
207 my ($quotient, $remainder) = $self->div($bn_b, $ctx);
208 # or
209 $self->div($bn_b, $ctx, $quotient, $remainder);
210 This method returns a list consisting of quotient and the remainder
212 obtained by dividing this object by the first argument, using the
213 second argument, a Crypt::OpenSSL::Bignum::CTX object, as a
214 scratchpad. If only two arguments are passed, new
215 Crypt::OpenSSL::Bignum objects are created for both return values.
216 If a third argument is passed, otherwise, the value of third
217 argument is set to the quotient. If a fourth argument is passed,
218 the value of the fourth argument is set to the remainder.
219 mod
221 my $remainder = $self->mod($bn_b, $ctx);
222 # or
223 $self->mod($bn_b, $ctx, $remainder);
224 This method returns the remainder obtained by dividing this object
226 by the first argument, a Crypt::OpenSSL::Bignum::CTX object, as a
227 scratchpad. Crypt::OpenSSL::Bignum object is created for the return
228 value. If a third argument is passed, the value of third argument
229 is set to the remainder.
230 sqr
232 my $new_bn_object = $self->sqr($ctx);
233 # new object is created $self is not modified
234 This method returns the square ("$self ** 2") of
236 Crypt::OpenSSL::Bignum object.
237 exp
239 my $new_bn_object = $self->exp($bn_exp, $ctx);
240 # new object is created $self is not modified
241 This method returns the product of this object exponentiated by the
243 first argument (Crypt::OpenSSL::Bignum object), using the second
244 argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
245 mod_exp
247 my $new_bn_object = $self->exp_mod($bn_exp, $bn_mod, $ctx);
248 # new object is created $self is not modified
249 This method returns the product of this object exponentiated by the
251 first argument (Crypt::OpenSSL::Bignum object), modulo the second
252 argument (also Crypt::OpenSSL::Bignum object), using the third
253 argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
254 mod_mul
256 my $new_bn_object = $self->mod_mul($bn_b, $bn_mod, $ctx);
257 # new object is created $self is not modified
258 This method returns "($self * $bn_b) % $bn_mod", using the third
260 argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
261 mod_inverse
263 my $new_bn_object = $self->mod_inverse($bn_n, $ctx);
264 # new object is created $self is not modified
265 Computes the inverse of $self modulo $bn_n and returns the result
267 in a new Crypt::OpenSSL::Bignum object, using the second argument,
268 a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
269 gcd
271 my $new_bn_object = $self->gcd($bn_b, $ctx);
272 # new object is created $self is not modified
273 Computes the greatest common divisor of $self and $bn_b and returns
275 the result in a new Crypt::OpenSSL::Bignum object, using the second
276 argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
277 cmp
279 my $result = $self->cmp($bn_b);
280 #returns:
281 # -1 if self < bn_b
282 # 0 if self == bn_b
283 # 1 if self > bn_b
284 Comparison of values $self and $bn_b (Crypt::OpenSSL::Bignum
286 objects).
287 ucmp
289 my $result = $self->ucmp($bn_b);
290 #returns:
291 # -1 if |self| < |bn_b|
292 # 0 if |self| == |bn_b|
293 # 1 if |self| > |bn_b|
294 Comparison using the absolute values of $self and $bn_b
296 (Crypt::OpenSSL::Bignum objects).
297 equals
299 my $result = $self->equals($bn_b);
300 #returns:
301 # 1 if self == bn_b
302 # 0 otherwise
303 num_bits
305 my $bits = $self->num_bits;
306 Returns the number of significant bits in a word. If we take
308 0x00000432 as an example, it returns 11, not 16, not 32. Basically,
309 except for a zero, it returns "floor(log2(w)) + 1".
310 num_bytes
312 my $bytes = $self->num_bytes;
313 Returns the size of binary represenatation in bytes.
315 rshift
317 my $new_bn_object = $self->rshift($n);
318 # new object is created $self is not modified
319 Shifts a right by $n (integer) bits and places the result into a
321 newly created Crypt::OpenSSL::Bignum object.
322 lshift
324 my $new_bn_object = $self->lshift($n);
325 # new object is created $self is not modified
326 Shifts a left by $n (integer) bits and places the result into a
328 newly created Crypt::OpenSSL::Bignum object.
329 swap
331 my $bn_a = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890001");
332 my $bn_b = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890002");
333 $bn_a->swap($bn_b);
335 # or
336 $bn_b->swap($bn_a);
337 Exchanges the values of two Crypt::OpenSSL::Bignum objects.
339 copy
341 my $new_bn_object = $self->copy;
342 Returns a copy of this object.
344 pointer_copy
346 my $cloned_BIGNUM_ptr = $self->pointer_copy($BIGNUM_ptr);
347 This method is intended only for use by XSUB writers wanting to
349 have access to the underlying BIGNUM structure referenced by a
350 Crypt::OpenSSL::Bignum perl object so that they can pass them to
351 other routines in the OpenSSL library. It returns a perl scalar
352 whose IV can be cast to a BIGNUM* value. This can then be passed
353 to an XSUB which can work with the BIGNUM directly. Note that the
354 BIGNUM object pointed to will be a copy of the BIGNUM object
355 wrapped by the instance; it is thus the responsibility of the
356 client to free space allocated by this BIGNUM object if and when it
357 is done with it. See also bless_pointer.
358
360 Ian Robertson, iroberts@cpan.org
361
363 <https://www.openssl.org/docs/crypto/bn.html>
364perl v5.34.0 2022-01-21 Bignum(3)