/usr/share/php/Horde/Ldap/Util.php is in php-horde-ldap 2.3.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 | <?php
/**
* Utility Class for Horde_Ldap
*
* This class servers some functionality to the other classes of Horde_Ldap but
* most of the methods can be used separately as well.
*
* Copyright 2009 Benedikt Hallinger
* Copyright 2010-2016 Horde LLC (http://www.horde.org/)
*
* @category Horde
* @package Ldap
* @author Benedikt Hallinger <beni@php.net>
* @author Jan Schneider <jan@horde.org>
* @license http://www.gnu.org/licenses/lgpl-3.0.html LGPL-3.0
*/
class Horde_Ldap_Util
{
/**
* Explodes the given DN into its elements
*
* {@link http://www.ietf.org/rfc/rfc2253.txt RFC 2253} says, a
* Distinguished Name is a sequence of Relative Distinguished Names (RDNs),
* which themselves are sets of Attributes. For each RDN a array is
* constructed where the RDN part is stored.
*
* For example, the DN 'OU=Sales+CN=J. Smith,DC=example,DC=net' is exploded
* to:
* <code>
* array(array('OU=Sales', 'CN=J. Smith'),
* 'DC=example',
* 'DC=net')
* </code>
*
* [NOT IMPLEMENTED] 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, explodeDN uses references to the
* actual values, e.g. '1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com' is
* exploded to:
* <code>
* array(array('1.3.6.1.4.1.1466.0' => "\004\002Hi"),
* array('DC' => 'example',
* array('DC' => 'com'))
* <code>
* See {@link http://www.vijaymukhi.com/vmis/berldap.htm} for more
* information on BER.
*
* It also performs the following operations on the given DN:
* - Unescape "\" followed by ",", "+", """, "\", "<", ">", ";", "#", "=",
* " ", or a hexpair and strings beginning with "#".
* - Removes the leading 'OID.' characters if the type is an OID instead of
* a name.
* - 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 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.
* - onlyvalues: If true, then only attributes values are returned ('foo'
* instead of 'cn=foo')
*
* @todo implement BER
* @todo replace preg_replace() callbacks.
*
* @param string $dn The DN that should be exploded.
* @param array $options Options to use.
*
* @return array Parts of the exploded DN.
*/
public static function explodeDN($dn, array $options = array())
{
$options = array_merge(
array(
'casefold' => 'upper',
'onlyvalues' => false,
'reverse' => false,
),
$options
);
// Escaping of DN and stripping of "OID.".
$dn = self::canonicalDN($dn, array('casefold' => $options['casefold']));
// Splitting the DN.
$dn_array = preg_split('/(?<!\\\\),/', $dn);
// Clear wrong splitting (possibly we have split too much).
// Not clear, if this is neccessary here:
//$dn_array = self::_correctDNSplitting($dn_array, ',');
$callback_upper = function($value) {
return Horde_String::upper($value[1]);
};
$callback_lower = function($value) {
return Horde_String::lower($value[1]);
};
// Construct subarrays for multivalued RDNs and unescape DN value, also
// convert to output format and apply casefolding.
foreach ($dn_array as $key => $value) {
$value_u = self::unescapeDNValue($value);
$rdns = self::splitRDNMultivalue($value_u[0]);
// TODO: nuke code duplication
if (count($rdns) > 1) {
// Multivalued RDN!
foreach ($rdns as $subrdn_k => $subrdn_v) {
// Casefolding.
if ($options['casefold'] == 'upper') {
$subrdn_v = preg_replace_callback('/^(\w+=)/',
$callback_upper,
$subrdn_v);
}
if ($options['casefold'] == 'lower') {
$subrdn_v = preg_replace_callback('/^(\w+=)/',
$callback_lower,
$subrdn_v);
}
if ($options['onlyvalues']) {
preg_match('/(.+?)(?<!\\\\)=(.+)/', $subrdn_v, $matches);
$rdn_val = $matches[2];
$unescaped = self::unescapeDNValue($rdn_val);
$rdns[$subrdn_k] = $unescaped[0];
} else {
$unescaped = self::unescapeDNValue($subrdn_v);
$rdns[$subrdn_k] = $unescaped[0];
}
}
$dn_array[$key] = $rdns;
} else {
// Singlevalued RDN.
// Casefolding.
if ($options['casefold'] == 'upper') {
$value = preg_replace_callback('/^(\w+=)/',
$callback_upper,
$value);
}
if ($options['casefold'] == 'lower') {
$value = preg_replace_callback('/^(\w+=)/',
$callback_lower,
$value);
}
if ($options['onlyvalues']) {
preg_match('/(.+?)(?<!\\\\)=(.+)/', $value, $matches);
$dn_val = $matches[2];
$unescaped = self::unescapeDNValue($dn_val);
$dn_array[$key] = $unescaped[0];
} else {
$unescaped = self::unescapeDNValue($value);
$dn_array[$key] = $unescaped[0];
}
}
}
if ($options['reverse']) {
return array_reverse($dn_array);
}
return $dn_array;
}
/**
* Escapes DN values according to RFC 2253.
*
* 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.
*
* @param string|array $values DN values that should be escaped.
*
* @return array The escaped values.
*/
public static function escapeDNValue($values)
{
// Parameter validation.
if (!is_array($values)) {
$values = array($values);
}
foreach ($values as $key => $val) {
// Escaping of filter meta characters.
$val = addcslashes($val, '\\,+"<>;#=');
// ASCII < 32 escaping.
$val = self::asc2hex32($val);
// Convert all leading and trailing spaces to sequences of \20.
if (preg_match('/^(\s*)(.+?)(\s*)$/', $val, $matches)) {
$val = str_repeat('\20', strlen($matches[1])) . $matches[2] . str_repeat('\20', strlen($matches[3]));
}
if (null === $val) {
// Apply escaped "null" if string is empty.
$val = '\0';
}
$values[$key] = $val;
}
return $values;
}
/**
* Unescapes DN values according to RFC 2253.
*
* Reverts the conversion done by escapeDNValue().
*
* Any escape sequence starting with a baskslash - hexpair or special
* character - will be transformed back to the corresponding character.
*
* @param array $values DN values.
*
* @return array Unescaped DN values.
*/
public static function unescapeDNValue($values)
{
// Parameter validation.
if (!is_array($values)) {
$values = array($values);
}
foreach ($values as $key => $val) {
// Strip slashes from special chars.
$val = str_replace(
array('\\\\', '\,', '\+', '\"', '\<', '\>', '\;', '\#', '\='),
array('\\', ',', '+', '"', '<', '>', ';', '#', '='),
$val);
// Translate hex code into ascii.
$values[$key] = self::hex2asc($val);
}
return $values;
}
/**
* Converts a DN into a canonical form.
*
* DN can either be a string or an array as returned by explodeDN(),
* which is useful when constructing a DN. The DN array may have be
* indexed (each array value is a OCL=VALUE pair) or associative (array key
* is OCL and value is VALUE).
*
* 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.
* - none: Do not change attribute type names.
* - reverse: If true, the RDN sequence is reversed.
* - separator: Separator to use between RDNs. Defaults to comma (',').
*
* The empty string "" is a valid DN, so be sure not to do a "$can_dn ==
* false" test, because an empty string evaluates to false. Use the "==="
* operator instead.
*
* @param array|string $dn The DN.
* @param array $options Options to use.
*
* @return boolean|string The canonical DN or false if the DN is not valid.
*/
public static function canonicalDN($dn, array $options = array())
{
if ($dn === '') {
// Empty DN is valid.
return $dn;
}
// Options check.
$options = array_merge(
array(
'casefold' => 'upper',
'reverse' => false,
'separator' => ',',
),
$options
);
if (!is_array($dn)) {
// It is not clear to me if the perl implementation splits by the
// user defined separator or if it just uses this separator to
// construct the new DN.
$dn = preg_split('/(?<!\\\\)' . preg_quote($options['separator']) . '/', $dn);
// Clear wrong splitting (possibly we have split too much).
$dn = self::_correctDNSplitting($dn, $options['separator']);
} else {
// Is array, check if the array is indexed or associative.
$assoc = false;
foreach ($dn as $dn_key => $dn_part) {
if (!is_int($dn_key)) {
$assoc = true;
break;
}
}
// Convert to indexed, if associative array detected.
if ($assoc) {
$newdn = array();
foreach ($dn as $dn_key => $dn_part) {
if (is_array($dn_part)) {
// We assume here that the RDN parts are also
// associative.
ksort($dn_part, SORT_STRING);
// Copy array as-is, so we can resolve it later.
$newdn[] = $dn_part;
} else {
$newdn[] = $dn_key . '=' . $dn_part;
}
}
$dn =& $newdn;
}
}
// Escaping and casefolding.
foreach ($dn as $pos => $dnval) {
if (is_array($dnval)) {
// Subarray detected, this means most probably that we had a
// multivalued DN part, which must be resolved.
$dnval_new = '';
foreach ($dnval as $subkey => $subval) {
// Build RDN part.
if (!is_int($subkey)) {
$subval = $subkey . '=' . $subval;
}
$subval_processed = self::canonicalDN($subval, $options);
if (false === $subval_processed) {
return false;
}
$dnval_new .= $subval_processed . '+';
}
// Store RDN part, strip last plus.
$dn[$pos] = substr($dnval_new, 0, -1);
} else {
// Try to split multivalued RDNs into array.
$rdns = self::splitRDNMultivalue($dnval);
if (count($rdns) > 1) {
// Multivalued RDN was detected. The RDN value is expected
// to be correctly split by splitRDNMultivalue(). It's time
// to sort the RDN and build the DN.
$rdn_string = '';
// Sort RDN keys alphabetically.
sort($rdns, SORT_STRING);
foreach ($rdns as $rdn) {
$subval_processed = self::canonicalDN($rdn, $options);
if (false === $subval_processed) {
return false;
}
$rdn_string .= $subval_processed . '+';
}
// Store RDN part, strip last plus.
$dn[$pos] = substr($rdn_string, 0, -1);
} else {
// No multivalued RDN. Split at first unescaped "=".
$dn_comp = self::splitAttributeString($rdns[0]);
if (count($dn_comp) != 2) {
throw new Horde_Ldap_Exception('Invalid RDN: ' . $rdns[0]);
}
// Trim left whitespaces because of "cn=foo, l=bar" syntax
// (whitespace after comma).
$ocl = ltrim($dn_comp[0]);
$val = $dn_comp[1];
// Strip 'OID.', otherwise apply casefolding and escaping.
if (substr(Horde_String::lower($ocl), 0, 4) == 'oid.') {
$ocl = substr($ocl, 4);
} else {
if ($options['casefold'] == 'upper') {
$ocl = Horde_String::upper($ocl);
}
if ($options['casefold'] == 'lower') {
$ocl = Horde_String::lower($ocl);
}
$ocl = self::escapeDNValue(array($ocl));
$ocl = $ocl[0];
}
// Escaping of DN value.
// TODO: if the value is already correctly escaped, we get
// double escaping.
$val = self::escapeDNValue(array($val));
$val = str_replace('/', '\/', $val[0]);
$dn[$pos] = $ocl . '=' . $val;
}
}
}
if ($options['reverse']) {
$dn = array_reverse($dn);
}
return implode($options['separator'], $dn);
}
/**
* 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.
*
* @param array $values Values to escape.
*
* @return array Escaped values.
*/
public static function escapeFilterValue($values)
{
// Parameter validation.
if (!is_array($values)) {
$values = array($values);
}
foreach ($values as $key => $val) {
// Escaping of filter meta characters.
$val = str_replace(array('\\', '*', '(', ')'),
array('\5c', '\2a', '\28', '\29'),
$val);
// ASCII < 32 escaping.
$val = self::asc2hex32($val);
if (null === $val) {
// Apply escaped "null" if string is empty.
$val = '\0';
}
$values[$key] = $val;
}
return $values;
}
/**
* Unescapes the given values according to RFC 2254.
*
* Reverses the conversion done by {@link escapeFilterValue()}.
*
* Converts any sequences of a backslash followed by two hex digits into
* the corresponding character.
*
* @param array $values Values to unescape.
*
* @return array Unescaped values.
*/
public static function unescapeFilterValue($values = array())
{
// Parameter validation.
if (!is_array($values)) {
$values = array($values);
}
foreach ($values as $key => $value) {
// Translate hex code into ascii.
$values[$key] = self::hex2asc($value);
}
return $values;
}
/**
* Converts all ASCII chars < 32 to "\HEX".
*
* @param string $string String to convert.
*
* @return string Hexadecimal representation of $string.
*/
public static function asc2hex32($string)
{
for ($i = 0, $len = strlen($string); $i < $len; $i++) {
$char = substr($string, $i, 1);
if (ord($char) < 32) {
$hex = dechex(ord($char));
if (strlen($hex) == 1) {
$hex = '0' . $hex;
}
$string = str_replace($char, '\\' . $hex, $string);
}
}
return $string;
}
/**
* Converts all hexadecimal expressions ("\HEX") to their original ASCII
* characters.
*
* @author beni@php.net, heavily based on work from DavidSmith@byu.net
*
* @param string $string String to convert.
*
* @return string ASCII representation of $string.
*/
public static function hex2asc($string)
{
return preg_replace_callback(
'/\\\([0-9A-Fa-f]{2})/',
function($hex) {
return chr(hexdec($hex[1]));
},
$string);
}
/**
* Splits a multivalued RDN value into an array.
*
* A RDN can contain multiple values, spearated by a plus sign. This method
* returns each separate ocl=value pair of the RDN part.
*
* If no multivalued RDN is detected, an array containing only the original
* RDN part is returned.
*
* For example, the multivalued RDN 'OU=Sales+CN=J. Smith' is exploded to:
* <kbd>array([0] => 'OU=Sales', [1] => 'CN=J. Smith')</kbd>
*
* The method tries to be smart if it encounters unescaped "+" characters,
* but may fail, so better ensure escaped "+" in attribute names and
* values.
*
* [BUG] If you have a multivalued RDN with unescaped plus characters and
* there is a unescaped plus sign at the end of an value followed by
* an attribute name containing an unescaped plus, then you will get
* wrong splitting:
* $rdn = 'OU=Sales+C+N=J. Smith';
* returns:
* array('OU=Sales+C', 'N=J. Smith');
* The "C+" is treaten as the value of the first pair instead of as
* the attribute name of the second pair. To prevent this, escape
* correctly.
*
* @param string $rdn Part of a (multivalued) escaped RDN (e.g. ou=foo or
* ou=foo+cn=bar)
*
* @return array The components of the multivalued RDN.
*/
public static function splitRDNMultivalue($rdn)
{
$rdns = preg_split('/(?<!\\\\)\+/', $rdn);
$rdns = self::_correctDNSplitting($rdns, '+');
return array_values($rdns);
}
/**
* Splits a attribute=value syntax into an array.
*
* The split will occur at the first unescaped '=' character.
*
* @param string $attr An attribute-value string.
*
* @return array Indexed array: 0=attribute name, 1=attribute value.
*/
public static function splitAttributeString($attr)
{
return preg_split('/(?<!\\\\)=/', $attr, 2);
}
/**
* Corrects splitting of DN parts.
*
* @param array $dn Raw DN array.
* @param array $separator Separator that was used when splitting.
*
* @return array Corrected array.
*/
protected static function _correctDNSplitting($dn = array(),
$separator = ',')
{
foreach ($dn as $key => $dn_value) {
// Refresh value (foreach caches!)
$dn_value = $dn[$key];
// If $dn_value is not in attr=value format, we had an unescaped
// separator character inside the attr name or the value. We assume
// that it was the attribute value.
// TODO: To solve this, we might ask the schema. The
// Horde_Ldap_Util class must remain independent from the
// other classes or connections though.
if (!preg_match('/.+(?<!\\\\)=.+/', $dn_value)) {
unset($dn[$key]);
if (array_key_exists($key - 1, $dn)) {
// Append to previous attribute value.
$dn[$key - 1] = $dn[$key - 1] . $separator . $dn_value;
} elseif (array_key_exists($key + 1, $dn)) {
// First element: prepend to next attribute name.
$dn[$key + 1] = $dn_value . $separator . $dn[$key + 1];
} else {
$dn[$key] = $dn_value;
}
}
}
return array_values($dn);
}
}
|