diff options
Diffstat (limited to 'phpsec/math.html')
| -rw-r--r-- | phpsec/math.html | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/phpsec/math.html b/phpsec/math.html deleted file mode 100644 index 4e5a14a54..000000000 --- a/phpsec/math.html +++ /dev/null @@ -1,157 +0,0 @@ -<?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> |