UnboundID LDAP SDK for Java

LDAPv3 Wire Protocol Reference

The LDAP Compare Operation

The LDAP compare operation may be used to determine whether a given entry has a specified attribute value. Each compare operation consists of one request message and one response message.

Technically, you can accomplish this with a search (using a base DN of the target entry DN, a scope of baseObject, and an equality filter with the target attribute type and assertion value; if the server returns a search result entry, the entry has the specified value), but the compare operation does this more efficiently because the compare operation can do this without the need for the extra search result entry message.

Honestly, the compare operation isn’t used all that often in most deployments. Nevertheless, it is a core LDAPv3 operation type, so it is described here for completeness.

The Compare Request

RFC 4511 section 4.10 defines the compare request protocol operation as follows:

CompareRequest ::= [APPLICATION 14] SEQUENCE {
     entry           LDAPDN,
     ava             AttributeValueAssertion }

And its dependencies, described elsewhere in RFC 4511, are:

LDAPDN ::= LDAPString -- Constrained to <distinguishedName>
                      -- [RFC4514]

AttributeValueAssertion ::= SEQUENCE {
     attributeDesc   AttributeDescription,
     assertionValue  AssertionValue }

LDAPString ::= OCTET STRING -- UTF-8 encoded,
                            -- [ISO10646] characters

AttributeDescription ::= LDAPString
                        -- Constrained to <attributedescription>
                        -- [RFC4512]

AttributeValue ::= OCTET STRING

That is to say that the compare request protocol operation is a sequence with a BER type of 0x6E (application class, constructed, tag number fourteen) and the following two elements:

• entry — The DN of the target entry. This is an octet string containing the string representation of the entry DN.
• ava — The attribute-value assertion. This is a sequence containing two octet strings: the first for the attribute description, and the second for the assertion value. Most of the time, the attribute description is just the name or OID for the target attribute type, but it may also include one or more attribute options (each of which would be preceded by a semicolon).

For example, let’s say that you want to determine whether the entry uid=jdoe,ou=People,dc=example,dc=com has an employeeType attribute with a value of salaried. If the compare request has message ID two and no request controls, it would be encoded as follows:

30 45 -- Begin the LDAPMessage sequence
   02 01 02 -- The message ID (integer value 2)
   6e 40 -- Begin the compare request protocol op
   04 24 75 69 64 3d 6a 64 6f 65 -- The target entry DN (octet string
         2c 6f 75 3d 50 65 6f 70 -- "uid=jdoe,ou=People,dc=example,dc=com")
         6c 65 2c 64 63 3d 65 78
         61 6d 70 6c 65 2c 64 63
         3d 63 6f 6d
   30 18 -- Begin the attribute value assertion sequence
      04 0c 65 6d 70 6c 6f 79 65 65 -- The attribute description (octet string
            54 79 70 65             -- "employeeType")
      04 08 73 61 6c 61 72 69 65 64 -- The assertion value (octet string "salaried")

The Compare Response

The compare response protocol operation is also defined in RFC 4511 section 4.10. That definition is:

CompareResponse ::= [APPLICATION 15] LDAPResult

We’ve already covered the LDAPResult element in an earlier section, so there’s no need to go into a lot of detail about it again here. But there is one unusual thing about the compare response: it won’t ever include a result code of success (0). Some of the result codes that may be used for the compare operation are:

• compareTrue (6) — Indicates that the target entry exists and contains the specified attribute with the indicated value.
• compareFalse (5) — Indicates that the target entry exists and contains the specified attribute, but that the attribute does not have the indicated value.
• noSuchObject (32) — Indicates that the target entry does not exist.
• noSuchAttribute (16) — Indicates that the target entry exists but does not contain the specified attribute.

There may, of course, be other result codes for other error conditions (e.g., if the requester doesn’t have permission to make the comparison, if the server is too busy, if the server encounters a referral while locating the target entry, if an internal server error occurs, etc.), but the above result codes are the most directly applicable.

If the server returns a compare response with a result code of compareTrue, then that would be encoded as:

30 0c -- Begin the LDAPMessage sequence
   02 01 02 -- The message ID (integer value 2)
   6f 07 -- Begin the compare response protocol op
      0a 01 06 -- compareTrue result code (enumerated value 6)
      04 00 -- No matched DN (0-byte octet string)
      04 00 -- No diagnostic message (0-byte octet string)