The LDAP Search Filters

The LDAP Search Filters

An LDAP filter is a Boolean combination of attribute–value assertions. An attribute–value assertion consists of two parts: an attribute name and a value assertion, which you can think of as a value with wildcards allowed. The following sections look at the various types of search filters. We use the RFC 2254 notation for LDAP search filters, which is convenient because the filters are encoded as text strings (within the LDAP protocol itself, the filters are encoded with BER, as discussed earlier). This notation is also what you use when using the ldapsearch command-line utility, which will be discussed later in this chapter.
Equality Filters

An equality filter allows you to look for entries that exactly match a particular value. Here's an example:

(sn=smith)

This filter matches entries in which the sn (surname) attribute contains a value that is exactly smith. Because the equality matching rule associated with the sn attribute is caseIgnoreMatch, the case of the attribute and the filter is not important when matching entries are being located.
Substring Filters

When you use wildcards in filters, they are called substring filters. For example, the filter (sn=smith*) matches any entry that has an sn attribute value that begins with "smith". Entries with a surname of Smith, Smithers, Smithsonian, and so on will be returned.

Wildcards may appear anywhere in the filter expression, so the filter (sn=*smith) matches entries in which the surname ends with "smith" (for example, Blacksmith). The filter (sn=smi*th) matches entries in which the surname begins with "smi" and ends with "th", and the filter (sn=*smith*) matches entries that contain the string "smith" in the surname attribute. Note that the wildcard character matches zero or more instances of any character, so the filter (sn=*smith*) would match the entry with the surname Smith as well as any surnames in which the string "smith" was embedded.
Approximate Filters

In addition to the equality and substring filters, servers support an approximate filter. For example, on most directory servers, the filter (sn~=jensen) returns entries in which the surname attribute has a value that sounds like "jensen" (for example, jenson). Exactly how the server implements this filter is particular to each vendor and the languages supported by the server. Netscape Directory Server, for example, uses the metaphone algorithm to locate entries when an approximate filter is used. Internationalization also throws an interesting wrinkle into the concept of approximate matching; each language may need its own particular sounds—like algorithms. For example, algorithms used to implement approximate matching for English are different from those for Japanese. It's likely that your directory software supports approximate matching for English but not for other languages.
"Greater Than or Equal To" and "Less Than or Equal To" Filters

LDAP servers also support "greater than or equal to" and "less than or equal to" filters on attributes that have some inherent ordering. For example, the filter (sn<=Smith) returns all entries in which the surname is less than or equal to Smith lexicographically. The ordering used depends on the matching rules associated with a particular attribute. The sn attribute, which is defined with the caseIgnoreOrderingMatch matching rule, is ordered lexicographically without respect to case. An attribute that has INTEGER syntax would be defined with a matching rule that would order values numerically. Attributes that have no inherent ordering, such as JPEG photos, cannot be searched for with this type of filter.

If you find that you need a greater-than or less-than filter (without the equals part), note that "greater than" is the complement of "less than or equal to" and "less than" is the complement of "greater than or equal to." In other words, (age>21) is equivalent to (!(age<=21)). Similarly, the filter (age<21), which is also not a valid LDAP filter, is equivalent to (!(age>=21)).

In these cases, ! is the negation operator, which we will discuss in more detail shortly.
Presence Filters

Another type of search filter is the presence filter. It matches any entry that has at least one value for the attribute. For example, the filter (telephoneNumber=*) matches all entries that have a telephone number.
Extensible Matching

The last type of search filter is the extensible match filter. It is supported only by LDAPv3 servers. The purpose of an extensible match filter is to allow new matching rules to be implemented in servers and used by clients. Recall our earlier example involving the caseIgnoreMatch rule. Each matching rule has an associated method for comparing values, depending on whether case is to be considered significant when values are being compared. When new attribute types are defined, it may also be necessary to define a new way of comparing values. Extensible matching also allows language-specific matching rules to be defined so that values in languages other than English can be meaningfully compared.

As an added benefit, extensible matching allows you to specify that the attributes that make up the DN of the entry should be searched. For example, using extensible matching you can locate all the entries in the directory that contain the attribute value assertion ou=Engineering anywhere in their DN. Without extensible matching, it's not possible to search on the individual components of the DN.

The syntax of an extensible matching filter is a bit complicated. It consists of five parts, three of which are optional:

1.-An attribute name. If omitted, any attribute type that supports the given matching rule is compared against the value.
2.-The optional string :dn, which indicates that the attributes forming the entry's DN are to be treated as attributes of the entry during the search.
3.-An optional colon and matching-rule identifier that identifies the particular matching rule to be used. If no matching rule is provided, the default matching rule for the attribute being searched should be used. If the attribute name is omitted, the colon and matching rule must be present.
4.-The literal string ":=", used to separate the matching-rule identifier from the attribute value.
5.-An attribute value to be compared against.

