cvs: pear /Net_LDAP LDAP.php /Net_LDAP/LDAP Entry.php Filter.php Search.php Util.php

beni Mon Feb 26 08:07:54 2007 UTC Modified files: /pear/Net_LDAP LDAP.php /pear/Net_LDAP/LDAP Entry.php Filter.php Search.php Util.php Log: * Some comments updated * Removed UTF8 en-/decoding stuff from Net_LDAP_Utils class since this was moved to Net_LDAP class in 0.6.6 * Moved Filter encoding from Net_LDAP_Filter to Net_LDAP_Util * Moved ldap_explode_dn_escaped() from Net_LDAP_Entry to Net_LDAP_Util * Added perls functions from Net_LDAP::Util to our Util class, but they need implementation

http://cvs.php.net/viewvc.cgi/pear/Net_LDAP/LDAP.php?r1=1.40&r2=1.41&diff_format=u Index: pear/Net_LDAP/LDAP.php diff -u pear/Net_LDAP/LDAP.php:1.40 pear/Net_LDAP/LDAP.php:1.41 --- pear/Net_LDAP/LDAP.php:1.40 Fri Feb 23 11:10:30 2007 +++ pear/Net_LDAP/LDAP.php Mon Feb 26 08:07:54 2007 @@ -15,7 +15,7 @@ * @author Benedikt Hallinger <beni@php.net> * @copyright 2003-2007 Tarjej Huse, Jan Wagner, Del Elson, Benedikt Hallinger * @license http://www.gnu.org/copyleft/lesser.html - * @version CVS: $Id: LDAP.php,v 1.40 2007/02/23 11:10:30 beni Exp $ + * @version CVS: $Id: LDAP.php,v 1.41 2007/02/26 08:07:54 beni Exp $ * @link http://pear.php.net/package/Net_LDAP/ */ @@ -25,6 +25,7 @@ require_once('PEAR.php'); require_once('LDAP/Entry.php'); require_once('LDAP/Search.php'); +require_once('LDAP/Util.php'); require_once('LDAP/Filter.php'); /** @@ -43,7 +44,7 @@ * @author Benedikt Hallinger <beni@php.net> * @copyright 2003-2007 Tarjej Huse, Jan Wagner, Del Elson, Benedikt Hallinger * @license http://www.gnu.org/copyleft/lesser.html - * @version CVS: $Id: LDAP.php,v 1.40 2007/02/23 11:10:30 beni Exp $ + * @version CVS: $Id: LDAP.php,v 1.41 2007/02/26 08:07:54 beni Exp $ * @link http://pear.php.net/package/Net_LDAP/ */ class Net_LDAP extends PEAR @@ -118,7 +119,7 @@ var $_schemaAttrs = array(); /** - * Returns the Net_LDAP Release version. + * Returns the Net_LDAP Release version, may be called statically * * @static * @return string Net_LDAP version @@ -1082,7 +1083,6 @@ * @access public * @param array $attributes Array of attributes * @return array Array of UTF8 encoded attributes - * @todo the code is doubled in class Net_LDAP_Util! one of the codes should only use the functions provided by the other */ function utf8Encode($attributes) { @@ -1095,7 +1095,6 @@ * @access public * @param array $attributes Array of attributes * @return array Array with decoded attribute values - * @todo the code is doubled in class Net_LDAP_Util! regarding to Jan, THIS is the function that should be used. */ function utf8Decode($attributes) { @@ -1109,7 +1108,6 @@ * @param array $attributes Array of attributes * @param array $function Function to apply to attribute values * @return array Array of attributes with function applied to values - * @todo the code is doubled in class Net_LDAP_Util! regarding to Jan, THIS is the function that should be used. */ function _utf8($attributes, $function) { http://cvs.php.net/viewvc.cgi/pear/Net_LDAP/LDAP/Entry.php?r1=1.29&r2=1.30&diff_format=u Index: pear/Net_LDAP/LDAP/Entry.php diff -u pear/Net_LDAP/LDAP/Entry.php:1.29 pear/Net_LDAP/LDAP/Entry.php:1.30 --- pear/Net_LDAP/LDAP/Entry.php:1.29 Wed Jan 10 07:38:02 2007 +++ pear/Net_LDAP/LDAP/Entry.php Mon Feb 26 08:07:54 2007 @@ -19,12 +19,13 @@ // | License along with this library; if not, write to the Free Software | // | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | // +--------------------------------------------------------------------------+ -// | Authors: Jan Wagner | +// | Authors: Jan Wagner, Tarjej Huse | // +--------------------------------------------------------------------------+ // -// $Id: Entry.php,v 1.29 2007/01/10 07:38:02 beni Exp $ +// $Id: Entry.php,v 1.30 2007/02/26 08:07:54 beni Exp $ require_once("PEAR.php"); +require_once('Util.php'); /** * Object representation of a directory entry @@ -35,7 +36,7 @@ * @package Net_LDAP * @author Jan Wagner <wagner@netsols.de> * @author Tarjej Huse - * @version $Revision: 1.29 $ + * @version $Revision: 1.30 $ */ class Net_LDAP_Entry extends PEAR @@ -556,7 +557,7 @@ return PEAR::raiseError("Renaming/Moving an entry is only supported in LDAPv3"); } // make dn relative to parent (needed for ldap rename) - $parent = $this->ldap_explode_dn_escaped($this->_newdn, 0); + $parent = Net_LDAP_Util::ldap_explode_dn_escaped($this->_newdn, 0); $child = array_shift($parent); $parent = join(",", $parent); // rename @@ -679,33 +680,5 @@ return $this->_ldap; } } - - /** - * Wrapper function for PHPs ldap_explode_dn() - * - * PHPs ldap_explode_dn() does not escape DNs so it will fail - * if the parameter $dn is something like <kbd>"<foobar>"</kbd> or contains - * Umlauts. - * This method ensures, that the DN is properly escaped and encoded. - * - * It is taken from http://php.net/ldap_explode_dn and slightly modified. - * - * @author DavidSmith@byu.net - * @param string $dn The DN that should be split - * @param string $only - * @static - */ - function ldap_explode_dn_escaped($dn, $only_values=0) - { - $dn = addcslashes( $dn, "<>" ); - $result = ldap_explode_dn( $dn, $only_values ); - if (isset($result["count"])) { - unset($result["count"]); - } - //translate hex code into ascii again - foreach( $result as $key => $value ) - $result[$key] = preg_replace("/\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\1')).''", $value); - return $result; - } } ?> \ No newline at end of file http://cvs.php.net/viewvc.cgi/pear/Net_LDAP/LDAP/Filter.php?r1=1.3&r2=1.4&diff_format=u Index: pear/Net_LDAP/LDAP/Filter.php diff -u pear/Net_LDAP/LDAP/Filter.php:1.3 pear/Net_LDAP/LDAP/Filter.php:1.4 --- pear/Net_LDAP/LDAP/Filter.php:1.3 Thu Feb 22 08:06:10 2007 +++ pear/Net_LDAP/LDAP/Filter.php Mon Feb 26 08:07:54 2007 @@ -22,13 +22,16 @@ // | Authors: Benedikt Hallinger | // +--------------------------------------------------------------------------+ // -// $Id: Filter.php,v 1.3 2007/02/22 08:06:10 beni Exp $ +// $Id: Filter.php,v 1.4 2007/02/26 08:07:54 beni Exp $ require_once("PEAR.php"); +require_once('Util.php'); /** * Object representation of a part of a LDAP filter. * +* This Class is not completely compatible to the PERL interface! +* * The purpose of this class is, that users can easily build LDAP filters * without having to worry about right escaping etc. * A Filter is built using several independent filter objects @@ -56,7 +59,7 @@ * * @package Net_LDAP * @author Benedikt Hallinger <beni@php.net> -* @version $Revision: 1.3 $ +* @version $Revision: 1.4 $ */ class Net_LDAP_Filter extends PEAR @@ -284,20 +287,11 @@ * @static * @param string $string Any string who should be escaped * @return string The string $string, but escaped - * @todo "null" escaping stuff needs some work i think... */ function escape($string) { - $string = str_replace('*', '\0x2a', $string); - $string = str_replace('(', '\0x28', $string); - $string = str_replace(')', '\0x29', $string); - $string = str_replace('\\', '\0x5c', $string); - - // null escaping seems to never apply. This probably needs some work! - $string = str_replace(null, '\0x2a', $string); - if ($string == null) $string = '\0x2a'; // apply escaped "null" if string is empty - - return $string; + $array = Net_LDAP_Util::escape_filter_value(array($string)); + return $array[0]; } /** http://cvs.php.net/viewvc.cgi/pear/Net_LDAP/LDAP/Search.php?r1=1.17&r2=1.18&diff_format=u Index: pear/Net_LDAP/LDAP/Search.php diff -u pear/Net_LDAP/LDAP/Search.php:1.17 pear/Net_LDAP/LDAP/Search.php:1.18 --- pear/Net_LDAP/LDAP/Search.php:1.17 Thu Feb 22 08:06:10 2007 +++ pear/Net_LDAP/LDAP/Search.php Mon Feb 26 08:07:54 2007 @@ -19,17 +19,17 @@ // | License along with this library; if not, write to the Free Software | // | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | // +--------------------------------------------------------------------------+ -// | Authors: Tarjej Huse | +// | Authors: Tarjej Huse, Benedikt Hallinger | // +--------------------------------------------------------------------------+ // -// $Id: Search.php,v 1.17 2007/02/22 08:06:10 beni Exp $ +// $Id: Search.php,v 1.18 2007/02/26 08:07:54 beni Exp $ /** * Result set of an LDAP search * * @author Tarjei Huse * @author Benedikt Hallinger <beni@php.net> - * @version $Revision: 1.17 $ + * @version $Revision: 1.18 $ * @package Net_LDAP */ class Net_LDAP_Search extends PEAR http://cvs.php.net/viewvc.cgi/pear/Net_LDAP/LDAP/Util.php?r1=1.7&r2=1.8&diff_format=u Index: pear/Net_LDAP/LDAP/Util.php diff -u pear/Net_LDAP/LDAP/Util.php:1.7 pear/Net_LDAP/LDAP/Util.php:1.8 --- pear/Net_LDAP/LDAP/Util.php:1.7 Fri Dec 15 11:45:35 2006 +++ pear/Net_LDAP/LDAP/Util.php Mon Feb 26 08:07:54 2007 @@ -19,120 +19,231 @@ // | License along with this library; if not, write to the Free Software | // | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | // +--------------------------------------------------------------------------+ -// | Authors: Jan Wagner | +// | Authors: Benedikt Hallinger | // +--------------------------------------------------------------------------+ // -// $Id: Util.php,v 1.7 2006/12/15 11:45:35 beni Exp $ +// $Id: Util.php,v 1.8 2007/02/26 08:07:54 beni Exp $ /** * Utility Class for Net_LDAP * * @package Net_LDAP - * @author Jan Wagner <wagner@netsols.de> - * @version $Revision: 1.7 $ + * @author Benedikt Hallinger <beni@php.net> + * @version $Revision: 1.8 $ */ -class Net_LDAP_Util extends PEAR +class Net_LDAP_Util extends PEAR { /** - * Reference to LDAP object + * Private empty Constructur * * @access private - * @var object Net_LDAP */ - var $_ldap = null; + function Net_LDAP_Util() + { + // We do nothing here, since all methods can be called statically. + // In Net_LDAP <= 0.7, we needed a instance of Util, because + // it was possible to do utf8 encoding and decoding, but this + // has been moved to the LDAP class. + } /** - * Net_LDAP_Schema object + * Wrapper function for PHPs ldap_explode_dn() * - * @access private - * @var object Net_LDAP_Schema - */ - var $_schema = null; - - /** - * Constructur + * PHPs ldap_explode_dn() does not escape DNs so it will fail + * if the parameter $dn is something like <kbd>"<foobar>"</kbd> or contains + * Umlauts. + * This method ensures, that the DN is properly escaped and encoded. * - * Takes an LDAP object by reference and saves it. Then the schema will be fetched. + * It is taken from http://php.net/ldap_explode_dn and slightly modified. * - * @access public - * @param Net_LDAP Reference to Net_LDAP object + * @author DavidSmith@byu.net + * @param string $dn The DN that should be split + * @param string $only_values Return just values, no attribute names ('foo' instead of 'cn=foo') + * @static */ - function Net_LDAP_Util(&$ldap) + function ldap_explode_dn_escaped($dn, $only_values = 0) { - if (is_object($ldap) && (strtolower(get_class($ldap)) == 'net_ldap')) { - $this->_ldap = $ldap; - $this->_schema = $this->_ldap->schema(); - if (Net_LDAP::isError($this->_schema)) $this->_schema = null; + $dn = addcslashes( $dn, "<>" ); + $result = ldap_explode_dn( $dn, $only_values ); + if (isset($result["count"])) { + unset($result["count"]); } + //translate hex code into ascii again + foreach( $result as $key => $value ) + $result[$key] = preg_replace("/\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\1')).''", $value); + return $result; + } + + /** + * Comment taken from CPAN: + * + * Explodes the given DN into an array of hashes and returns a reference to this array. + * Returns undef if DN is not a valid Distinguished Name. + * A Distinguished Name is a sequence of Relative Distinguished Names (RDNs), which themselves + * are sets of Attributes. For each RDN a hash is constructed with the attribute type names as + * keys and the attribute values as corresponding values. These hashes are then stored in an + * array in the order in which they appear in the DN. + * + * For example, the DN 'OU=Sales+CN=J. Smith,DC=example,DC=net' is exploded to: + * [ { 'OU' => 'Sales', 'CN' => 'J. Smith' }, { 'DC' => 'example' }, { 'DC' => 'net' } ] + * + * (RFC2253 string) DNs might also contain values, which are the bytes of the BER encoding of + * the X.500 AttributeValue rather than some LDAP string syntax. These values are hex-encoded + * and prefixed with a #. To distinguish such BER values, ldap_explode_dn uses references to + * the actual values, e.g. '1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com' is exploded to: + * [ { '1.3.6.1.4.1.1466.0' => "\004\002Hi" }, { 'DC' => 'example' }, { 'DC' => 'com' } ]; + * + * It also performs the following operations on the given DN: + * - Unescape "\" followed by ",", "+", """, "\", "<", ">", ";", "#", "=", " ", or a hexpair + * and and strings beginning with "#". + * - Removes the leading 'OID.' characters if the type is an OID instead of a name. + * + * OPTIONS is a list of name/value pairs, valid options are: + * casefold Controls case folding of attribute types names. + * Attribute values are not affected by this option. + * The default is to uppercase. Valid values are: + * lower Lowercase attribute types names. + * upper Uppercase attribute type names. This is the default. + * none Do not change attribute type names. + * reverse If TRUE, the RDN sequence is reversed. + * + * @todo implement me! + * @static + * @param string $dn The DN that should be exploded + * @param array $options Options to use + * @return array Parts of the exploded DN + */ + function ldap_explode_dn($dn, $options = array('casefold' => 'upper')) + { + PEAR::raiseError("Not implemented!"); } /** - * Encodes given attributes to UTF8 if needed - * - * This function takes attributes in an array and then checks against the schema if they need - * UTF8 encoding. If that is so, they will be encoded. An encoded array will be returned and - * can be used for adding or modifying. - * - * @access public - * @param array $attributes Array of attributes - * @return array Array of UTF8 encoded attributes - * @todo the code is doubled in class Net_LDAP! Regarding to Jan utf8-stuff should be done inside Net_LDAP so THIS function is obsolete - * @obsolete - */ - function utf8Encode($attributes) + * escape_dn_value ( VALUES ) + * + * Comment taken from CPAN: + * Escapes the given VALUES according to RFC 2253 so that they can be safely used in LDAP DNs. + * The characters ",", "+", """, "\", "<", ">", ";", "#", "=" with a special meaning in RFC 2252 + * are preceeded by ba backslash. Control characters with an ASCII code < 32 are represented as \hexpair. + * Finally all leading and trailing spaces are converted to sequences of \20. + * + * Returns the converted list in list mode and the first element in scalar mode. + * + * @todo implement me! + * @static + * @param array $values A array containing the DN values that should be escaped + * @return array The array $values, but escaped + */ + function escape_dn_value($values = array()) { - return $this->_utf8($attributes, 'utf8_encode'); + PEAR::raiseError("Not implemented!"); } /** - * Decodes the given attribute values - * - * @access public - * @param array $attributes Array of attributes - * @return array Array with decoded attribute values - * @todo the code is doubled in class Net_LDAP! Regarding to Jan utf8-stuff should be done inside Net_LDAP so THIS function is obsolete - * @obsolete - */ - function utf8Decode($attributes) + * Undoes the conversion done by escape_dn_value(). + * + * Any escape sequence starting with a baskslash - hexpair or special character - + * will be transformed back to the corresponding character. + * + * Returns the converted list in list mode and the first element in scalar mode. + * + * @todo implement me! + * @param array $values Array of DN Values + * @return array Same as $values, but unescaped + * @static + */ + function unescape_dn_value($values = array()) { - return $this->_utf8($attributes, 'utf8_decode'); + PEAR::raiseError("Not implemented!"); } /** - * Encodes or decodes attribute values if needed - * - * @access private - * @param array $attributes Array of attributes - * @param array $function Function to apply to attribute values - * @return array Array of attributes with function applied to values - * @todo the code is doubled in class Net_LDAP! Regarding to Jan utf8-stuff should be done inside Net_LDAP so THIS function is obsolete - * @obsolete - */ - function _utf8($attributes, $function) + * Returns the given DN in a canonical form + * + * Returns undef if DN is not a valid Distinguished Name. + * Note: The empty string "" is a valid DN.) DN can either be a string or reference to an array of + * hashes as returned by ldap_explode_dn, which is useful when constructing a DN. + * + * It performs the following operations on the given DN: + * - Removes the leading 'OID.' characters if the type is an OID instead of a name. + * - Escapes all RFC 2253 special characters (",", "+", """, "\", "<", ">", ";", "#", "=", " "), slashes ("/"), and any other character where the ASCII code is < 32 as \hexpair. + * - Converts all leading and trailing spaces in values to be \20. + * - If an RDN contains multiple parts, the parts are re-ordered so that the attribute type names are in alphabetical order. + * + * OPTIONS is a list of name/value pairs, valid options are: + * casefold Controls case folding of attribute type names. + * Attribute values are not affected by this option. The default is to uppercase. + * Valid values are: + * lower Lowercase attribute type names. + * upper Uppercase attribute type names. This is the default. + * none Do not change attribute type names. + * mbcescape If TRUE, characters that are encoded as a multi-octet UTF-8 sequence will be escaped as \(hexpair){2,*}. + * reverse If TRUE, the RDN sequence is reversed. + * separator Separator to use between RDNs. Defaults to comma (','). + * + * @todo implement me! + * @static + * @param string $dn The DN + * @param array $option Options to use + * @return string The canonical DN + */ + function canonical_dn($dn, $options = array('casefold' => 'upper')) { - if (!$this->_ldap || !$this->_schema || !function_exists($function)) { - return $attributes; - } - if (is_array($attributes) && count($attributes) > 0) { - foreach( $attributes as $k => $v ) { - $attr = $this->_schema->get('attribute', $k); - if (Net_LDAP::isError($attr)) { - continue; - } - if (false !== strpos($attr['syntax'], '1.3.6.1.4.1.1466.115.121.1.15')) { - if (is_array($v)) { - foreach ($v as $ak => $av ) { - $v[$ak] = call_user_func($function, $av ); - } - } else { - $v = call_user_func($function, $v); - } - } - $attributes[$k] = $v; - } + PEAR::raiseError("Not implemented!"); + } + + /** + * Escapes the given VALUES according to RFC 2254 so that they can be safely used in LDAP filters. + * + * Any control characters with an ACII code < 32 as well as the characters with special meaning in + * LDAP filters "*", "(", ")", and "\" (the backslash) are converted into the representation of a + * backslash followed by two hex digits representing the hexadecimal value of the character. + * + * @todo NULL escaping seems to never apply + * @todo The "ASCII escaping" Part needs some work + * @static + * @param array $values Array of values to escape + * @return array Array $values, but escaped + */ + function escape_filter_value($values = array()) + { + $escaped = array(); + foreach ($values as $val) { + // ASCII < 32 escaping + // [TODO] + + // Escaping of meta characters + $val = str_replace('*', '\0x2a', $val); + $val = str_replace('(', '\0x28', $val); + $val = str_replace(')', '\0x29', $val); + $val = str_replace('\\', '\0x5c', $val); + $val = str_replace(null, '\0x2a', $val); // null escaping seems to never apply. This probably needs some work! + + if ($val === null) $val = '\0x2a'; // apply escaped "null" if string is empty + + array_push($escaped, $val); } - return $attributes; + + return $escaped; } + + /** + * Undoes the conversion done by {@link escape_filter_value()}. + * + * Converts any sequences of a backslash followed by two hex digits into the corresponding character. + * + * Returns the converted list in list mode and the first element in scalar mode. + * + * @todo implement me! + * @static + * @param array $values Array of values to escape + * @return array Array $values, but unescaped + */ + function unescape_filter_value($values = array()) + { + PEAR::raiseError("Not implemented!"); + } + } ?> \ No newline at end of file