summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortailor <cygnus@janrain.com>2005-12-30 19:58:18 +0000
committertailor <cygnus@janrain.com>2005-12-30 19:58:18 +0000
commit977e9dc10d959800341f270587d3fe7adfc9fd68 (patch)
tree43d31a2c7062a43542b931a33058472f31881c25
parent07ece50a42abe82e3a4fdd59fb1c712b1022692b (diff)
downloadphp-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.php190
-rw-r--r--Net/OpenID/DiffieHellman.php6
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);
}