LDAP v3 lets you define additional match operators and rules in the schema for specific data types. How you define these match operators for data and attribute types is covered in Chapter 4, in the section on attribute-matching rules. You can specify these extended match operators in the search filter by using an extended match filter syntax, which is slightly different from the simple search filter syntax already described. The extended syntax of the search filter is

"(" attributetype [":dn"] [":" extendedoperator] ":=" attributevalue ")" 

The optional elements are in [brackets]. The extended operator is usually an OID, but a descriptive name can also be assigned in the schema and used here in the filter.

The filter (cn:1.2.3.4.987:=Brian Arkills) would match any entry by comparing “Brian Arkills” with the values in their cn attributes, using the matching logic defined by the matching rule denoted by OID 1.2.3.4.987. Should this OID not denote a matching rule that the directory supports (and in this case the OID is a fabrication of the author), the directory will return an error code.

Extended match filters also let you search the DN of an entry for value matches. This may be a bit confusing at first. An entry's DN contains all the RDNs of the object above it in the directory structure. These RDNs may or may not be attributes of the entry. So if you wanted to find all the entries with ou=People in the DN, you would need to use an extended match filter. Now you may be thinking, “Why wouldn't you use a search with a base DN at the People OU, and a one-level scope?” This seems to accomplish the same thing. But consider the possibility that a referral might reside in the People OU. The more simple search would return records via this referral that technically do not have ou=People in their DN. Also consider the possibility that there might be more than one container with an RDN of ou=People in the directory. In this case, a single search without extended match filters would fail to capture all the entries. Multiple searches would work, but that approach might be inconvenient. Not all LDAP servers support extended match filter searching for DNs.

There are several special characters that must be treated differently when used in the attribute value portion of a search filter. You must escape these characters just as you had to escape the special characters in the DN or LDAP URL format. Table 3-1 lists the special search filter characters along with the escaped character sequence.

You must use the hexadecimal value of the character, which is different from quoting the special characters in DNs.

The bind operation is the first request a client sends to the server. Binding is the same task as authenticating to the directory. The client is verifying its identity to the directory, so all future operations can be performed in the context of that identity. A client that doesn't bind, or that binds with an empty string as the identity, is said to be anonymous. One identity may be allowed to view directory information that another identity can't. Binding to the directory provides an authorization context for allowing or denying the subsequent operations. The bind operation has two parameters: a DN and a set of credentials. Some LDAP directories are configured to support anonymous binding, and others are designed to allow no requests from anonymous clients. This design choice is typically linked to the sensitivity of the data in the directory.

The search operation is discussed in detail earlier in this chapter.

The compare operation simply verifies whether the information passed by the client matches the information stored in the directory. The compare operation is less useful than the search operation, except for one key situation in which it works differently from the search operation. If you ask to compare an attribute of an entry, but the attribute isn't present on the entry, a special result code is returned. A search operation for an attribute that isn't there returns no entries but a success result code. The compare operation has three parameters: a DN, an attribute type, and an attribute value.

For example, a compare operation request with the following parameters, against the directory pictured in Figure 3-1, would return a TRUE response.

The add operation allows the client to create a new entry. For it to be successful, the add operation requires that the client specify what object class(es) the new entry will contain, and that all mandatory attributes of that object class be supplied with values. The schema-checking process on the server enforces these requirements. Additionally, the container object of the new entry must already exist, and no existing entry can have the same DN. If there are structure rules for the entry's object class, they also must be met. Finally, the DN (and any RDNs) must be in the proper form with any illegal, special characters escaped. The add operation has primarily two parameters: a DN (of the new entry) and the attribute pairs (type and value) that you want to include on the entry. You can specify as many attribute pairs as you want (or as many as are required by the object class).

As an example, an add operation request to the Mycompany directory with the following parameters would be successful. I've denoted the list of attributes with semicolons delimiting the attribute pairs and with an equal sign connecting each pair. The actual syntax would depend on the API used.

