1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Math</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="PHP Secure Communications Library" /><link rel="up" href="index.html" title="PHP Secure Communications Library" /><link rel="prev" href="intro.html" title="Chapter 1. Introduction" /><link rel="next" href="sym_crypt.html" title="Chapter 3. Symmetric-key Cryptography" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Math</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="sym_crypt.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="math"></a>Chapter 2. Math</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="math.html#math_biginteger">2.1. Math_BigInteger</a></span></dt><dd><dl><dt><span class="section"><a href="math.html#math_biginteger_dependencies">2.1.1. Dependencies</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_constructor">2.1.2. The constructor</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_output">2.1.3. toString(), toBytes(), toHex() and toBits()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_fourfunctions">2.1.4. add(), subtract(), multiply() and divide()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_modulo">2.1.5. powMod() and modInverse()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_gcd">2.1.6. gcd() and extendedGCD()</a></span></dt><dt><span class="section"><a href="math.html#math_abs">2.1.7. abs()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_compare">2.1.8. equals() and compare()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_precision">2.1.9. setPrecision()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_bitwise">2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_shifts">2.1.11. bitwise_rightShift() and bitwise_leftShift()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_rotates">2.1.12. bitwise_rightRotate() and bitwise_leftRotate()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_setrandom">2.1.13. setRandomGenerator()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_prime">2.1.14. isPrime()</a></span></dt><dt><span class="section"><a href="math.html#math_biginteger_random">2.1.15. random() and randomPrime()</a></span></dt></dl></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="math_biginteger"></a>2.1. Math_BigInteger</h2></div></div></div><p>
Implements an arbitrary precision integer arithmetic library. Uses gmp or bcmath, if available, and an
internal implementation, otherwise. Here's an example:
</p><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger(2);
$b = new Math_BigInteger(3);
$c = $a->add($b);
echo $c->toString(); // outputs 5
?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_dependencies"></a>2.1.1. Dependencies</h3></div></div></div><p>
If you're running PHP 5, Math_BigInteger's only dependancy is the PCRE extension (which is enabled by default). Math_BigInteger also works on PHP 4 if PHP/Compat/Function/array_fill.php and PHP/Compat/Function/bcpowmod.php are included.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_constructor"></a>2.1.2. The constructor</h3></div></div></div><p>
The constructor takes two parameters. The first is the number and the second represents the base. Both
are optional (if they're not provided, the Math_BigInteger object will assume a value of 0).
</p><p>
The supported bases are base-2, base-10 (default), base-16, and base-256. To set $a, in the
above example, to 2, using base-2, we'd do <code class="code">new Math_BigInteger('10', 2)</code>. To do it using
base-16, you could do <code class="code">new Math_BigInteger('2', 16)</code> or <code class="code">new Math_BigInteger('0x2', 16)</code>.
To set it to 2 using base-256, you'd do <code class="code">new Math_BigInteger(chr(2), 256)</code>.
</p><p>
If the base is negative (eg. -256), two's compliment will be used. Thus, <code class="code">new Math_BigInteger(chr(0xFF), -256)</code>
is equal to -1, as is <code class="code">new Math_BigInteger('0xFFFFFFFF', -16)</code> and <code class="code">new Math_BigInteger('11', -2)</code>.
Basically, if the leading bit is 1, the number is assumed to be negative.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_output"></a>2.1.3. toString(), toBytes(), toHex() and toBits()</h3></div></div></div><p>
<code class="code">toString()</code> returns the base-10 form of a number. <code class="code">toBytes()</code> returns the base-256
form of a number, <code class="code">toHex()</code> returns the base-16 form, and <code class="code">toBits()</code> the base-2 form.
<code class="code">toBytes()</code>, <code class="code">toHex()</code>, and <code class="code">toBits()</code> also take an optional parameter which,
if set, will return the two's compliment of a number. So if, for example, $a is equal to -1,
<code class="code">toBytes(true)</code> will return <code class="code">chr(0xFF)</code>.
</p><p>
On PHP 5, <code class="code">toString()</code> is called automatically when used in a string context via the
<a class="ulink" href="http://php.net/language.oop5.magic#language.oop5.magic.tostring" target="_top">__toString() magic method</a>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_fourfunctions"></a>2.1.4. add(), subtract(), multiply() and divide()</h3></div></div></div><p>
<code class="code">subtract()</code> and <code class="code">multiply()</code> operate similarly to <code class="code">add()</code>. <code class="code">divide()</code>,
however, does not. Namely, it 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:
</p><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger('10');
$b = new Math_BigInteger('20');
list($quotient, $remainder) = $a->divide($b);
echo $quotient->toString(); // outputs 0
echo "\r\n";
echo $remainder->toString(); // outputs 10
?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_modulo"></a>2.1.5. powMod() and modInverse()</h3></div></div></div><p>
Examples of each follow:
</p><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger('10');
$b = new Math_BigInteger('20');
$c = new Math_BigInteger('30');
$c = $a->powMod($b, $c);
echo $c->toString(); // outputs 10
?></pre><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger(30);
$b = new Math_BigInteger(17);
$c = $a->modInverse($b);
echo $c->toString(); // outputs 4
?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_gcd"></a>2.1.6. gcd() and extendedGCD()</h3></div></div></div><p>
<code class="code">extendedGCD()</code> returns an array containing three Math_BigInteger values indexed with x, y,
and gcd. x and y represent Bézout's identity. <code class="code">gcd()</code> returns a Math_BigInteger value
equal to the gcd. An example of each follows:
</p><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger(693);
$b = new Math_BigInteger(609);
extract($a->extendedGCD($b));
$c = $a->gcd($b);
echo $gcd->toString() . "\r\n"; // outputs 21
echo $c->toString() . "\r\n"; // outputs 21
echo $a->toString() * $x->toString() + $b->toString() * $y->toString(); // outputs 21
?></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_abs"></a>2.1.7. abs()</h3></div></div></div><p>
<code class="code">$x->abs()</code> returns the absolute value of <code class="code">$x</code>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_compare"></a>2.1.8. equals() and compare()</h3></div></div></div><p>
<code class="code">$x->equals($y)</code> returns true or false depending on whether or not <code class="code">$x</code> and
<code class="code">$y</code> are equal.
</p><p>
<code class="code">$x->compare($y)</code> returns 1 if $x > $y, 0 if $x == $y, and -1 if $x < $y. The reason for this
is demonstrated thusly:
</p><pre class="programlisting">$x > $y: $x->compare($y) > 0
$x < $y: $x->compare($y) < 0
$x == $y: $x->compare($y) == 0
$x >= $y: $x->compare($y) >= 0
$x <= $y: $x->compare($y) <= 0</pre><p>
As a consequence of this, <code class="code">!$x->compare($y)</code> does not mean <code class="code">$x != $y</code> but rather
<code class="code">$x == $y</code>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_precision"></a>2.1.9. setPrecision()</h3></div></div></div><p>
Some bitwise operations give different results depending on the precision being used. Examples include
left shift, not, and rotates, as discussed for <a class="link" href="math.html#math_biginteger_bitwise" title="2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()">bitwise_not()</a>.
This function lets you control the precision.
</p><p>
Whenever a new Math_BigInteger object is created it's precision is set to the same precision as the
calling object. In other words, if you do <code class="code">$b = $a->bitwise_not()</code> then <code class="code">$b</code> will
have the same precision as <code class="code">$a</code>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_bitwise"></a>2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()</h3></div></div></div><p>
<code class="code">bitwise_and()</code>, <code class="code">bitwise_or()</code> and <code class="code">bitwise_xor()</code> operate similar to
<code class="code">add()</code>. <code class="code">bitwise_not()</code> is a bit more complicated. To elaborate, if the
precision (see <a class="link" href="math.html#math_biginteger_precision" title="2.1.9. setPrecision()">setPrecision</a>) is arbitrary,
<code class="code">$x->bitwise_not()</code> will always yield a smaller value since the most significant bit is
assumed to have a value of one. With fixed precision, however, the leading bit can be anything.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_shifts"></a>2.1.11. bitwise_rightShift() and bitwise_leftShift()</h3></div></div></div><p>
<code class="code">$a->bitwise_rightShift($shift)</code> shifts $a by $shift bits, effectively dividing by 2**$shift.
<code class="code">$a->bitwise_leftShift($shift)</code> shifts $a by $shift bits, effectively multiplying by 2**$shift.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_rotates"></a>2.1.12. bitwise_rightRotate() and bitwise_leftRotate()</h3></div></div></div><p>
<code class="code">$a->bitwise_rightRotate($shift)</code> and <code class="code">$a->bitwise_leftRotate($shift)</code> are
demonstrated thusly:
</p><pre class="programlisting"><?php
include('Math/BigInteger.php');
$a = new Math_BigInteger('00111000', 2);
$a->setPrecision(8);
$b = $a->bitwise_leftRotate(2);
echo $b->toBits(); // returns 11100000
echo "\r\n";
$a = new Math_BigInteger('00111000', 2);
$b = $a->bitwise_leftRotate(2);
echo $b->toBits(); // returns 100011
?></pre><p>
Just as with <a class="link" href="math.html#math_biginteger_bitwise" title="2.1.10. bitwise_and(), bitwise_or(), bitwise_xor() and bitwise_not()">bitwise_not()</a>, these operations are
precision dependant.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_setrandom"></a>2.1.13. setRandomGenerator()</h3></div></div></div><p>
Sets the random generator. To set it to <code class="code">mt_rand()</code> (which is what it is by default), call
<code class="code">$x->setRandomGenerator('mt_rand')</code>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_prime"></a>2.1.14. isPrime()</h3></div></div></div><p>
Returns true if a number is prime and false if it isn't.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="math_biginteger_random"></a>2.1.15. random() and randomPrime()</h3></div></div></div><p>
<code class="code">random($min, $max)</code> generates a random number between <code class="code">$min</code> and <code class="code">$max</code>.
<code class="code">randomPrime($min, $max)</code> generates a random prime number between <code class="code">$min</code> and <code class="code">$max</code>.
If no prime number exists between <code class="code">$min</code> and <code class="code">$max</code> false is returned.
</p><p>
<code class="code">randomPrime()</code> has an optional third parameter, as well - $timeout. Generating prime numbers
is a particurarly expensive operation and although in certain environments even 512-bit primes can be
generated in a less than a second it can take other environments upwards of around a minute if not more.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="sym_crypt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Symmetric-key Cryptography</td></tr></table></div></body></html>
|
