While most LDAP result codes are defined in RFC 4511, there are a number of other LDAP specifications that define their own result codes. Some of these are RFCs, and therefore should be considered “officially official” result codes. Others are IETF drafts, and their officialness often falls on a sliding scale from “de facto official” to “deny their existence”. This chapter attempts to provide all of the result codes from LDAP-related RFCs (except for RFC 4511, which was covered in the last chapter) and as many of the result codes as possible from LDAP-related IETF drafts.
Defined in Specification: RFC 1777
Applicable operation types: none
The isLeaf result code was defined for use in LDAPv2, but it has been removed from the LDAPv3 specification. None of the LDAPv2 standards documents provide any guidance on the conditions in which the isLeaf result code should be used, nor does it appear to have been inherited from any of the X.500 specifications from which LDAP is derived. However, it is likely the case that it was intended for use in the event that a requested operation was only allowed to target a non-leaf entry (that is, an entry that has one or more subordinate entries), but targeted a leaf entry.
Defined in Specification: RFC 1798
The resultsTooLarge result code is not actually used in LDAP. It is only intended for use in CLDAP, which encodes requests and responses in a manner similar to LDAP (albeit LDAPv2 at the time RFC 1798 was published) but uses UDP rather than TCP and only supports search and abandon requests. In CLDAP, the resultsTooLarge result code indicates that a search response message is too large to fit in a UDP packet.
RFC 3352, released in March of 2003, declared CLDAP a historical protocol that should no longer be used. Nevertheless, it appears that a number of public Internet-facing servers still support this capability as recently as late 2016 because CLDAP was used as a means of launching distributed denial-of-service (DDoS) attacks because a very small request can be used to generate a substantially larger response and because UDP packets can be spoofed to appear as if they are coming from a different source address than they actually are. This allows for an attacker to use a small amount of traffic to send requests to one or more CLDAP servers, and then cause those servers to send large amounts of traffic to an unsuspecting victim.
If you’re running a directory server that supports CLDAP, you should either turn off that capability or ensure that it’s behind a firewall that will block incoming requests from malicious external clients, and that will block outbound responses to spoofed addresses.
LDAP is an asynchronous protocol, which means that (with certain restrictions) there’s no need to wait for a response to one request before sending another request. So you can have multiple active operations for a connection at the same time, and the responses may be received from the server in any order and may be interleaved. To deal with this, the client assigns a different integer value, called the message ID, to each request. Most clients just keep a counter for each connection, so that the first request has a message ID of 1, the second request a message ID of 2, and so on. Whenever the server returns a response for a request, it includes the request’s message ID in the response, which allows the client to match up that response with the appropriate request.
There may be times when a client wants to tell the server to stop processing a request that is currently in progress on the connection. For example, this could happen if the server is taking longer than expected to process an operation and the client wants to send the request to a different server. The LDAP abandon request, in which the client provides the message ID for the operation it wants the server to stop processing, can be used to accomplish this. However, the abandon operation has a couple of undesirable qualities:
This means that the abandon operation is a “fire and forget” operation, where it’s difficult for the client to know whether it was successful or not. And if a connection is shared across multiple application threads, one thread may be waiting for a response to the operation that won’t be coming because it has been abandoned.
To address these problems, RFC 3909 defines a new type of extended operation called the cancel operation. It behaves like an abandon operation in that the client provides the message ID of an operation it wants the server to stop processing, but it also addresses the two problems listed above:
As part of the specification for the cancel extended operation, RFC 3909 defines four new result codes, which are described below.
Applicable operation types: add, compare, delete, extended, modify, modify DN, search
The canceled result code does double duty. When the server uses this result code in the response to a cancel extended request, it means that the target operation was successfully canceled. And when the server uses this result code in the response to any other kind of operation, it means that operation was canceled by a cancel request.
In addition, although the standard LDAP behavior is to never send a response to an operation that has been interrupted by an abandon request, some servers may have an option to send a canceled response to any operation that is successfully abandoned. This helps protect against the possibility of a client waiting forever (or at least for a long time) for a response that isn’t going to come.
Applicable operation types: extended
The noSuchOperation result code may be included in a cancel extended response to indicate that the server couldn’t cancel the requested operation because it didn’t know anything about that operation. This probably means that the server has already completed processing for the operation (and possibly even that it completed that processing while the client was sending the cancel request) and has forgotten all about it. However, it could also mean that the client screwed up and included the wrong message ID in the cancel request.
Applicable operation types: extended
The tooLate result code may be included in a cancel extended response to indicate that the server received the cancel request and identified the operation to be canceled, but determined that it was already too far into processing the operation to be able to honor the cancel request. Some of the conditions in which this result code might be used include:
Applicable operation types: extended
The cannotCancel result code may be included in a cancel extended response to indicate that the server received the cancel request and identified the operation to be canceled, but the target operation isn’t one that can ever be canceled. RFC 3909 states that the following types of operations cannot be canceled:
In addition, some servers may define other types of operations that cannot be canceled.
Defined in Specification: RFC 4528
Applicable operation types: add, compare, delete, extended, modify, modify DN, search
The assertionFailed result code is used to indicate that the associated request included an LDAP assertion request control with a filter that did not match the target entry. The assertion request control may be used to indicate that the associated operation should only be processed if the target entry matches a specified filter. This is particularly useful for write operations, as it allows for a kind of atomic “check and set” operation, but you can also use it for compare and search operations (and for a search operation, the target entry is the one indicated by the search base DN). Some directory servers may also support it for certain extended operations.
If the filter included in the assertion request control does not match the target entry, then the operation will fail, and the response will include the assertionFailed result code. If the filter does match the target entry, then the operation will be processed as normal, and may succeed, or may fail for some reason unrelated to the inclusion of the assertion request control.
Defined in Specification: RFC 4370
Applicable operation types: add, compare, delete, extended, modify, modify DN, search
The authorizationDenied result code is used to indicate that the associated request included a proxied authorization request control, but that the client is not permitted to assign the requested authorization identity.
The proxied authorization request control allows a client authenticated as one account to request that an operation be processed under the authority of a different account. It’s kind of like the LDAP equivalent of the UNIX sudo command, and it allows you to have a pool of connections authenticated as an application-specific account that are used to request operations that are processed as if they had been requested by the end users accessing that application.
Since allowing one account to impersonate another is obviously a security risk, directory servers generally impose strict restrictions on which accounts can use the proxied authorization control, and on which accounts they’re allowed to impersonate. In the event that a client attempts to use the proxied authorization control when they aren’t allowed to use it, or when they aren’t allowed to impersonate the requested authorization identity, the server will reject that request with the authorizationDenied result code.
Defined in Specification: RFC 4533
Applicable operation types: search
The e-syncRefreshRequired result code is used to indicate that the associated request included a content synchronization request control with a cookie that is not recognized or cannot be used.
The content synchronization request control can be used to allow a client to maintain a partial or complete copy of the data in a directory server, and to be kept up to date with changes made to the data in that server. If it is a partial copy, then that may include a subset of the entries within the server (identified by the base DN, scope, and filter from the search request) and a subset of the attributes within each entry (identified by the requested attributes from the search request). The client first needs to retrieve a copy of all of the relevant data, and it includes a state cookie in the response indicating that all of those entries have been returned. The client can then send a second search request with a content synchronization request control that includes that cookie so that the server can provide the client with information from any entries that have changed since the last search. But if that cookie is no longer valid (for example, because it has been too long since it was generated and it is no longer valid), then the server will return a search result done message with the e-syncRefreshRequired result code to indicate that the client needs to retrieve a new complete copy of the relevant data.
Defined in Specification: draft-ietf-ldapext-ldapv3-vlv
Applicable operation types: search
The virtual list view request control may be included in a search request to indicate that the server should return a specified portion of the entire set of search results. It is similar to the simple paged results control (as described in RFC 2696), but there are a couple of key differences. In particular, the virtual list view request control requires the results to be sorted (and therefore the request must also include the server-side sort request control as described in RFC 2891) whereas the simple paged results control does not, and the virtual list view request control allows the client to jump around in the result set whereas the simple paged results control only allows for iterating sequentially through the result set.
The virtual list view request control specifies four elements:
And the search result done message that the server returns after it’s completed processing for the search request should include a virtual list view response control with the following four elements:
The draft-ietf-ldapext-ldapv3-vlv specification defines three new result codes: sortControlMissing (60), offsetRangeError (61), and virtualListViewError (76). However, only the virtualListViewError result code is actually intended to be used as a result code in search result done messages. The other two result codes are intended to be used only in the “virtual list view result” element of the virtual list view response control, and only if the search result done message has a result code of virtualListViewError.
The sortControlMissing result code should be used as the “virtual list view result” result code in the virtual list view response control if the search request included a virtual list view request control but did not also include the required server-side sort request control.
The offsetRangeError result code should be used as the “virtual list view result” result code in the virtual list view response control if the search request included a virtual list view request control that identified the target entry by offset but had an inappropriate offset or content count value.
The virtualListViewError result code indicates that the search operation failed because of a problem encountered while performing processing related to the virtual list view request control. The search result done response will also include a virtual list view response control, and that response control will itself include a result code that provides information about the nature of the problem. As per draft-ietf-ldapext-ldapv3-vlv, some of the values that may be used for that result code are:
The diagnostic message in the search result done message may also provide additional information about the problem that occurred.
Some of the most likely causes for a virtualListViewError result are:
As described in the next section, the numeric value 76 was also proposed to mean controlError in draft-armijo-ldap-control-error. Neither the draft-ietf-ldapext-ldapv3-vlv nor the draft-armijo-ldap-control-error specification made it out of draft phase to become an official RFC, but draft-ietf-ldapext-ldapv3-vlv is supported by a number of directory servers and is sort of a de facto standard, so most of the time you see a result code with a numeric value of 76, it will mean virtualListViewError. However, the discussion on the controlError result code below provides a set of guidelines for determining which of these result codes is actually intended for a response whose result code has a numeric value of 76.
Defined in Specification: draft-armijo-ldap-control-error
Applicable operation types: add, bind, compare, delete, extended, modify, modify DN, search
The controlError result code was proposed in draft-armijo-ldap-control-error as a way to indicate that operation processing failed because of a problem encountered while processing one or more of the controls included in the request. This draft proposed a numeric value of 76 for this result code, which conflicts with the numeric value for the virtualListViewError result code described in draft-ietf-ldapext-ldapv3-vlv.
The draft-armijo-ldap-control-error draft didn’t get as much traction as draft-ietf-ldapext-ldapv3-vlv did (a number of directory servers support the virtual list view request control, and therefore presumably assume that a result code with numeric value 76 means virtualListViewError instead of controlError), but these result codes are very similar and not really all that incompatible. In fact, controlError is a more general result code that encapsulates the meaning of virtualListViewError, but that could also be used to indicate a problem with other types of controls.
If you receive a response with a numeric value of 76, you can use the following criteria to determine whether that result code indicates controlError or virtualListViewError:
- If the response is not a search result done response, then it indicates controlError, since virtualListViewErroris only applicable to search operations.
- If a search result done response does not include a virtual list view response control, then it indicates controlError since any search result done response that uses the virtualListViewError result code must also include a virtual list view response control.
- If a search result done response includes a virtual list view response control, but the result code contained inside that virtual list view response control is success (0), then it indicates controlError, since any search result done response that uses the virtualListViewError result code would have a non-success result code inside the virtual list view response control.
- If a search result done response includes a virtual list view response control and the result code contained inside that virtual list view response control is not success, then it indicates virtualListViewError.
Defined in Specification: draft-zeilenga-ldap-noop
Applicable operation types: add, delete, extended, modify, modify DN
The LDAP no-operation request control may be included in a request that would create, remove, or alter information in the directory server. It requests that the server perform extended validation for the operation, but not actually make any changes to the data in the server. It can be used to determine whether an operation would have likely succeeded, but without applying the associated change.
In the event that a request including the no-operation request control succeeds up to the point at which the change would have been applied, the server should return a response with a result code of noOperation. If any problem is encountered before that point, the server should return whatever error response (including any appropriate result code, diagnostic message, matched DN, and referral URLs) would be appropriate for that problem.
Although the draft-zeilenga-ldap-noop draft does not specify a numeric value for the noOperation result code, a number of servers that implement support for this capability use a numeric value of 16654. In the event that the specification is promoted to an official RFC, IANA may or may not assign a different numeric value, but since the latest revision of the draft was published in July 2008, this may not ever be a concern.
There are a few LDAP result codes that have been proposed in draft specifications but that never made it to the big leagues of becoming an actual standard. Most of them were proposed without any numeric value, and therefore can’t be used unless a server implements the draft specification on its own and selects its own numeric values. But for completeness, these proposed result codes include:
The draft-ietf-ldapext-ldapudp specification does go as far as suggestion numeric value of 70 for the connectionRequired result code (albeit followed by a pair of question marks), but that value had already been taken by the resultsTooLarge result code from RFC 1798. This may have been intentional since the two specifications both describe an LDAP-like protocol using a UDP transport, and since RFC 1798 was obsoleted shortly thereafter by RFC 3352, but nonetheless, the reuse of a numeric value for a different purpose is a poor choice. After all, it’s not like numbers are exactly a scarce resource.
| Previous: Core LDAPv3 Result Codes | Next: Client-Side Result Codes |