Formally, the grammar for the extensible search filter is

attr [":dn"] [":" matchingrule] ":=" value

where attr is an attribute name.
*.-matchingrule is usually given by an object identifier (OID), although if a descriptive name has been assigned to the matching rule, that may be used as well. The OIDs of the matching rules supported by your directory server will be given in its documentation.
*.-value is an attribute value to be used for comparison.

Although LDAP largely does away with the mandatory use of OIDs, you will see them from time to time, especially if you use extensible matching rules or if you design your own schema extensions. The topic of extending your directory schema is discussed in Chapter 8, Schema Design. Let's look at some examples of extensible matching filters:

*.-The following filter specifies that all entries in which the cn attribute matches the value Barbara Jensen should be returned:

(cn:1.2.3.4.5.6:=Barbara Jensen)

When comparing values, the matching rule given by the OID 1.2.3.4.5.6 should be used.
*.-The following filter specifies that all entries that contain the string jensen in the surname should be returned:

(sn:dn:1.2.3.4.5.7:=jensen)

Object Identifiers
Object identifiers, commonly referred to as OIDs, are unique identifiers assigned to objects. They are used to uniquely identify many different types of things, such as X.500 directory object and attribute types. In fact, just about everything in the X.500 directory system is identified by an OID. OIDs are also used to uniquely identify objects in other protocols, such as the Simple Network Management Protocol (SNMP).-OIDs are written as strings of dotted decimal numbers. Each part of an OID represents a node in a hierarchical OID tree. This hierarchy allows an arbitrarily large number of objects to be named, and it supports delegation of the namespace. For example, all the user attribute types defined by the X.500 standards begin with "2.5.4". The cn attribute is assigned the OID 2.5.4.3, and the sn attribute is assigned the OID 2.5.4.4.-An individual subtree of the OID tree is called an arc. Individual arcs may be assigned to organizations, which can then further divide the arc into subarcs, if so desired. For example, Netscape Communications Corporation has been assigned an arc of the OID namespace for its own use. Internally, it has divided that arc into subarcs for use by the various product teams. Delegating the management of the OID namespace in this fashion can prevent conflicts.-The X.500 protocol makes extensive use of OIDs to uniquely identify various protocol elements. LDAP, on the other hand, favors short, textual names for things: cn to describe the common name attribute and person to identify the person object class, for example. To maintain compatibility with X.500, LDAP allows a string representation of an OID to be used interchangeably with the short name for the item. For example, the search filters (cn=Barbara Jensen) and (2.5.4.3=Barbara Jensen) are equivalent. Unless you're working with an LDAP-based gateway into an X.500 system, you should generally avoid using OIDs in your directory-enabled applications.-The sn attributes within the DN are also searched. When comparing values, the matching rule given by the OID 1.2.3.4.5.7 should be used.

*.-The following filter returns any entries in which the o (organization) attribute exactly matches Example and any entry in which o=Example is one of the components of the DN:

(o:dn:=Example)

*.-The following filter returns any entries in which a DN component with a syntax appropriate to the given matching rule matches Example:

(:dn:1.2.3.4.5.8:=Example)

The matching rule given by the OID 1.2.3.4.5.8 should be used.

Negation

Any search element can be negated if the filter is preceded with an exclamation point (!). For example, the filter (!(sn=Smith)) matches all entries in which the sn attribute does not contain the value smith, including entries with no sn attribute at all.
Combining Filter Terms

Filters can also be combined by AND and OR operators. The AND operator is signified by an ampersand (&), and the OR operator is signified by the vertical bar (|). When combining search filters, you use prefix notation, in which the operator precedes its arguments. Those familiar with the "reverse polish notation" common on Hewlett-Packard calculators will be familiar with this concept (although reverse polish is a postfix notation, not a prefix notation like that used in LDAP search filters).

Let's look at some examples of combinations of LDAP search filters. The filter (&(sn=Smith) (L=Mountain View)) matches all entries with a surname of smith that also have an L (locality) attribute of Mountain View. In other words, this filter finds everyone named Smith in the Mountain View location. The filter (|(sn=Smith) (sn=Jones)) matches everyone with a surname of Smith or Jones.

You use parentheses to group more complex filters to make the meaning of the filter unambiguous. For example, if you want to search the directory for all entries that have an e-mail address but do not have a telephone number, you use the following filter:

(&(mail=*)(!(telephoneNumber=*)))

Note that the parentheses bind the negation operator to the presence filter for telephone number.

Technically speaking, parentheses are always required, even if the filter consists of only a single term. Some LDAP software allows you to omit the enclosing parentheses and inserts them for you before sending the search request to the server. However, if you are developing your own software using one of the available SDKs, you need to include the enclosing parentheses.

Table 2.3 summarizes the six types of search filters and the three Boolean operators.