1Bignum(3)             User Contributed Perl Documentation            Bignum(3)
2
3
4

NAME

6       Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic
7

SYNOPSIS

9         use Crypt::OpenSSL::Bignum;
10
11         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
19         use Crypt::OpenSSL::Bignum::CTX;
20
21         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

DESCRIPTION

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
41       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

Constructors

45       new_from_decimal
46            my $bn = Crypt::OpenSSL::Bignum->new_from_decimal($decimal_string);
47
48           Create a new Crypt::OpenSSL::Bignum object whose value is specified
49           by the given decimal representation.
50
51       new_from_hex
52            my $bn = Crypt::OpenSSL::Bignum->new_from_hex($hex_string); #no leading '0x'
53
54           Create a new Crypt::OpenSSL::Bignum object whose value is specified
55           by the given hexidecimal representation.
56
57       new_from_word
58            my $bn = Crypt::OpenSSL::Bignum->new_from_word($unsigned_integer);
59
60           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
64       new_from_bin
65            my $bn = Crypt::OpenSSL::Bignum->new_from_bin($bin_buffer);
66
67           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
71       new
72            my $bn = Crypt::OpenSSL::Bignum->new;
73
74           Returns a new Crypt::OpenSSL::Bignum object representing 0
75
76       zero
77            my $bn = Crypt::OpenSSL::Bignum->zero;
78
79           Returns a new Crypt::OpenSSL::Bignum object representing 0 (same as
80           new)
81
82       one
83            my $bn = Crypt::OpenSSL::Bignum->one;
84
85           Returns a new Crypt::OpenSSL::Bignum object representing 1
86
87       rand
88            my $bn = Crypt::OpenSSL::Bignum->rand($bits, $top, $bottom)
89            # $bits, $top, $bottom are integers
90
91           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
99       pseudo_rand
100            my $bn = Crypt::OpenSSL::Bignum->pseudo_rand($bits, $top, $bottom)
101            # $bits, $top, $bottom are integers
102
103           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
108       rand_range
109            my $bn = Crypt::OpenSSL::Bignum->rand_range($bn_range)
110
111           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
116       bless_pointer
117            my $bn = Crypt::OpenSSL::Bignum->bless_pointer($BIGNUM_ptr)
118
119           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
127           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

Instance Methods

133       to_decimal
134            my $decimal_string = $self->to_decimal;
135
136           Return a decimal string representation of this object.
137
138       to_hex
139            my $hex_string = $self->to_hex;
140
141           Return a hexidecimal string representation of this object.
142
143       to_bin
144            my $bin_buffer = $self->to_bin;
145
146           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
152       get_word
153            my $unsigned_int = $self->get_word;
154
155           Return a scalar integer representation of this object, if it can be
156           represented as an unsigned long.
157
158       is_zero
159            my $bool = $self->is_zero;
160
161           Returns true of this object represents 0.
162
163       is_one
164            my $bool = $self->is_one;
165
166           Returns true of this object represents 1.
167
168       is_odd
169            my $bool = $self->is_odd;
170
171           Returns true of this object represents an odd number.
172
173       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
178           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
183       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
188           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
194       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
199           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
206       div
207            my ($quotient, $remainder) = $self->div($bn_b, $ctx);
208            # or
209            $self->div($bn_b, $ctx, $quotient, $remainder);
210
211           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
220       mod
221            my $remainder = $self->mod($bn_b, $ctx);
222            # or
223            $self->mod($bn_b, $ctx, $remainder);
224
225           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
231       sqr
232            my $new_bn_object = $self->sqr($ctx);
233            # new object is created $self is not modified
234
235           This method returns the square ("$self ** 2") of
236           Crypt::OpenSSL::Bignum object.
237
238       exp
239            my $new_bn_object = $self->exp($bn_exp, $ctx);
240            # new object is created $self is not modified
241
242           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
246       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
250           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
255       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
259           This method returns "($self * $bn_b) % $bn_mod", using the third
260           argument, a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
261
262       mod_inverse
263            my $new_bn_object = $self->mod_inverse($bn_n, $ctx);
264            # new object is created $self is not modified
265
266           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
270       gcd
271            my $new_bn_object = $self->gcd($bn_b, $ctx);
272            # new object is created $self is not modified
273
274           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
278       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
285           Comparison of values $self and $bn_b (Crypt::OpenSSL::Bignum
286           objects).
287
288       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
295           Comparison using the absolute values of $self and $bn_b
296           (Crypt::OpenSSL::Bignum objects).
297
298       equals
299            my $result = $self->equals($bn_b);
300            #returns:
301            # 1 if self == bn_b
302            # 0 otherwise
303
304       num_bits
305            my $bits = $self->num_bits;
306
307           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
311       num_bytes
312            my $bytes = $self->num_bytes;
313
314           Returns the size of binary represenatation in bytes.
315
316       rshift
317            my $new_bn_object = $self->rshift($n);
318            # new object is created $self is not modified
319
320           Shifts a right by $n (integer) bits and places the result into a
321           newly created Crypt::OpenSSL::Bignum object.
322
323       lshift
324            my $new_bn_object = $self->lshift($n);
325            # new object is created $self is not modified
326
327           Shifts a left by $n (integer) bits and places the result into a
328           newly created Crypt::OpenSSL::Bignum object.
329
330       swap
331            my $bn_a = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890001");
332            my $bn_b = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890002");
333
334            $bn_a->swap($bn_b);
335            # or
336            $bn_b->swap($bn_a);
337
338           Exchanges the values of two Crypt::OpenSSL::Bignum objects.
339
340       copy
341            my $new_bn_object = $self->copy;
342
343           Returns a copy of this object.
344
345       pointer_copy
346            my $cloned_BIGNUM_ptr = $self->pointer_copy($BIGNUM_ptr);
347
348           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

AUTHOR

360       Ian Robertson, iroberts@cpan.org
361

SEE ALSO

363       <https://www.openssl.org/docs/crypto/bn.html>
364
365
366
367perl v5.34.0                      2021-07-22                         Bignum(3)
Impressum