The delete operation removes an entry from the directory. All information associated with that entry (the values of the entry's attributes) is removed. Of course, for the operation to succeed, the entry specified must exist. Additionally, that entry cannot be a container with child entries. A delete operation has a single parameter: the DN of the entry.

A delete operation request with the following parameter would delete the entry we just created in the previous Add section.

The modify operation allows the client to modify existing attributes of an entry, delete attribute values, or add a value to one or more attributes. The entry designated must exist for the operation to succeed. All the attribute modifications must succeed or the entire operation will fail. This condition avoids an inconsistent entry state in which the operation only partially succeeds. It also avoids the need for the client to order the attribute modifications in a least-to-highest risk order. The modify operation has two parameters: a DN and the set of attribute modifications desired.

Anakin's phone number has changed, and he is anxious to make sure the directory reflects his new number so he doesn't miss any calls from any ladies. He would also like to update his homePostalAddress so the Jedi Academy knows about his new home. A modify request with the following parameters will get the job done:

telephoneNumber=+1 212 121 2121;
homePostalAddress=31580749 Sith Way $ Jedi
Academy $ Coruscant;

The modifyRDN operation allows the client to rename the directory entry. The existing DN is specified, and the new RDN is supplied. The rename operation has four parameters: the DN to be renamed, the new RDN for the entry, a flag to tell the server whether to keep or delete the old RDN as an attribute of the entry, and an optional parameter for specifying a new parent container DN. This last optional parameter is important; it doesn't exist in the LDAP v2 standard. It lets you move an entry anywhere in the directory. The entry being moved can be a container with child entries beneath it. If the entry (or entries) being moved is being relocated to a DN on another server, the operation may fail depending on the vendor implementation. In this case, the client should be prepared to receive an affectsMultipleDSAs error in the result code. Even though the ability to specify a new parent DN is an essential requirement of meeting the LDAP v3 standard, some LDAP servers that advertise themselves as LDAP v3 compliant do not support this functionality.

The modifyRDN operation's ability to move an entry or even an entire portion of the directory tree can be confusing. The following examples should help to illustrate how this operation can be used. Each example is accompanied with a figure that shows how the directory looks before and after the operation.

Leia's name must be updated to reflect her marriage to Han Solo. The following modifyRDN operation parameters are used.

Figure 3-4 shows how the directory looks before and after the operation.

Figure 3-4. ModifyRDN used to modify only the RDN

Mycompany's Sales department manages the Customers container in which all customer contact information is kept. The Sales department is now a division of the HR department. Because the HR department manages the People container, the HR department wants the Customers container moved under the People container to reflect the organizational change. The HR department also wants to rename the Customers container to Customer Contacts. The following modifyRDN operation parameters are used.

Figure 3-5 shows how the directory looks before and after the operation.

Figure 3-5. ModifyRDN used to both modify the RDN and move the entry

Many people know Chewbacca by his nickname Chewie. His name must be updated to include both his formal name and nickname. The following modifyRDN operation parameters are used. After this operation, the original RDN will no longer be a valid DN, but it will remain as an attribute of the entry.

Figure 3-6 shows how the directory looks before and after the operation.

Figure 3-6. ModifyRDN used to modify the RDN, while leaving the old RDN

You may have expected to see both “Chewie” and “Chewbacca” in the second tree. But because of space restrictions, I can't list all the attributes of each entry … so pretend you can see the additional attributes associated with all these entries.

The unbind operation allows the client to close its existing session with the directory. The directory obliges by discarding any client credentials it is holding, and it ceases any work on behalf of the client session, effectively terminating the session. Note that the connection, in other words, the TCP session between the client and server, isn't necessarily terminated. After an unbind operation, if the client requests a new operation without binding, the new operation will be evaluated in the context of an anonymous client. The unbind operation has no parameters. If the client terminates the session without issuing an unbind operation, most LDAP implementations use a session timeout parameter to accomplish the same end. The directory administrator can set this directory-wide timeout parameter.

The abandon operation allows the client to tell the directory to cancel a specific previous operation it requested. This eliminates the need to unbind and rebind, should the client not want to wait for the results of a lengthy operation. This operation improves the potential efficiency of the client and server. The abandon operation has a single parameter: the message ID of the operation the client wishes to cancel. Note that a timing issue is possible with this operation. The client could send an abandon request that arrives at the server after the server has sent the complete result code (and entries) from the operation the client is canceling.

The extended operation is a placeholder for specific directory implementations to extend the functionality of the directory but still have a predefined syntax for doing so. Additional security functionality such as session encryption is a good example of an extended operation. An extended operation can have parameters just as any other LDAP operation does. An LDAP directory must advertise what extended operations are available in the root DSE object in the supportedExtension attribute. The root DSE object is a special directory entry with an empty DN: “”.

An example of an extended operation that has reached RFC status is the password modify extended operation as defined in RFC 3062. This operation addresses a common need of organizations. Traditionally, LDAP directories stored authentication information internal to the directory so each authentication identity had its own DN. In other words, the username and password were integrated with the LDAP namespace. Now, however, many LDAP directories use primarily SASL as the means of authentication. This allows for an external store of authentication information, using a non-LDAP namespace. Therefore, the traditional method of changing a password using the modify operation won't work in this instance. This extended operation provides a way to modify a password external to the directory.