insufficientAccessRights (50),
busy (51),
unavailable (52),
unwillingToPerform (53),
loopDetect (54),
-- 55-63 unused --
namingViolation (64),
objectClassViolation (65),
notAllowedOnNonLeaf (66),
notAllowedOnRDN (67),
entryAlreadyExists (68),
objectClassModsProhibited (69),
-- 70 reserved for CLDAP --
affectsMultipleDSAs (71),
-- 72-79 unused --
other (80),
... },
matchedDN LDAPDN,
diagnosticMessage LDAPString,
referral [3] Referral OPTIONAL }
The resultCode enumeration is extensible as defined in Section 3.8 of
[RFC4520]. The meanings of the listed result codes are given in
Appendix A. If a server detects multiple errors for an operation,
only one result code is returned. The server should return the
result code that best indicates the nature of the error encountered.
Servers may return substituted result codes to prevent unauthorized
disclosures.
The diagnosticMessage field of this construct may, at the server’s
option, be used to return a string containing a textual, human-
readable diagnostic message (terminal control and page formatting
characters should be avoided). As this diagnostic message is not
standardized, implementations MUST NOT rely on the values returned.
Diagnostic messages typically supplement the resultCode with
additional information. If the server chooses not to return a
textual diagnostic, the diagnosticMessage field MUST be empty.
For certain result codes (typically, but not restricted to
noSuchObject, aliasProblem, invalidDNSyntax, and
aliasDereferencingProblem), the matchedDN field is set (subject to
access controls) to the name of the last entry (object or alias) used
in finding the target (or base) object. This will be a truncated
form of the provided name or, if an alias was dereferenced while
attempting to locate the entry, of the resulting name. Otherwise,
the matchedDN field is empty.
4.1.10. Referral
The referral result code indicates that the contacted server cannot
or will not perform the operation and that one or more other servers
may be able to. Reasons for this include:
- The target entry of the request is not held locally, but the server
has knowledge of its possible existence elsewhere.
- The operation is restricted on this server -- perhaps due to a
read-only copy of an entry to be modified.
The referral field is present in an LDAPResult if the resultCode is
set to referral, and it is absent with all other result codes. It
contains one or more references to one or more servers or services
that may be accessed via LDAP or other protocols. Referrals can be
returned in response to any operation request (except Unbind and
Abandon, which do not have responses). At least one URI MUST be
present in the Referral.
During a Search operation, after the baseObject is located, and
entries are being evaluated, the referral is not returned. Instead,
continuation references, described in Section 4.5.3, are returned
when other servers would need to be contacted to complete the
operation.
Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
URI ::= LDAPString -- limited to characters permitted in
-- URIs
If the client wishes to progress the operation, it contacts one of
the supported services found in the referral. If multiple URIs are
present, the client assumes that any supported URI may be used to
progress the operation.
Clients that follow referrals MUST ensure that they do not loop
between servers. They MUST NOT repeatedly contact the same server
for the same request with the same parameters. Some clients use a
counter that is incremented each time referral handling occurs for an
operation, and these kinds of clients MUST be able to handle at least
ten nested referrals while progressing the operation.
A URI for a server implementing LDAP and accessible via TCP/IP (v4 or
v6) [RFC793][RFC791] is written as an LDAP URL according to
[RFC4516].
Referral values that are LDAP URLs follow these rules:
- If an alias was dereferenced, the <dn> part of the LDAP URL MUST be
present, with the new target object name.
- It is RECOMMENDED that the <dn> part be present to avoid ambiguity.
- If the <dn> part is present, the client uses this name in its next
request to progress the operation, and if it is not present the
client uses the same name as in the original request.
- Some servers (e.g., participating in distributed indexing) may
provide a different filter in a URL of a referral for a Search
operation.
- If the <filter> part of the LDAP URL is present, the client uses
this filter in its next request to progress this Search, and if it
is not present the client uses the same filter as it used for that
Search.
- For Search, it is RECOMMENDED that the <scope> part be present to
avoid ambiguity.
- If the <scope> part is missing, the scope of the original Search is
used by the client to progress the operation.
- Other aspects of the new request may be the same as or different
from the request that generated the referral.
Other kinds of URIs may be returned. The syntax and semantics of
such URIs is left to future specifications. Clients may ignore URIs
that they do not support.
UTF-8 encoded characters appearing in the string representation of a
DN, search filter, or other fields of the referral value may not be
legal for URIs (e.g., spaces) and MUST be escaped using the % method
in [RFC3986].
4.1.11. Controls
Controls provide a mechanism whereby the semantics and arguments of
existing LDAP operations may be extended. One or more controls may
be attached to a single LDAP message. A control only affects the
semantics of the message it is attached to.
Controls sent by clients are termed ’request controls’, and those
sent by servers are termed ’response controls’.
Controls ::= SEQUENCE OF control Control
Control ::= SEQUENCE {
controlType LDAPOID,
criticality BOOLEAN DEFAULT FALSE,
controlValue OCTET STRING OPTIONAL }
The controlType field is the dotted-decimal representation of an
OBJECT IDENTIFIER that uniquely identifies the control. This
provides unambiguous naming of controls. Often, response control(s)
solicited by a request control share controlType values with the
request control.
The criticality field only has meaning in controls attached to
request messages (except UnbindRequest). For controls attached to
response messages and the UnbindRequest, the criticality field SHOULD
be FALSE, and MUST be ignored by the receiving protocol peer. A
value of TRUE indicates that it is unacceptable to perform the
operation without applying the semantics of the control.
Specifically, the criticality field is applied as follows:
- If the server does not recognize the control type, determines that
it is not appropriate for the operation, or is otherwise unwilling
to perform the operation with the control, and if the criticality
field is TRUE, the server MUST NOT perform the operation, and for
operations that have a response message, it MUST return with the
resultCode set to unavailableCriticalExtension.
- If the server does not recognize the control type, determines that
it is not appropriate for the operation, or is otherwise unwilling
to perform the operation with the control, and if the criticality
field is FALSE, the server MUST ignore the control.
- Regardless of criticality, if a control is applied to an
operation, it is applied consistently and impartially to the
entire operation.
The controlValue may contain information associated with the
controlType. Its format is defined by the specification of the
control. Implementations MUST be prepared to handle arbitrary
contents of the controlValue octet string, including zero bytes. It
is absent only if there is no value information that is associated
with a control of its type. When a controlValue is defined in terms
of ASN.1, and BER-encoded according to Section 5.1, it also follows
the extensibility rules in Section 4.
Servers list the controlType of request controls they recognize in
the ’supportedControl’ attribute in the root DSE (Section 5.1 of
[RFC4512]).
Controls SHOULD NOT be combined unless the semantics of the
combination has been specified. The semantics of control
combinations, if specified, are generally found in the control
specification most recently published. When a combination of
controls is encountered whose semantics are invalid, not specified
(or not known), the message is considered not well-formed; thus, the
operation fails with protocolError. Controls with a criticality of
FALSE may be ignored in order to arrive at a valid combination.
Additionally, unless order-dependent semantics are given in a
specification, the order of a combination of controls in the SEQUENCE
is ignored. Where the order is to be ignored but cannot be ignored
by the server, the message is considered not well-formed, and the
operation fails with protocolError. Again, controls with a
criticality of FALSE may be ignored in order to arrive at a valid
combination.
This document does not specify any controls. Controls may be
specified in other documents. Documents detailing control extensions
are to provide for each control:
- the OBJECT IDENTIFIER assigned to the control,
- direction as to what value the sender should provide for the
criticality field (note: the semantics of the criticality field are
defined above should not be altered by the control’s
specification),
- whether the controlValue field is present, and if so, the format of
its contents,
- the semantics of the control, and
- optionally, semantics regarding the combination of the control with
other controls.
4.2. Bind Operation
The function of the Bind operation is to allow authentication
information to be exchanged between the client and server. The Bind
operation should be thought of as the "authenticate" operation.
Operational, authentication, and security-related semantics of this
operation are given in [RFC4513].
The Bind request is defined as follows:
BindRequest ::= [APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication AuthenticationChoice }
AuthenticationChoice ::= CHOICE {
simple [0] OCTET STRING,
-- 1 and 2 reserved
sasl [3] SaslCredentials,
... }
SaslCredentials ::= SEQUENCE {
mechanism LDAPString,
credentials OCTET STRING OPTIONAL }
Fields of the BindRequest are:
- version: A version number indicating the version of the protocol to
be used at the LDAP message layer. This document describes version
3 of the protocol. There is no version negotiation. The client
sets this field to the version it desires. If the server does not
support the specified version, it MUST respond with a BindResponse
where the resultCode is set to protocolError.
- name: If not empty, the name of the Directory object that the
client wishes to bind as. This field may take on a null value (a
zero-length string) for the purposes of anonymous binds ([RFC4513],
Section 5.1) or when using SASL [RFC4422] authentication
([RFC4513], Section 5.2). Where the server attempts to locate the
named object, it SHALL NOT perform alias dereferencing.
- authentication: Information used in authentication. This type is
extensible as defined in Section 3.7 of [RFC4520]. Servers that do
not support a choice supplied by a client return a BindResponse
with the resultCode set to authMethodNotSupported.
Textual passwords (consisting of a character sequence with a known
character set and encoding) transferred to the server using the
simple AuthenticationChoice SHALL be transferred as UTF-8 [RFC3629]
encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
passwords as "query" strings by applying the SASLprep [RFC4013]
profile of the stringprep [RFC3454] algorithm. Passwords
consisting of other data (such as random octets) MUST NOT be
altered. The determination of whether a password is textual is a
local client matter.
4.2.1. Processing of the Bind Request
Before processing a BindRequest, all uncompleted operations MUST
either complete or be abandoned. The server may either wait for the
uncompleted operations to complete, or abandon them. The server then
proceeds to authenticate the client in either a single-step or
multi-step Bind process. Each step requires the server to return a
BindResponse to indicate the status of authentication.
After sending a BindRequest, clients MUST NOT send further LDAP PDUs
until receiving the BindResponse. Similarly, servers SHOULD NOT
process or respond to requests received while processing a
BindRequest.
If the client did not bind before sending a request and receives an
operationsError to that request, it may then send a BindRequest. If
this also fails or the client chooses not to bind on the existing
LDAP session, it may terminate the LDAP session, re-establish it, and
begin again by first sending a BindRequest. This will aid in
interoperating with servers implementing other versions of LDAP.
Clients may send multiple Bind requests to change the authentication
and/or security associations or to complete a multi-stage Bind
process. Authentication from earlier binds is subsequently ignored.
For some SASL authentication mechanisms, it may be necessary for the
client to invoke the BindRequest multiple times ([RFC4513], Section
5.2). Clients MUST NOT invoke operations between two Bind requests
made as part of a multi-stage Bind.
A client may abort a SASL bind negotiation by sending a BindRequest
with a different value in the mechanism field of SaslCredentials, or
an AuthenticationChoice other than sasl.
If the client sends a BindRequest with the sasl mechanism field as an
empty string, the server MUST return a BindResponse with the
resultCode set to authMethodNotSupported. This will allow the client
to abort a negotiation if it wishes to try again with the same SASL
mechanism.
4.2.2. Bind Response
The Bind response is defined as follows.
BindResponse ::= [APPLICATION 1] SEQUENCE {
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
BindResponse consists simply of an indication from the server of the
status of the client’s request for authentication.
A successful Bind operation is indicated by a BindResponse with a
resultCode set to success. Otherwise, an appropriate result code is
set in the BindResponse. For BindResponse, the protocolError result
code may be used to indicate that the version number supplied by the
client is unsupported.
If the client receives a BindResponse where the resultCode is set to
protocolError, it is to assume that the server does not support this
version of LDAP. While the client may be able proceed with another
version of this protocol (which may or may not require closing and
re-establishing the transport connection), how to proceed with
another version of this protocol is beyond the scope of this
document. Clients that are unable or unwilling to proceed SHOULD
terminate the LDAP session.
The serverSaslCreds field is used as part of a SASL-defined bind
mechanism to allow the client to authenticate the server to which it
is communicating, or to perform "challenge-response" authentication.
If the client bound with the simple choice, or the SASL mechanism
does not require the server to return information to the client, then
this field SHALL NOT be included in the BindResponse.
4.3. Unbind Operation
The function of the Unbind operation is to terminate an LDAP session.
The Unbind operation is not the antithesis of the Bind operation as
the name implies. The naming of these operations are historical.
The Unbind operation should be thought of as the "quit" operation.
The Unbind operation is defined as follows:
UnbindRequest ::= [APPLICATION 2] NULL
The client, upon transmission of the UnbindRequest, and the server,
upon receipt of the UnbindRequest, are to gracefully terminate the
LDAP session as described in Section 5.3. Uncompleted operations are
handled as specified in Section 3.1.
4.4. Unsolicited Notification
An unsolicited notification is an LDAPMessage sent from the server to
the client that is not in response to any LDAPMessage received by the
server. It is used to signal an extraordinary condition in the
server or in the LDAP session between the client and the server. The
notification is of an advisory nature, and the server will not expect
any response to be returned from the client.
The unsolicited notification is structured as an LDAPMessage in which
the messageID is zero and protocolOp is set to the extendedResp
choice using the ExtendedResponse type (See Section 4.12). The
responseName field of the ExtendedResponse always contains an LDAPOID
that is unique for this notification.
One unsolicited notification (Notice of Disconnection) is defined in
this document. The specification of an unsolicited notification
consists of:
- the OBJECT IDENTIFIER assigned to the notification (to be specified
in the responseName,
- the format of the contents of the responseValue (if any),
- the circumstances which will cause the notification to be sent, and
- the semantics of the message.
4.4.1. Notice of Disconnection
This notification may be used by the server to advise the client that
the server is about to terminate the LDAP session on its own
initiative. This notification is intended to assist clients in
distinguishing between an exceptional server condition and a
transient network failure. Note that this notification is not a
response to an Unbind requested by the client. Uncompleted
operations are handled as specified in Section 3.1.
The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field
is absent, and the resultCode is used to indicate the reason for the
disconnection. When the strongerAuthRequired resultCode is returned
with this message, it indicates that the server has detected that an
established security association between the client and server has
unexpectedly failed or been compromised.
Upon transmission of the Notice of Disconnection, the server
gracefully terminates the LDAP session as described in Section 5.3.
4.5. Search Operation
The Search operation is used to request a server to return, subject
to access controls and other restrictions, a set of entries matching
a complex search criterion. This can be used to read attributes from
a single entry, from entries immediately subordinate to a particular
entry, or from a whole subtree of entries.
4.5.1. Search Request
The Search request is defined as follows:
SearchRequest ::= [APPLICATION 3] SEQUENCE {
baseObject LDAPDN,
scope ENUMERATED {
baseObject (0),
singleLevel (1),
wholeSubtree (2),
... },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3) },
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
typesOnly BOOLEAN,
filter Filter,
attributes AttributeSelection }
AttributeSelection ::= SEQUENCE OF selector LDAPString
-- The LDAPString is constrained to
-- <attributeSelector> in Section 4.5.1.8
Filter ::= CHOICE {
and [0] SET SIZE (1..MAX) OF filter Filter,
or [1] SET SIZE (1..MAX) OF filter Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeDescription,
approxMatch [8] AttributeValueAssertion,
extensibleMatch [9] MatchingRuleAssertion,
... }
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
initial [0] AssertionValue, -- can occur at most once
any [1] AssertionValue,
final [2] AssertionValue } -- can occur at most once