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.
( filter )
Filters are always enclosed in brackets (parentheses).
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.
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.
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
(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
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:
(&(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 (|(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
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
(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
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 (18.104.22.168) sn=smith # override EQUALITY match with case sensitive match sn:caseExactMatch:=Smith # functionally same as above using OID sn:22.214.171.124:=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:126.96.36.199:=*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).
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.
3 ldap objects
4 install ldap
7 replica & refer
10 ldap api
14 ldap tools
notes & info
rfc's & x.500
This work is licensed under a Creative Commons License.
If you are happy it's OK - but your browser is giving a less than optimal experience on our site. You could, at no charge, upgrade to a W3C STANDARDS COMPLIANT browser such as Firefox