phpseclib API Documentation
Class

phpseclib\Math\BigInteger

class BigInteger

Pure-PHP arbitrary precision integer arithmetic library.

Supports base-2, base-10, base-16, and base-256 numbers.

Constants

MONTGOMERY

BARRETT

POWEROF2

CLASSIC

NONE

VALUE

$result[self::VALUE] contains the value.

SIGN

$result[self::SIGN] contains the sign.

VARIABLE

Cache constants

$cache[self::VARIABLE] tells us whether or not the cached data is still valid.

DATA

$cache[self::DATA] contains the cached data.

MODE_INTERNAL

To use the pure-PHP implementation

MODE_BCMATH

To use the BCMath library

(if enabled; otherwise, the internal implementation will be used)

MODE_GMP

To use the GMP library

(if present; otherwise, either the BCMath or the internal implementation will be used)

KARATSUBA_CUTOFF

Karatsuba Cutoff

At what point do we switch between Karatsuba multiplication and schoolbook long multiplication?

Properties

array $value Holds the BigInteger's value.
bool $is_negative Holds the BigInteger's magnitude.
$precision Precision
$bitmask Precision Bitmask
string $hex Mode independent value used for serialization.

Methods

BigInteger __construct($x $x, int $base = 10)

Converts base-2, base-10, base-16, and binary strings (base-256) to BigIntegers.

string toBytes(bool $twos_compliment = false)

