1package Crypt::OpenSSL::Bignum;
2
3use 5.005;
4use strict;
5use Carp;
6
7use vars qw( $VERSION @ISA );
8
9require DynaLoader;
10
11@ISA = qw(DynaLoader);
12
13$VERSION = '0.04';
14
15bootstrap Crypt::OpenSSL::Bignum $VERSION;
16
17sub DESTROY
18{
19    shift->_free_BN();
20}
21
22sub bless_pointer
23{
24    my( $proto, $p_pointer ) = @_;
25    return bless( \$p_pointer, $proto );
26}
27
28sub equals
29{
30    my( $self, $a ) = @_;
31    return ! $self->cmp( $a );
32}
33
34
351;
36__END__
37
38=head1 NAME
39
40Crypt::OpenSSL::Bignum - OpenSSL's multiprecision integer arithmetic
41
42=head1 SYNOPSIS
43
44  use Crypt::OpenSSL::Bignum;
45
46  my $bn = Crypt::OpenSSL::Bignum->new_from_decimal( "1000" );
47  # or
48  my $bn = Crypt::OpenSSL::Bignum->new_from_word( 1000 );
49  # or
50  my $bn = Crypt::OpenSSL::Bignum->new_from_hex("0x3e8");
51  # or
52  my $bn = Crypt::OpenSSL::Bignum->new_from_bin(pack( "C*", 3, 232 ))
53
54  use Crypt::OpenSSL::Bignum::CTX;
55
56  sub print_factorial
57  {
58    my( $n ) = @_;
59    my $fac = Crypt::OpenSSL::Bignum->one();
60    my $ctx = Crypt::OpenSSL::Bignum::CTX->new();
61    foreach my $i (1 .. $n)
62    {
63      $fac->mul( Crypt::OpenSSL::Bignum->new_from_word( $i ), $ctx, $fac );
64    }
65    print "$n factorial is ", $fac->to_decimal(), "\n";
66  }
67
68=head1 DESCRIPTION
69
70Crypt::OpenSSL::Bignum provides access to OpenSSL multiprecision
71integer arithmetic libraries.  Presently, many though not all of the
72arithmetic operations that OpenSSL provides are exposed to perl.  In
73addition, this module can be used to provide access to bignum values
74produced by other OpenSSL modules, such as key parameters from
75Crypt::OpenSSL::RSA.
76
77I<NOTE>: Many of the methods in this package can croak, so use eval, or
78Error.pm's try/catch mechanism to capture errors.
79
80=head1 Class Methods
81
82=over
83
84=item new_from_word
85
86Create a new Crypt::OpenSSL::Bignum object whose value will be the
87word given.  Note that numbers represneted by objects created using
88this method are necessarily between 0 and 2^32 - 1.
89
90=item new_from_decimal
91
92Create a new Crypt::OpenSSL::Bignum object whose value is specified by
93the given decimal representation.
94
95=item new_from_hex
96
97Create a new Crypt::OpenSSL::Bignum object whose value is specified by
98the given hexidecimal representation.
99
100=item new_from_bin
101
102Create a new Crypt::OpenSSL::Bignum object whose value is specified by
103the given packed binary string.  Note that objects created using this
104method are necessarily nonnegative.
105
106=item zero
107
108Returns a new Crypt::OpenSSL::Bignum object representing 0
109
110=item one
111
112Returns a new Crypt::OpenSSL::Bignum object representing 1
113
114=item bless_pointer
115
116Given a pointer to a OpenSSL BIGNUM object in memory, construct and
117return Crypt::OpenSSL::Bignum object around this.  Note that the
118underlying BIGNUM object will be destroyed (via BN_clear_free(3ssl))
119when the returned Crypt::OpenSSL::Bignum object is no longer
120referenced, so the pointer passed to this method should only be
121referenced via the returned perl object after calling bless_pointer.
122
123This method is intended only for use by XSUB writers writing code that
124interfaces with OpenSSL library methods, and who wish to be able to
125return a BIGNUM structure to perl as a Crypt::OpenSSL::Bignum object.
126
127=back
128
129=head1 Instance Methods
130
131=over
132
133=item to_decimal
134
135Return a decimal string representation of this object.
136
137=item to_hex
138
139Return a hexidecimal string representation of this object.
140
141=item to_bin
142
143Return a packed binary string representation of this object.  Note
144that sign is ignored, so that to bin called on a
145Crypt::OpenSSL::Bignum object representing a negative number returns
146the same value as it would called on an object representing that
147number's absolute value.
148
149=item get_word
150
151Return a scalar integer representation of this object, if it can be
152represented as an unsigned long.
153
154=item is_zero
155
156Returns true of this object represents 0.
157
158=item is_one
159
160Returns true of this object represents 1.
161
162=item is_odd
163
164Returns true of this object represents an odd number.
165
166=item copy
167
168Returns a copy of this object.
169
170=item add
171
172This method returns the sum of this object and the first argument.  If
173only one argument is passed, a new Crypt::OpenSSL::Bignum object is
174created for the return value; otherwise, the value of second argument
175is set to the result and returned.
176
177=item sub
178
179This method returns the difference of this object and the first
180argument.  If only one argument is passed, a new
181Crypt::OpenSSL::Bignum object is created for the return value;
182otherwise, the value of second argument is set to the result and
183returned.
184
185=item mul
186
187This method returns the product of this object and the first argument,
188using the second argument, a Crypt::OpenSSL::Bignum::CTX object, as a
189scratchpad.  If only two arguments are passed, a new
190Crypt::OpenSSL::Bignum object is created for the return value;
191otherwise, the value of third argument is set to the result and
192returned.
193
194=item div
195
196This method returns a list consisting of quotient and the remainder
197obtained by dividing this object by the first argument, using the
198second argument, a Crypt::OpenSSL::Bignum::CTX object, as a
199scratchpad.  If only two arguments are passed, new
200Crypt::OpenSSL::Bignum objects is created for both return values.  If
201a third argument is passed, otherwise, the value of third argument is
202set to the quotient.  If a fourth argument is passed, the value of the
203fourth argument is set to the remainder.
204
205=item exp
206
207This method returns the product of this object exponeniated by the
208first argument, using the second argument, a
209Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
210
211=item mod_exp
212
213This method returns the product of this object exponeniated by the
214first argument, modulo the second argument, using the third argument, a
215Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.
216
217=item pointer_copy
218
219This method is intended only for use by XSUB writers wanting to have
220access to the underlying BIGNUM structure referenced by a
221Crypt::OpenSSL::Bignum perl object so that they can pass them to other
222routines in the OpenSSL library.  It returns a perl scalar whose IV
223can be cast to a BIGNUM* value.  This can then be passed to an XSUB
224which can work with the BIGNUM directly.  Note that the BIGNUM object
225pointed to will be a copy of the BIGNUM object wrapped by the
226instance; it is thus the responsiblity of the client to free space
227allocated by this BIGNUM object if and when it is done with it. See
228also bless_pointer.
229
230=back
231
232=head1 AUTHOR
233
234Ian Robertson, iroberts@cpan.org
235
236=head1 SEE ALSO
237
238L<perl>, L<bn(3ssl)>
239
240=cut
241