Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bignum(3)	      User Contributed Perl Documentation	     Bignum(3)

NAME
       Crypt::OpenSSL::Bignum -	OpenSSL's multiprecision integer arithmetic

SYNOPSIS
	 use Crypt::OpenSSL::Bignum;

	 my $bn	= Crypt::OpenSSL::Bignum->new_from_decimal( "1000" );
	 # or
	 my $bn	= Crypt::OpenSSL::Bignum->new_from_word( 1000 );
	 # or
	 my $bn	= Crypt::OpenSSL::Bignum->new_from_hex("3e8"); # no leading 0x
	 # or
	 my $bn	= Crypt::OpenSSL::Bignum->new_from_bin(pack( "C*", 3, 232 ))

	 use Crypt::OpenSSL::Bignum::CTX;

	 sub print_factorial
	 {
	   my( $n ) = @_;
	   my $fac = Crypt::OpenSSL::Bignum->one();
	   my $ctx = Crypt::OpenSSL::Bignum::CTX->new();
	   foreach my $i (1 .. $n)
	   {
	     $fac->mul(	Crypt::OpenSSL::Bignum->new_from_word( $i ), $ctx, $fac	);
	   }
	   print "$n factorial is ", $fac->to_decimal(), "\n";
	 }

DESCRIPTION
       Crypt::OpenSSL::Bignum provides access to OpenSSL multiprecision
       integer arithmetic libraries.  Presently, many though not all of	the
       arithmetic operations that OpenSSL provides are exposed to perl.	 In
       addition, this module can be used to provide access to bignum values
       produced	by other OpenSSL modules, such as key parameters from
       Crypt::OpenSSL::RSA.

       NOTE: Many of the methods in this package can croak, so use eval, or
       Error.pm's try/catch mechanism to capture errors.

Constructors
       new_from_decimal
	    my $bn = Crypt::OpenSSL::Bignum->new_from_decimal($decimal_string);

	   Create a new	Crypt::OpenSSL::Bignum object whose value is specified
	   by the given	decimal	representation.

       new_from_hex
	    my $bn = Crypt::OpenSSL::Bignum->new_from_hex($hex_string);	#no leading '0x'

	   Create a new	Crypt::OpenSSL::Bignum object whose value is specified
	   by the given	hexidecimal representation.

       new_from_word
	    my $bn = Crypt::OpenSSL::Bignum->new_from_word($unsigned_integer);

	   Create a new	Crypt::OpenSSL::Bignum object whose value will be the
	   word	given.	Note that numbers represented by objects created using
	   this	method are necessarily between 0 and 2^32 - 1.

       new_from_bin
	    my $bn = Crypt::OpenSSL::Bignum->new_from_bin($bin_buffer);

	   Create a new	Crypt::OpenSSL::Bignum object whose value is specified
	   by the given	packed binary string (created by "to_bin"). Note that
	   objects created using this method are necessarily nonnegative.

       new
	    my $bn = Crypt::OpenSSL::Bignum->new;

	   Returns a new Crypt::OpenSSL::Bignum	object representing 0

       zero
	    my $bn = Crypt::OpenSSL::Bignum->zero;

	   Returns a new Crypt::OpenSSL::Bignum	object representing 0 (same as
	   new)

       one
	    my $bn = Crypt::OpenSSL::Bignum->one;

	   Returns a new Crypt::OpenSSL::Bignum	object representing 1

       rand
	    my $bn = Crypt::OpenSSL::Bignum->rand($bits, $top, $bottom)
	    # $bits, $top, $bottom are integers

	   generates a cryptographically strong	pseudo-random number of	bits
	   bits	in length and stores it	in rnd.	If top is -1, the most
	   significant bit of the random number	can be zero. If	top is 0, it
	   is set to 1,	and if top is 1, the two most significant bits of the
	   number will be set to 1, so that the	product	of two such random
	   numbers will	always have 2*bits length. If bottom is	true, the
	   number will be odd.

       pseudo_rand
	    my $bn = Crypt::OpenSSL::Bignum->pseudo_rand($bits,	$top, $bottom)
	    # $bits, $top, $bottom are integers

	   does	the same, but pseudo-random numbers generated by this function
	   are not necessarily unpredictable. They can be used for non-
	   cryptographic purposes and for certain purposes in cryptographic
	   protocols, but usually not for key generation etc.

       rand_range
	    my $bn = Crypt::OpenSSL::Bignum->rand_range($bn_range)

	   generates a cryptographically strong	pseudo-random number rnd in
	   the range 0 <lt>= rnd < range. BN_pseudo_rand_range() does the
	   same, but is	based on BN_pseudo_rand(), and hence numbers generated
	   by it are not necessarily unpredictable.

       bless_pointer
	    my $bn = Crypt::OpenSSL::Bignum->bless_pointer($BIGNUM_ptr)

	   Given a pointer to a	OpenSSL	BIGNUM object in memory, construct and
	   return Crypt::OpenSSL::Bignum object	around this.  Note that	the
	   underlying BIGNUM object will be destroyed (via
	   BN_clear_free(3ssl))	when the returned Crypt::OpenSSL::Bignum
	   object is no	longer referenced, so the pointer passed to this
	   method should only be referenced via	the returned perl object after
	   calling bless_pointer.

	   This	method is intended only	for use	by XSUB	writers	writing	code
	   that	interfaces with	OpenSSL	library	methods, and who wish to be
	   able	to return a BIGNUM structure to	perl as	a
	   Crypt::OpenSSL::Bignum object.