Converts a BigInteger to a byte string (eg.

string toHex(bool $twos_compliment = false)

Converts a BigInteger to a hex string (eg.

string toBits(bool $twos_compliment = false)

Converts a BigInteger to a bit string (eg.

string toString()

Converts a BigInteger to a base-10 number.

__toString()

__toString() magic method

__sleep()

__sleep() magic method

__wakeup()

__wakeup() magic method

__debugInfo()

__debugInfo() magic method

BigInteger add(BigInteger $y)

Adds two BigIntegers.

BigInteger subtract(BigInteger $y)

Subtracts two BigIntegers.

BigInteger multiply(BigInteger $x)

Multiplies two BigIntegers

array divide(BigInteger $y)

Divides two BigIntegers.

BigInteger modPow(BigInteger $e, BigInteger $n)

Performs modular exponentiation.

BigInteger powMod(BigInteger $e, BigInteger $n)

Performs modular exponentiation.

BigInteger _slidingWindow(BigInteger $e, BigInteger $n, int $mode)

Sliding Window k-ary Modular Exponentiation

BigInteger _mod2(BigInteger $n)

Modulos for Powers of Two

int _modInverse67108864(array $x)

Modular Inverse of a number mod 2**26 (eg.

BigInteger|false modInverse(BigInteger $n)

Calculates modular inverses.

BigInteger extendedGCD(BigInteger $n)

Calculates the greatest common divisor and Bezout's identity.

BigInteger gcd(BigInteger $n)

Calculates the greatest common divisor

BigInteger abs()

Absolute value.

int compare(BigInteger $y)

Compares two numbers.

bool equals(BigInteger $x)

Tests the equality of two numbers.

setPrecision(int $bits)

Set Precision

int getPrecision()

Get Precision

BigInteger bitwise_and(BigInteger $x)

Logical And

BigInteger bitwise_or(BigInteger $x)

Logical Or

BigInteger bitwise_xor(BigInteger $x)

Logical Exclusive-Or

BigInteger bitwise_not()

Logical Not

BigInteger bitwise_rightShift(int $shift)

Logical Right Shift

BigInteger bitwise_leftShift(int $shift)

Logical Left Shift

BigInteger bitwise_leftRotate(int $shift)

Logical Left Rotate

BigInteger bitwise_rightRotate(int $shift)

Logical Right Rotate

_make_odd()

Make the current number odd

bool isPrime(BigInteger $t = false)

Checks a numer to see if it's prime

_lshift(int $shift)

Logical Left Shift

_rshift(int $shift)

Logical Right Shift

BigInteger _normalize(BigInteger $result)

Normalize

Details

at line 252
public BigInteger __construct($x $x, int $base = 10)

Converts base-2, base-10, base-16, and binary strings (base-256) to BigIntegers.

If the second parameter - $base - is negative, then it will be assumed that the number's are encoded using two's compliment. The sole exception to this is -10, which is treated the same as 10 is.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('0x32', 16); // 50 in base-16

echo $a->toString(); // outputs 50 ?>

Parameters

$x $x base-10 number or base-$base number if $base set.
int $base

Return Value

BigInteger

at line 522
public string toBytes(bool $twos_compliment = false)

Converts a BigInteger to a byte string (eg.

base-256).

Negative numbers are saved as positive numbers, unless $twos_compliment is set to true, at which point, they're saved as two's compliment.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('65');

echo $a->toBytes(); // outputs chr(65) ?>

Parameters

bool $twos_compliment

Return Value

string

at line 615
public string toHex(bool $twos_compliment = false)

Converts a BigInteger to a hex string (eg.

base-16)).

Negative numbers are saved as positive numbers, unless $twos_compliment is set to true, at which point, they're saved as two's compliment.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('65');

echo $a->toHex(); // outputs '41' ?>

Parameters

bool $twos_compliment

Return Value

string

at line 640
public string toBits(bool $twos_compliment = false)

Converts a BigInteger to a bit string (eg.

base-2).

Negative numbers are saved as positive numbers, unless $twos_compliment is set to true, at which point, they're saved as two's compliment.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('65');

echo $a->toBits(); // outputs '1000001' ?>

Parameters

bool $twos_compliment

Return Value

string

at line 675
public string toString()

Converts a BigInteger to a base-10 number.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('50');

echo $a->toString(); // outputs 50 ?>

Return Value

string

at line 723
public __toString()

__toString() magic method

Will be called, automatically, if you're supporting just PHP5. If you're supporting PHP4, you'll need to call toString().

at line 736
public __sleep()

__sleep() magic method

Will be called, automatically, when serialize() is called on a BigInteger object.

See also

self::__wakeup()

at line 754
public __wakeup()

__wakeup() magic method

Will be called, automatically, when unserialize() is called on a BigInteger object.

See also

self::__sleep()

at line 772
public __debugInfo()

__debugInfo() magic method

Will be called, automatically, when printr() or vardump() are called

at line 818
public BigInteger add(BigInteger $y)

Adds two BigIntegers.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('10'); $b = new \phpseclib\Math\BigInteger('20');

$c = $a->add($b);

echo $c->toString(); // outputs 30 ?>

Parameters

BigInteger $y

Return Value

BigInteger

at line 947
public BigInteger subtract(BigInteger $y)

Subtracts two BigIntegers.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('10'); $b = new \phpseclib\Math\BigInteger('20');

$c = $a->subtract($b);

echo $c->toString(); // outputs -10 ?>

Parameters

BigInteger $y

Return Value

BigInteger

at line 1080
public BigInteger multiply(BigInteger $x)

Multiplies two BigIntegers

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('10'); $b = new \phpseclib\Math\BigInteger('20');

$c = $a->multiply($b);

echo $c->toString(); // outputs 200 ?>

Parameters

BigInteger $x

Return Value

BigInteger

at line 1365
public array divide(BigInteger $y)

Divides two BigIntegers.

Returns an array whose first element contains the quotient and whose second element contains the "common residue". If the remainder would be positive, the "common residue" and the remainder are the same. If the remainder would be negative, the "common residue" is equal to the sum of the remainder and the divisor (basically, the "common residue" is the first positive modulo).

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('10'); $b = new \phpseclib\Math\BigInteger('20');

list($quotient, $remainder) = $a->divide($b);

echo $quotient->toString(); // outputs 0 echo "\r\n"; echo $remainder->toString(); // outputs 10 ?>

Parameters

BigInteger $y

Return Value

array

at line 1600
public BigInteger modPow(BigInteger $e, BigInteger $n)

Performs modular exponentiation.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger('10'); $b = new \phpseclib\Math\BigInteger('20'); $c = new \phpseclib\Math\BigInteger('30');

$c = $a->modPow($b, $c);

echo $c->toString(); // outputs 10 ?>

Parameters

BigInteger $e
BigInteger $n

Return Value

BigInteger

at line 1751
public BigInteger powMod(BigInteger $e, BigInteger $n)

Performs modular exponentiation.

Alias for modPow().

Parameters

BigInteger $e
BigInteger $n

Return Value

BigInteger

at line 1770
public BigInteger _slidingWindow(BigInteger $e, BigInteger $n, int $mode)

Sliding Window k-ary Modular Exponentiation

Based on {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=27 HAC 14.85} / {@link http://math.libtomcrypt.com/files/tommath.pdf#page=210 MPM 7.7}. In a departure from those algorithims, however, this function performs a modular reduction after every multiplication and squaring operation. As such, this function has the same preconditions that the reductions being used do.

Parameters

BigInteger $e
BigInteger $n
int $mode

Return Value

BigInteger

at line 1941
public BigInteger _mod2(BigInteger $n)

Modulos for Powers of Two

Calculates $x%$n, where $n = 2**$e, for some $e. Since this is basically the same as doing $x & ($n-1), we'll just use this function as a wrapper for doing that.

Parameters

BigInteger $n

Return Value

BigInteger

See also

self::_slidingWindow()

at line 2358
public int _modInverse67108864(array $x)

Modular Inverse of a number mod 2**26 (eg.

67108864)

Based off of the bnpInvDigit function implemented and justified in the following URL:

{@link http://www-cs-students.stanford.edu/~tjw/jsbn/jsbn.js}

The following URL provides more info:

{@link http://groups.google.com/group/sci.crypt/msg/7a137205c1be7d85}

As for why we do all the bitmasking... strange things can happen when converting from floats to ints. For instance, on some computers, var_dump((int) -4294967297) yields int(-1) and on others, it yields int(-2147483648). To avoid problems stemming from this, we use bitmasks to guarantee that ints aren't auto-converted to floats. The outermost bitmask is present because without it, there's no guarantee that the "residue" returned would be the so-called "common residue". We use fmod, in the last step, because the maximum possible $x is 26 bits and the maximum $result is 16 bits. Thus, we have to be able to handle up to 40 bits, which only 64-bit floating points will support.

Thanks to Pedro Gimeno Fortea for input!

Parameters

array $x

Return Value

int

See also

self::_montgomery()

at line 2396
public BigInteger|false modInverse(BigInteger $n)

Calculates modular inverses.

Say you have (30 mod 17 * x mod 17) mod 17 == 1. x can be found using modular inverses.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger(30); $b = new \phpseclib\Math\BigInteger(17);

$c = $a->modInverse($b); echo $c->toString(); // outputs 4

echo "\r\n";

$d = $a->multiply($c); list(, $d) = $d->divide($b); echo $d; // outputs 1 (as per the definition of modular inverse) ?>

Parameters

BigInteger $n

Return Value

BigInteger|false

at line 2460
public BigInteger extendedGCD(BigInteger $n)

Calculates the greatest common divisor and Bezout's identity.

Say you have 693 and 609. The GCD is 21. Bezout's identity states that there exist integers x and y such that 693x + 609y == 21. In point of fact, there are actually an infinite number of x and y combinations and which combination is returned is dependant upon which mode is in use. See {@link http://en.wikipedia.org/wiki/B%C3%A9zout%27s_identity Bezout's identity - Wikipedia} for more information.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger(693); $b = new \phpseclib\Math\BigInteger(609);

extract($a->extendedGCD($b));

echo $gcd->toString() . "\r\n"; // outputs 21 echo $a->toString() * $x->toString() + $b->toString() * $y->toString(); // outputs 21 ?>

Parameters

BigInteger $n

Return Value

BigInteger

at line 2589
public BigInteger gcd(BigInteger $n)

Calculates the greatest common divisor

Say you have 693 and 609. The GCD is 21.

Here's an example: <?php $a = new \phpseclib\Math\BigInteger(693); $b = new \phpseclib\Math\BigInteger(609);

$gcd = a->extendedGCD($b);

echo $gcd->toString() . "\r\n"; // outputs 21 ?>

Parameters

BigInteger $n

Return Value

BigInteger

at line 2601
public BigInteger abs()

Absolute value.

Return Value

BigInteger

at line 2637
public int compare(BigInteger $y)

Compares two numbers.

Although one might think !$x->compare($y) means $x != $y, it, in fact, means the opposite. The reason for this is demonstrated thusly:

$x > $y: $x->compare($y) > 0 $x < $y: $x->compare($y) < 0 $x == $y: $x->compare($y) == 0

Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).

Parameters

BigInteger $y

Return Value

int < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.

See also

self::equals()

at line 2695
public bool equals(BigInteger $x)

Tests the equality of two numbers.

If you need to see if one number is greater than or less than another number, use BigInteger::compare()

Parameters

BigInteger $x

Return Value

bool

See also

self::compare()

at line 2714
public setPrecision(int $bits)

Set Precision

Some bitwise operations give different results depending on the precision being used. Examples include left shift, not, and rotates.

Parameters

int $bits

at line 2740
public int getPrecision()

Get Precision

Return Value

int

See also

self::setPrecision()

at line 2753
public BigInteger bitwise_and(BigInteger $x)

Logical And

Parameters

BigInteger $x

Return Value

BigInteger

at line 2794
public BigInteger bitwise_or(BigInteger $x)

Logical Or

Parameters

BigInteger $x

Return Value

BigInteger

at line 2834
public BigInteger bitwise_xor(BigInteger $x)

Logical Exclusive-Or

Parameters

BigInteger $x

Return Value

BigInteger

at line 2873
public BigInteger bitwise_not()

Logical Not

Return Value

BigInteger

at line 2916
public BigInteger bitwise_rightShift(int $shift)

Logical Right Shift

Shifts BigInteger's by $shift bits, effectively dividing by 2**$shift.

Parameters

int $shift

Return Value

BigInteger

at line 2954
public BigInteger bitwise_leftShift(int $shift)

Logical Left Shift

Shifts BigInteger's by $shift bits, effectively multiplying by 2**$shift.

Parameters

int $shift

Return Value

BigInteger

at line 2991
public BigInteger bitwise_leftRotate(int $shift)

Logical Left Rotate

Instead of the top x bits being dropped they're appended to the shifted bit string.

Parameters

int $shift

Return Value

BigInteger

at line 3036
public BigInteger bitwise_rightRotate(int $shift)

Logical Right Rotate

Instead of the bottom x bits being dropped they're prepended to the shifted bit string.

Parameters

int $shift

Return Value

BigInteger

at line 3242
public _make_odd()

Make the current number odd

If the current number is odd it'll be unchanged. If it's even, one will be added to it.

See also

self::randomPrime()

at line 3272
public bool isPrime(BigInteger $t = false)

Checks a numer to see if it's prime

Assuming the $t parameter is not set, this function has an error rate of 2**-80. The main motivation for the $t parameter is distributability. BigInteger::randomPrime() can be distributed across multiple pageloads on a website instead of just one.

Parameters

BigInteger $t

Return Value

bool

at line 3421
public _lshift(int $shift)

Logical Left Shift

Shifts BigInteger's by $shift bits.

Parameters

int $shift

at line 3456
public _rshift(int $shift)

Logical Right Shift

Shifts BigInteger's by $shift bits.

Parameters

int $shift

at line 3492
public BigInteger _normalize(BigInteger $result)

Normalize

Removes leading zeros and truncates (if necessary) to maintain the appropriate precision

Parameters

BigInteger $result

Return Value

BigInteger

See also

self::_trim()