Documentation

Horde_Ldap_Util
in package

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-2017 Horde LLC (http://www.horde.org/)

Tags
category

Horde

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

Table of Contents

asc2hex32()  : string
Converts all ASCII chars < 32 to "\HEX".
canonicalDN()  : bool|string
Converts a DN into a canonical form.
escapeDNValue()  : array<string|int, mixed>
Escapes DN values according to RFC 2253.
escapeFilterValue()  : array<string|int, mixed>
Escapes the given values according to RFC 2254 so that they can be safely used in LDAP filters.
explodeDN()  : array<string|int, mixed>
Explodes the given DN into its elements
hex2asc()  : string
Converts all hexadecimal expressions ("\HEX") to their original ASCII characters.
splitAttributeString()  : array<string|int, mixed>
Splits a attribute=value syntax into an array.
splitRDNMultivalue()  : array<string|int, mixed>
Splits a multivalued RDN value into an array.
unescapeDNValue()  : array<string|int, mixed>
Unescapes DN values according to RFC 2253.
unescapeFilterValue()  : array<string|int, mixed>
Unescapes the given values according to RFC 2254.
_correctDNSplitting()  : array<string|int, mixed>
Corrects splitting of DN parts.

Methods

asc2hex32()

Converts all ASCII chars < 32 to "\HEX".

public static asc2hex32(string $string) : string
Parameters
$string : string

String to convert.

Return values
string —

Hexadecimal representation of $string.

canonicalDN()

Converts a DN into a canonical form.

public static canonicalDN(array<string|int, mixed>|string $dn[, array<string|int, mixed> $options = array() ]) : bool|string

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.

Parameters
$dn : array<string|int, mixed>|string

The DN.

$options : array<string|int, mixed> = array()

Options to use.

Return values
bool|string —

The canonical DN or false if the DN is not valid.

escapeDNValue()

Escapes DN values according to RFC 2253.

public static escapeDNValue(string|array<string|int, mixed> $values) : array<string|int, mixed>

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.

Parameters
$values : string|array<string|int, mixed>

DN values that should be escaped.

Return values
array<string|int, mixed> —

The escaped values.

escapeFilterValue()

Escapes the given values according to RFC 2254 so that they can be safely used in LDAP filters.

public static escapeFilterValue(array<string|int, mixed> $values) : array<string|int, mixed>

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.

Parameters
$values : array<string|int, mixed>

Values to escape.

Return values
array<string|int, mixed> —

Escaped values.

explodeDN()

Explodes the given DN into its elements

public static explodeDN(string $dn[, array<string|int, mixed> $options = array() ]) : array<string|int, mixed>

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: array(array('OU=Sales', 'CN=J. Smith'), 'DC=example', 'DC=net')

[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: array(array('1.3.6.1.4.1.1466.0' => "\004\002Hi"), array('DC' => 'example', array('DC' => 'com')) See 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')
Parameters
$dn : string

The DN that should be exploded.

$options : array<string|int, mixed> = array()

Options to use.

Tags
todo

implement BER

todo

replace preg_replace() callbacks.

Return values
array<string|int, mixed> —

Parts of the exploded DN.

hex2asc()

Converts all hexadecimal expressions ("\HEX") to their original ASCII characters.

public static hex2asc(string $string) : string
Parameters
$string : string

String to convert.

Tags
author

beni@php.net, heavily based on work from DavidSmith@byu.net

Return values
string —

ASCII representation of $string.

splitAttributeString()

Splits a attribute=value syntax into an array.

public static splitAttributeString(string $attr) : array<string|int, mixed>

The split will occur at the first unescaped '=' character.

Parameters
$attr : string

An attribute-value string.

Return values
array<string|int, mixed> —

Indexed array: 0=attribute name, 1=attribute value.

splitRDNMultivalue()

Splits a multivalued RDN value into an array.

public static splitRDNMultivalue(string $rdn) : array<string|int, mixed>

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: array([0] => 'OU=Sales', [1] => 'CN=J. Smith')

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.

Parameters
$rdn : string

Part of a (multivalued) escaped RDN (e.g. ou=foo or ou=foo+cn=bar)

Return values
array<string|int, mixed> —

The components of the multivalued RDN.

unescapeDNValue()

Unescapes DN values according to RFC 2253.

public static unescapeDNValue(array<string|int, mixed> $values) : array<string|int, mixed>

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.

Parameters
$values : array<string|int, mixed>

DN values.

Return values
array<string|int, mixed> —

Unescaped DN values.

unescapeFilterValue()

Unescapes the given values according to RFC 2254.

public static unescapeFilterValue([array<string|int, mixed> $values = array() ]) : array<string|int, mixed>

Reverses the conversion done by .

Converts any sequences of a backslash followed by two hex digits into the corresponding character.

Parameters
$values : array<string|int, mixed> = array()

Values to unescape.

Return values
array<string|int, mixed> —

Unescaped values.

_correctDNSplitting()

Corrects splitting of DN parts.

protected static _correctDNSplitting([array<string|int, mixed> $dn = array() ][, array<string|int, mixed> $separator = ',' ]) : array<string|int, mixed>
Parameters
$dn : array<string|int, mixed> = array()

Raw DN array.

$separator : array<string|int, mixed> = ','

Separator that was used when splitting.

Return values
array<string|int, mixed> —

Corrected array.

Search results