Appendix A - LDAP: Text Search Filter

The text form of the search filter is defined by RFC 4515 with a bit of help from RFC 4510 and was significantly extended with component matching (RFC3687) and Generic String Encoding Rules (GSER) (RFC4972).

Note: Since component matching was defined significantly later than the original LDAPv3 specs and, since it is part of the basic specification, it does not require a LDAP extension OID (in the RootDSE) it is not clear either how widespread is the implementation or how, other than trying, one discovers whether an LDAP implementation supports the capability. Sigh. While announced with OpenLDAP 2.4.8 componentMatching is only included when LDAP_DEVEL is set which is not defaulted in most builds. Even after compiling with this variable not all matchingRules where available - specifically presentMatch. It apears that component matching is still in a development state (Ticket no. 5429).

While it may seem obvious, searching is only required where an entry cannot be found directly. That is, it is not the same as the 'base' DN of the read or modify operation. When an entry is initially added to a DIT it is assigned a DN (in the LDIF file or LDAP client). In general, to avoid excessive searching this 'creation' DN should be the same as that used to most frequently access the entry. However, if the entry will be used for authentication then special conditions apply.

Basic format

( filter )

Filters are always enclosed in brackets (parentheses).

Simple Single Expression Filters

attr=value # equals (may include wildcards)
attr~=value # approximately
attr>=value # greater than
attr<=value #less than
OR
objectclass=class

Note: The type of comparison carried out, for example, case sensitive or case insensitive is defined by the properties of the attribute used in the comparison and the form of the search (may be EQUALITY, ORDERING or SUBSTR. You will see references to a string used in a search being called a substring. This is only correct if it contain one or more wildcards. Attribute definition.

Where:

equals (=) performs either an EQUALITY match (no wildcards in value) or a SUBSTR match (one or more wildcards are included in value).

approx (~=) performs a match using one of two 'sounds-like' algorithms and requires an approx index.

greater than (>=) performs a match of value against the contents of the defined attribute and returns all those that are lexicographically equal or higher. This form only works if the attribute has an ORDERING rule and very few attributes do.

less than (<=) performs a match of value against the contents of the defined attribute and returns all those that are lexicographically equal or lower. This form only works if the attribute has an ORDERING rule and very few do.

wildcards

The wildcard * may be used singly as a presence indicator (the attribute exists in the entry or the objectclass exists in the entry) or as a classic iteration value in which case it means '0 or more characters may occur in the position of the *'. Wildcards may only be used as a presence indicator with objectclass=obj form

Simple Expression Search Examples

(mail=*) # returns all entries which have a mail attribute
(objectclass=*) # returns all entries
(mail=*@*) # return entries with any valid RFC822 mail address
(sn=smith) # exact match returns Smith but NOT Smit
(sn=s*) # returns entries with surnames starting with s or S
(cn=*a*i*) # return entries with common names with both a and i anywhere
(telephonenumber=*555) # return entries with telephone numbers that end with 555
(objectclass=person) #return entries which use person objectclass

Notes:

1. in objectclass=person any objectclass which uses person in its hierarchy is also returned e.g. if an entry is defined using inetOrgPerson or residentialPerson etc.
2. the form of the test carried out also depends on the definition of the attribute (as defined by ASN.1). e.g. sn and cn are part of the name attribute family which defines the matchingrule as caseIgnoreMatch which means that they are NOT case sensitive e.g. a search with sn=a will find both a and A.

Simple Combined Expression Filters

Two or more expressions may be combined (or nested) using & (AND), ! (NOT) and | (OR):

(&(exp1)(exp2)(exp3)) # exp1 AND exp2 AND exp3
(|(exp1)(exp2)(exp3)) # exp1 OR exp2 OR exp3
(!(exp1)) # NOT exp1
(&(!(exp1))(!(exp2))) # NOT exp1 AND NOT exp2

NOT (!) is a tad problematic but logical (maybe) and only works in the form above. See also the examples below:

Combined Simple Expression Search Examples

(&(mail=*)(cn=*r)(sn=s*)) # has mail attr AND cn ends with R 
                            AND sn starts with s
(|(sn=a*)(sn=b*)(sn=c*)) # sn starts with a OR b OR c
(!(sn=a*)) # entries with sn NOT starting with a
(&(!(sn=a*))(!(sn=b*))) # entries with sn NOT starting with a 
                          AND NOT starting with b
(&ammp;(sn=*a)(!(sn=s*))) # entries with sn ending with a AND NOT starting with s
# classic simple mistake - watch this one
(&(sn=a*)(sn=b*)(sb=c*)) # impossible always returns nothing

Searching for Special Characters

If you need to search for a pattern that includes a special character (* ) ( \ or NULL) it must be escaped using the format '\code' (the code is actually the 2 hexadecimal characters representing the ASCII character). Similarly any binary value may be search for by using its hexadecimal value.

\2a replaces or escapes *
\28 replaces or escapes (
\29 replaces or escapes )
\5c replaces or escapes \
\00 replaces or escapes NUL
\xx search for hexadecimal value
    where xx lies in range 00 - FF

Escaped Search Examples

(cn=*\2a*) # searches for * anywhere in the cn
(file=d:\5cmyfile.html) # searches for d:\myfile
(description=*\28*\29) # searches for both ( and ) 
                         anywhere and in that order
(bin=\5b\04) # searches for binary values 5b04

Extensible Matching

The default search behaviour for any attribute is defined by its MatchingRule for the search TYPE (EQUALITY, SUBSTR or ODERING). This may be overridden by defining a replacement matching rule (either by name or by OID).

# default sn EQUALITY comparison behaviour
# is caseIgnoreMatch (2.5.13.2)
sn=smith

# override EQUALITY match with case sensitive match
sn:caseExactMatch:=Smith
# functionally same as above using OID
sn:2.5.13.5:=Smith

# if a wildcard appears in seach the SUBSTR 
# MatchingRule applies

# default sn SUBSTR comparison behavior
# is caseIgnoreSubstringMatch
sn=*s* # finds Smith or smith

# override SUBSTR match with case sensitive match
sn:caseExactSubstringMatch:=*S* # only finds Smith
# functionally same as above using OID
sn:2.5.13.7:=*S*

Using the override process it is possible to define a search criteria that includes properties that are not defined by the Attribute such as ORDERING (which is very uncommon in attribute definitions).

DN Component

It is possible to declare that any part of the base DN attribute data values may also be included in the search. This may be done using the keyword dn within the search expression as shown below:

# indicates the dc value of com may appear in the DN 
# or the final target defined by the base DN and scope
dc:dn:=com

Component Matching is defined under the generic heading of Extensible Filters and is described separately.

---

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.