Instance Methods
       to_decimal
	    my $decimal_string = $self->to_decimal;

	   Return a decimal string representation of this object.

       to_hex
	    my $hex_string = $self->to_hex;

	   Return a hexidecimal	string representation of this object.

       to_bin
	    my $bin_buffer = $self->to_bin;

	   Return a packed binary string representation	of this	object.	 Note
	   that	sign is	ignored, so that to bin	called on a
	   Crypt::OpenSSL::Bignum object representing a	negative number
	   returns the same value as it	would called on	an object representing
	   that	number's absolute value.

       get_word
	    my $unsigned_int = $self->get_word;

	   Return a scalar integer representation of this object, if it	can be
	   represented as an unsigned long.

       is_zero
	    my $bool = $self->is_zero;

	   Returns true	of this	object represents 0.

       is_one
	    my $bool = $self->is_one;

	   Returns true	of this	object represents 1.

       is_odd
	    my $bool = $self->is_odd;

	   Returns true	of this	object represents an odd number.

       add
	    my $new_bn_object =	$self->add($bn_b); # $new_bn_object = $self + $bn_b
	    # or
	    $self->add($bn_b, $result_bn);	   # $result_bn	= $self	+ $bn_b

	   This	method returns the sum of this object and the first argument.
	   If only one argument	is passed, a new Crypt::OpenSSL::Bignum	object
	   is created for the return value; otherwise, the value of second
	   argument is set to the result and returned.

       sub
	    my $new_bn_object =	$self->sub($bn_b); # $new_bn_object = $self - $bn_b
	    # or
	    $self->sub($bn_b, $result_bn);	   # $result_bn	= $self	- $bn_b

	   This	method returns the difference of this object and the first
	   argument.  If only one argument is passed, a	new
	   Crypt::OpenSSL::Bignum object is created for	the return value;
	   otherwise, the value	of second argument is set to the result	and
	   returned.

       mul
	    my $new_bn_object =	$self->mul($bn_b, $ctx); # $new_bn_object = $self * $bn_b
	    # or
	    $self->mul($bn_b, $ctx, $result_bn);	 # $result_bn =	$self *	$bn_b

	   This	method returns the product of this object and the first
	   argument, using the second argument,	a Crypt::OpenSSL::Bignum::CTX
	   object, as a	scratchpad.  If	only two arguments are passed, a new
	   Crypt::OpenSSL::Bignum object is created for	the return value;
	   otherwise, the value	of third argument is set to the	result and
	   returned.

       div
	    my ($quotient, $remainder) = $self->div($bn_b, $ctx);
	    # or
	    $self->div($bn_b, $ctx, $quotient, $remainder);

	   This	method returns a list consisting of quotient and the remainder
	   obtained by dividing	this object by the first argument, using the
	   second argument, a Crypt::OpenSSL::Bignum::CTX object, as a
	   scratchpad.	If only	two arguments are passed, new
	   Crypt::OpenSSL::Bignum objects are created for both return values.
	   If a	third argument is passed, otherwise, the value of third
	   argument is set to the quotient.  If	a fourth argument is passed,
	   the value of	the fourth argument is set to the remainder.

       mod
	    my $remainder = $self->mod($bn_b, $ctx);
	    # or
	    $self->mod($bn_b, $ctx, $remainder);

	   This	method returns the remainder obtained by dividing this object
	   by the first	argument, a Crypt::OpenSSL::Bignum::CTX	object,	as a
	   scratchpad. Crypt::OpenSSL::Bignum object is	created	for the	return
	   value. If a third argument is passed, the value of third argument
	   is set to the remainder.

       sqr
	    my $new_bn_object =	$self->sqr($ctx);
	    # new object is created $self is not modified

	   This	method returns the square ("$self ** 2") of
	   Crypt::OpenSSL::Bignum object.

       exp
	    my $new_bn_object =	$self->exp($bn_exp, $ctx);
	    # new object is created $self is not modified

	   This	method returns the product of this object exponentiated	by the
	   first argument (Crypt::OpenSSL::Bignum object), using the second
	   argument, a Crypt::OpenSSL::Bignum::CTX object, as a	scratchpad.

       mod_exp
	    my $new_bn_object =	$self->exp_mod($bn_exp,	$bn_mod, $ctx);
	    # new object is created $self is not modified

	   This	method returns the product of this object exponentiated	by the
	   first argument (Crypt::OpenSSL::Bignum object), modulo the second
	   argument (also Crypt::OpenSSL::Bignum object), using	the third
	   argument, a Crypt::OpenSSL::Bignum::CTX object, as a	scratchpad.

       mod_mul
	    my $new_bn_object =	$self->mod_mul($bn_b, $bn_mod, $ctx);
	    # new object is created $self is not modified

	   This	method returns "($self * $bn_b)	% $bn_mod", using the third
	   argument, a Crypt::OpenSSL::Bignum::CTX object, as a	scratchpad.

       mod_inverse
	    my $new_bn_object =	$self->mod_inverse($bn_n, $ctx);
	    # new object is created $self is not modified

	   Computes the	inverse	of $self modulo	$bn_n and returns the result
	   in a	new Crypt::OpenSSL::Bignum object, using the second argument,
	   a Crypt::OpenSSL::Bignum::CTX object, as a scratchpad.

       gcd
	    my $new_bn_object =	$self->gcd($bn_b, $ctx);
	    # new object is created $self is not modified

	   Computes the	greatest common	divisor	of $self and $bn_b and returns
	   the result in a new Crypt::OpenSSL::Bignum object, using the	second
	   argument, a Crypt::OpenSSL::Bignum::CTX object, as a	scratchpad.

       cmp
	    my $result = $self->cmp($bn_b);
	    #returns:
	    # -1 if self <  bn_b
	    #  0 if self == bn_b
	    #  1 if self >  bn_b

	   Comparison of values	$self and $bn_b	(Crypt::OpenSSL::Bignum
	   objects).

       ucmp
	    my $result = $self->ucmp($bn_b);
	    #returns:
	    # -1 if |self| <  |bn_b|
	    #  0 if |self| == |bn_b|
	    #  1 if |self| >  |bn_b|

	   Comparison using the	absolute values	of $self and $bn_b
	   (Crypt::OpenSSL::Bignum objects).

       equals
	    my $result = $self->equals($bn_b);
	    #returns:
	    # 1	if self	== bn_b
	    # 0	otherwise

       num_bits
	    my $bits = $self->num_bits;

	   Returns the number of significant bits in a word. If	we take
	   0x00000432 as an example, it	returns	11, not	16, not	32. Basically,
	   except for a	zero, it returns "floor(log2(w)) + 1".

       num_bytes
	    my $bytes =	$self->num_bytes;

	   Returns the size of binary represenatation in bytes.

       rshift
	    my $new_bn_object =	$self->rshift($n);
	    # new object is created $self is not modified

	   Shifts a right by $n	(integer) bits and places the result into a
	   newly created Crypt::OpenSSL::Bignum	object.

       lshift
	    my $new_bn_object =	$self->lshift($n);
	    # new object is created $self is not modified

	   Shifts a left by $n (integer) bits and places the result into a
	   newly created Crypt::OpenSSL::Bignum	object.

       swap
	    my $bn_a = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890001");
	    my $bn_b = Crypt::OpenSSL::Bignum->new_from_decimal("1234567890002");

	    $bn_a->swap($bn_b);
	    # or
	    $bn_b->swap($bn_a);

	   Exchanges the values	of two Crypt::OpenSSL::Bignum objects.

       copy
	    my $new_bn_object =	$self->copy;

	   Returns a copy of this object.

       pointer_copy
	    my $cloned_BIGNUM_ptr = $self->pointer_copy($BIGNUM_ptr);

	   This	method is intended only	for use	by XSUB	writers	wanting	to
	   have	access to the underlying BIGNUM	structure referenced by	a
	   Crypt::OpenSSL::Bignum perl object so that they can pass them to
	   other routines in the OpenSSL library.  It returns a	perl scalar
	   whose IV can	be cast	to a BIGNUM* value.  This can then be passed
	   to an XSUB which can	work with the BIGNUM directly.	Note that the
	   BIGNUM object pointed to will be a copy of the BIGNUM object
	   wrapped by the instance; it is thus the responsibility of the
	   client to free space	allocated by this BIGNUM object	if and when it
	   is done with	it. See	also bless_pointer.

AUTHOR
       Ian Robertson, iroberts@cpan.org

SEE ALSO
       <https://www.openssl.org/docs/crypto/bn.html>

perl v5.24.1			  2017-02-08			     Bignum(3)

NAME | SYNOPSIS | DESCRIPTION | Constructors | Instance Methods | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Crypt::OpenSSL::Bignum&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help