LDAP filters formal definition

Before reading this topic, you may want to review simple LDAP search filters shown in LDAP Filters. This topic describes the formal definition of LDAP search filters and is intended for advanced users.

Formal definition

The formal definition of the search filter is as follows (from RFC 1960):

<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <item>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<item> ::= <simple> | <present> | <substring>
<simple> ::= <attr> <filtertype> <value>
<filtertype> ::= <equal> | <approx> | <ge> | <le>
<equal> ::= '='
<approx> ::= '~='
<ge> ::= '>='
<le> ::= '<='
<present> ::= <attr> '=*'
<substring> ::= <attr> '=' <initial> <any> <final>
<initial> ::= NULL | <value>
<any> ::= '*' <starval>
<starval> ::= NULL | <value> '*' <starval>
<final> ::= NULL | <value>

The token <attr> is a string that represents a name of an attribute. The token <value> is a string that represents a value of an attribute whose format is defined by the underlying directory service.

Special Characters

If any of the following special characters must appear in the search filter as literals, they must be replaced by the listed escape sequence:

ASCII character	Escape sequence substitute
*	\2a
(	\28
)	\29
\	\5c
NUL	\00
/	\2f

In addition, arbitrary binary data may be represented using the escape sequence syntax by encoding each byte of binary data with the backslash (\) followed by two hexadecimal digits. For example, the four-byte value 0x00000004 is encoded as \00\00\00\04 in a filter string.

Special operators

In addition to the logical operators, LDAP defines two matching rule object identifiers (OIDs) that can be used to perform bitwise comparisons of numeric values. Matching rules have the following syntax:

where: "<attribute name>" is the name of the attribute, "<rule OID>" is the OID for the matching rule, and "<value>" is the value to use for comparison. Be aware that spaces cannot be used in this string. "<value>" must be a decimal number; it cannot be a hexadecimal number or a constant name such as ADS_GROUP_TYPE_SECURITY_ENABLED.

The following table lists the matching rule OIDs implemented by LDAP.

Matching rule OID	Description
1.2.840.113556.1.4.803	A match is found only if all bits from the attribute match the value. This rule is equivalent to a bitwise AND operator.
1.2.840.113556.1.4.804	A match is found if any bits from the attribute match the value. This rule is equivalent to a bitwise OR operator.

The following example query string searches Active Directory for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the comparison value.

(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))