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