diff options
author | tailor <cygnus@janrain.com> | 2005-12-30 19:58:18 +0000 |
---|---|---|
committer | tailor <cygnus@janrain.com> | 2005-12-30 19:58:18 +0000 |
commit | 977e9dc10d959800341f270587d3fe7adfc9fd68 (patch) | |
tree | 43d31a2c7062a43542b931a33058472f31881c25 | |
parent | 07ece50a42abe82e3a4fdd59fb1c712b1022692b (diff) | |
download | php-openid-977e9dc10d959800341f270587d3fe7adfc9fd68.zip php-openid-977e9dc10d959800341f270587d3fe7adfc9fd68.tar.gz php-openid-977e9dc10d959800341f270587d3fe7adfc9fd68.tar.bz2 |
[project @ Added a ton of documentation updates]
-rw-r--r-- | Net/OpenID/CryptUtil.php | 190 | ||||
-rw-r--r-- | Net/OpenID/DiffieHellman.php | 6 |
2 files changed, 186 insertions, 10 deletions
diff --git a/Net/OpenID/CryptUtil.php b/Net/OpenID/CryptUtil.php index c14839f..7f4d6de 100644 --- a/Net/OpenID/CryptUtil.php +++ b/Net/OpenID/CryptUtil.php @@ -31,6 +31,7 @@ if (!defined('Net_OpenID_RAND_SOURCE')) { * Net_OpenID_CryptUtil houses static utility functions. * * @package OpenID + * @static */ class Net_OpenID_CryptUtil { /** @@ -43,7 +44,6 @@ class Net_OpenID_CryptUtil { * <code>Net_OpenID_USE_INSECURE_RAND</code>, and the code will * fall back on a pseudo-random number generator. * - * @static * @param int $num_bytes The length of the return value * @return string $bytes random bytes */ @@ -68,6 +68,12 @@ class Net_OpenID_CryptUtil { return $bytes; } + /** + * Computes the maximum integer value for this PHP installation. + * + * @return int $max_int_value The maximum integer value for this + * PHP installation + */ function maxint() { /** * quick-and-dirty function for PHP int size -- assumes @@ -87,7 +93,6 @@ class Net_OpenID_CryptUtil { * Computes the SHA1 hash. * * @param string $str The input string. - * @static * @return string The resulting SHA1 hash. */ function sha1($str) { @@ -96,19 +101,44 @@ class Net_OpenID_CryptUtil { /** * Computes an HMAC-SHA1 digest. + * + * @param string $key The key used to generate the HMAC-SHA1 digest + * @param string $text The text to be hashed + * @return string $digest The raw HMAC-SHA1 digest */ function hmacSha1($key, $text) { return Net_OpenID_HMACSHA1($key, $text); } + /** + * Converts a base64-encoded string to its raw binary equivalent. + * + * @param string $str The base64-encoded string to decode + * @return string $raw The decoded binary data + */ function fromBase64($str) { return base64_decode($str); } + /** + * Converts a raw binary string to its base64-encoded equivalent. + * + * @param string $str The raw binary data to encode + * @return string $raw The base64-encoded version of $str + */ function toBase64($str) { return base64_encode($str); } + /** + * Given a long integer, returns the number converted to a binary + * string. + * + * @param integer $long The long number (can be a normal PHP + * integer or a number created by one of the available long number + * libraries) + * @return string $binary The binary version of $long + */ function longToBinary($long) { $lib =& Net_OpenID_MathLibrary::getLibWrapper(); @@ -141,6 +171,13 @@ class Net_OpenID_CryptUtil { return $string; } + /** + * Given a binary string, returns the binary string converted to a long number. + * + * @param string $binary The binary version of a long number, + * probably as a result of calling longToBinary + * @return integer $long The long number equivalent of the binary string $str + */ function binaryToLong($str) { $lib =& Net_OpenID_MathLibrary::getLibWrapper(); @@ -168,14 +205,35 @@ class Net_OpenID_CryptUtil { return $n; } + /** + * Converts a base64-encoded string to a long number. + * + * @param string $str A base64-encoded string + * @return integer $long A long number + */ function base64ToLong($str) { return Net_OpenID_CryptUtil::binaryToLong(Net_OpenID_CryptUtil::fromBase64($str)); } + /** + * Converts a long number to its base64-encoded representation. + * + * @param integer $long The long number to be converted + * @return string $str The base64-encoded version of $long + */ function longToBase64($long) { return Net_OpenID_CryptUtil::toBase64(Net_OpenID_CryptUtil::longToBinary($long)); } + /** + * Given two strings of equal length, computes the exclusive-OR of + * the two strings' ordinal values and returns the resulting + * string. + * + * @param string $x A string + * @param string $y A string + * @return string $result The result of $x XOR $y + */ function strxor($x, $y) { if (strlen($x) != strlen($y)) { return null; @@ -189,6 +247,12 @@ class Net_OpenID_CryptUtil { return $str; } + /** + * Reverses a string or array. + * + * @param mixed $list A string or an array + * @return mixed $result The reversed string or array + */ function reversed($list) { if (is_string($list)) { return strrev($list); @@ -199,6 +263,15 @@ class Net_OpenID_CryptUtil { } } + /** + * Returns a random number in the specified range. + * + * @param integer $start The start of the range, or the minimum random number to return + * @param integer $stop The end of the range, or the maximum random number to return + * @param integer $step The step size, such that $result - ($step + * * N) = $start for some N + * @return integer $result The resulting randomly-generated number + */ function randrange($start, $stop = null, $step = 1) { static $Net_OpenID_CryptUtil_duplicate_cache = array(); @@ -246,7 +319,12 @@ class Net_OpenID_CryptUtil { } /** - * Produce a string of length random bytes, chosen from chrs. + * Produce a string of length random bytes, chosen from chrs. If + * $chrs is null, the resulting string may contain any characters. + * + * @param integer $length The length of the resulting randomly-generated string + * @param string $chrs A string of characters from which to choose to build the new string + * @return string $result A string of randomly-chosen characters from $chrs */ function randomString($length, $chrs = null) { if ($chrs == null) { @@ -263,26 +341,54 @@ class Net_OpenID_CryptUtil { } /** + * Exposes math library functionality. + * * Net_OpenID_MathWrapper is a base class that defines the interface - * to whatever large number math library is available, if any. + * to a math library like GMP or BCmath. This library will attempt to + * use an available long number implementation. If a library like GMP + * is found, the appropriate Net_OpenID_MathWrapper subclass will be + * instantiated and used for mathematics operations on large numbers. + * This base class wraps only native PHP functionality. See + * Net_OpenID_MathWrapper subclasses for access to particular long + * number implementations. * * @package OpenID */ class Net_OpenID_MathWrapper { + /** + * The type of the Net_OpenID_MathWrapper class. This value + * describes the library or module being wrapped. Users of + * Net_OpenID_MathWrapper instances should check this value if + * they care about the type of math functionality being exposed. + * + * @type string + */ var $type = 'dumb'; + /** + * Returns a random number in the specified range. + */ function random($min, $max) { return mt_rand($min, $max); } + /** + * Returns $base raised to the $exponent power. + */ function pow($base, $exponent) { return pow($base, $exponent); } + /** + * Returns the sum of $x and $y. + */ function add($x, $y) { return $x + $y; } + /** + * Returns -1 if $x < $y, 0 if $x == $y, and 1 if $x > $y. + */ function cmp($x, $y) { if ($x > $y) { return 1; @@ -293,26 +399,49 @@ class Net_OpenID_MathWrapper { } } + /** + * "Initializes" a new number. This may simply return the + * specified number or it may call a library function for this + * purpose. The base may be ignored depending on the + * implementation. + */ function init($number, $base = 10) { return $number; } + /** + * Returns the result of $base mod $modulus. + */ function mod($base, $modulus) { return $base % $modulus; } + /** + * Returns the product of $x and $y. + */ function mul($x, $y) { return $x * $y; } + /** + * Returns the difference of $x and $y. + */ function sub($x, $y) { return $x - $y; } + /** + * Returns $x / $y. + */ function div($x, $y) { return $x / $y; } + /** + * Returns ($base to the $exponent power) mod $modulus. In some + * long number implementations, this may be optimized. This + * placeholder implementation performs it manually. + */ function powmod($base, $exponent, $modulus) { $square = $this->mod($base, $modulus); $result = '1'; @@ -328,6 +457,8 @@ class Net_OpenID_MathWrapper { } /** + * Exposes BCmath math library functionality. + * * Net_OpenID_BcMathWrapper implements the Net_OpenID_MathWrapper * interface and wraps the functionality provided by the BCMath * library. @@ -375,6 +506,8 @@ class Net_OpenID_BcMathWrapper extends Net_OpenID_MathWrapper { } /** + * Exposes GMP math library functionality. + * * Net_OpenID_GmpMathWrapper implements the Net_OpenID_MathWrapper * interface and wraps the functionality provided by the GMP library. * @@ -427,35 +560,70 @@ class Net_OpenID_GmpMathWrapper extends Net_OpenID_MathWrapper { $Net_OpenID___mathLibrary = null; /** - * Net_OpenID_MathLibrary checks for the presence of a module in - * Net_OpenID_supported_extensions and supplies an instance of a - * wrapper for that extension module. + * Net_OpenID_MathLibrary checks for the presence of long number + * extension modules and returns an instance of Net_OpenID_MathWrapper + * which exposes the module's functionality. * + * @static * @package OpenID */ class Net_OpenID_MathLibrary { + /** + * A method to access an available long number implementation. + * + * Checks for the existence of an extension module described by + * the local Net_OpenID_supported_extensions array and returns an + * instance of a wrapper for that extension module. If no + * extension module is found, an instance of + * Net_OpenID_MathWrapper is returned, which wraps the native PHP + * integer implementation. The proper calling convention for this + * method is $lib =& Net_OpenID_MathLibrary::getLibWrapper(). + * + * This function checks for the existence of specific long number + * implementations in the following order: GMP followed by BCmath. + * + * @return Net_OpenID_MathWrapper $instance An instance of + * Net_OpenID_MathWrapper or one of its subclasses + */ function &getLibWrapper() { + // Define the supported extensions. An extension array has + // keys 'modules', 'extension', and 'class'. 'modules' is an + // array of PHP module names which the loading code will + // attempt to load. These values will be suffixed with a + // library file extension (e.g. ".so"). 'extension' is the + // name of a PHP extension which will be tested before + // 'modules' are loaded. 'class' is the string name of a + // Net_OpenID_MathWrapper subclass which should be + // instantiated if a given extension is present. $Net_OpenID_supported_extensions = array( array('modules' => array('gmp', 'php_gmp'), 'extension' => 'gmp', 'class' => 'Net_OpenID_GmpMathWrapper'), array('modules' => array('bcmath', 'php_bcmath'), - 'extension' => 'bcmath', + 'extension' => 'bcmath', 'class' => 'Net_OpenID_BcMathWrapper') ); + // The instance of Net_OpenID_MathWrapper that we choose to + // supply will be stored here, so that subseqent calls to this + // method will return a reference to the same object. global $Net_OpenID___mathLibrary; + // If this method has not been called before, look at + // $Net_OpenID_supported_extensions and try to find an + // extension that works. if (!$Net_OpenID___mathLibrary) { $loaded = false; foreach ($Net_OpenID_supported_extensions as $extension) { + // See if the extension specified is already loaded. if ($extension['extension'] && extension_loaded($extension['extension'])) { $loaded = true; } + // Try to load dynamic modules. if (!$loaded) { foreach ($extension['modules'] as $module) { if (@dl($module . "." . PHP_SHLIB_SUFFIX)) { @@ -465,6 +633,9 @@ class Net_OpenID_MathLibrary { } } + // If the load succeeded, supply an instance of + // Net_OpenID_MathWrapper which wraps the specified + // module's functionality. if ($loaded) { $classname = $extension['class']; $Net_OpenID___mathLibrary =& new $classname(); @@ -472,6 +643,9 @@ class Net_OpenID_MathLibrary { } } + // If no extensions were found, fall back to + // Net_OpenID_MathWrapper so at least some platform-size + // math can be performed. if (!$Net_OpenID___mathLibrary) { $Net_OpenID___mathLibrary =& new Net_OpenID_MathWrapper(); } diff --git a/Net/OpenID/DiffieHellman.php b/Net/OpenID/DiffieHellman.php index 97ca6c7..7e3b125 100644 --- a/Net/OpenID/DiffieHellman.php +++ b/Net/OpenID/DiffieHellman.php @@ -14,7 +14,7 @@ */ /** - * Require CryptUtil because we need to get a math library wrapper + * Require CryptUtil because we need to get a Net_OpenID_MathWrapper * object. */ require_once('CryptUtil.php'); @@ -40,7 +40,9 @@ class Net_OpenID_DiffieHellman { $this->lib =& Net_OpenID_MathLibrary::getLibWrapper(); if (!$this->lib) { - // This should NEVER occur, but if there's a bug in + // This should NEVER occur because even if no math + // extensions can be found, we should get an instance of + // Net_OpenID_MathWrapper, but if there's a bug in // Net_OpenID_MathLibrary::getLibWrapper, it might. trigger_error("Big integer fallback implementation unavailable.", E_USER_ERROR); } |