Request for Comments: 4511 Novell, Inc.
Obsoletes: 2251, 2830, 3771 June 2006
Category: Standards Track
Lightweight Directory Access Protocol (LDAP): The Protocol
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document describes the protocol elements, along with their
semantics and encodings, of the Lightweight Directory Access Protocol
(LDAP). LDAP provides access to distributed directory services that
act in accordance with X.500 data and service models. These protocol
elements are based on those described in the X.500 Directory Access
Protocol (DAP).
Table of Contents
1. Introduction ....................................................3
1.1. Relationship to Other LDAP Specifications ..................3
2. Conventions .....................................................3
3. Protocol Model ..................................................4
3.1. Operation and LDAP Message Layer Relationship ..............5
4. Elements of Protocol ............................................5
4.1. Common Elements ............................................5
4.1.1. Message Envelope ....................................6
4.1.2. String Types ........................................7
4.1.3. Distinguished Name and Relative Distinguished Name ..8
4.1.4. Attribute Descriptions ..............................8
4.1.5. Attribute Value .....................................8
4.1.6. Attribute Value Assertion ...........................9
4.1.7. Attribute and PartialAttribute ......................9
4.1.8. Matching Rule Identifier ...........................10
4.1.9. Result Message .....................................10
4.1.10. Referral ..........................................12
4.1.11. Controls ..........................................14
4.2. Bind Operation ............................................16
4.2.1. Processing of the Bind Request .....................17
4.2.2. Bind Response ......................................18
4.3. Unbind Operation ..........................................18
4.4. Unsolicited Notification ..................................19
4.4.1. Notice of Disconnection ............................19
4.5. Search Operation ..........................................20
4.5.1. Search Request .....................................20
4.5.2. Search Result ......................................27
4.5.3. Continuation References in the Search Result .......28
4.6. Modify Operation ..........................................31
4.7. Add Operation .............................................33
4.8. Delete Operation ..........................................34
4.9. Modify DN Operation .......................................34
4.10. Compare Operation ........................................36
4.11. Abandon Operation ........................................36
4.12. Extended Operation .......................................37
4.13. IntermediateResponse Message .............................39
4.13.1. Usage with LDAP ExtendedRequest and
ExtendedResponse ..................................40
4.13.2. Usage with LDAP Request Controls ..................40
4.14. StartTLS Operation .......................................40
4.14.1. StartTLS Request ..................................40
4.14.2. StartTLS Response .................................41
4.14.3. Removal of the TLS Layer ..........................41
5. Protocol Encoding, Connection, and Transfer ....................42
5.1. Protocol Encoding .........................................42
5.2. Transmission Control Protocol (TCP) .......................43
5.3. Termination of the LDAP session ...........................43
6. Security Considerations ........................................43
7. Acknowledgements ...............................................45
8. Normative References ...........................................46
9. Informative References .........................................48
10. IANA Considerations ...........................................48
Appendix A. LDAP Result Codes .....................................49
A.1. Non-Error Result Codes ....................................49
A.2. Result Codes ..............................................49
Appendix B. Complete ASN.1 Definition .............................54
Appendix C. Changes ...............................................60
C.1. Changes Made to RFC 2251 ..................................60
C.2. Changes Made to RFC 2830 ..................................66
C.3. Changes Made to RFC 3771 ..................................66
1. Introduction
The Directory is "a collection of open systems cooperating to provide
directory services" [X.500]. A directory user, which may be a human
or other entity, accesses the Directory through a client (or
Directory User Agent (DUA)). The client, on behalf of the directory
user, interacts with one or more servers (or Directory System Agents
(DSA)). Clients interact with servers using a directory access
protocol.
This document details the protocol elements of the Lightweight
Directory Access Protocol (LDAP), along with their semantics.
Following the description of protocol elements, it describes the way
in which the protocol elements are encoded and transferred.
1.1. Relationship to Other LDAP Specifications
This document is an integral part of the LDAP Technical Specification
[RFC4510], which obsoletes the previously defined LDAP technical
specification, RFC 3377, in its entirety.
This document, together with [RFC4510], [RFC4513], and [RFC4512],
obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by
[RFC4510]. Sections 4.2.1 (portions) and 4.2.2 are obsoleted by
[RFC4513]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5,
4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph)
are obsoleted by [RFC4512]. The remainder of RFC 2251 is obsoleted
by this document. Appendix C.1 summarizes substantive changes in the
remainder.
This document obsoletes RFC 2830, Sections 2 and 4. The remainder of
RFC 2830 is obsoleted by [RFC4513]. Appendix C.2 summarizes
substantive changes to the remaining sections.
This document also obsoletes RFC 3771 in entirety.
2. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
to be interpreted as described in [RFC2119].
Character names in this document use the notation for code points and
names from the Unicode Standard [Unicode]. For example, the letter
"a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
Note: a glossary of terms used in Unicode can be found in [Glossary].
Information on the Unicode character encoding model can be found in
[CharModel].
The term "transport connection" refers to the underlying transport
services used to carry the protocol exchange, as well as associations
established by these services.
The term "TLS layer" refers to Transport Layer Security (TLS)
services used in providing security services, as well as associations
established by these services.
The term "SASL layer" refers to Simply Authentication and Security
Layer (SASL) services used in providing security services, as well as
associations established by these services.
The term "LDAP message layer" refers to the LDAP Message Protocol
Data Unit (PDU) services used in providing directory services, as
well as associations established by these services.
The term "LDAP session" refers to combined services (transport
connection, TLS layer, SASL layer, LDAP message layer) and their
associations.
See the table in Section 5 for an illustration of these four terms.
3. Protocol Model
The general model adopted by this protocol is one of clients
performing protocol operations against servers. In this model, a
client transmits a protocol request describing the operation to be
performed to a server. The server is then responsible for performing
the necessary operation(s) in the Directory. Upon completion of an
operation, the server typically returns a response containing
appropriate data to the requesting client.
Protocol operations are generally independent of one another. Each
operation is processed as an atomic action, leaving the directory in
a consistent state.
Although servers are required to return responses whenever such
responses are defined in the protocol, there is no requirement for
synchronous behavior on the part of either clients or servers.
Requests and responses for multiple operations generally may be
exchanged between a client and server in any order. If required,
synchronous behavior may be controlled by client applications.
The core protocol operations defined in this document can be mapped
to a subset of the X.500 (1993) Directory Abstract Service [X.511].
However, there is not a one-to-one mapping between LDAP operations
and X.500 Directory Access Protocol (DAP) operations. Server
implementations acting as a gateway to X.500 directories may need to
make multiple DAP requests to service a single LDAP request.
3.1. Operation and LDAP Message Layer Relationship
Protocol operations are exchanged at the LDAP message layer. When
the transport connection is closed, any uncompleted operations at the
LDAP message layer are abandoned (when possible) or are completed
without transmission of the response (when abandoning them is not
possible). Also, when the transport connection is closed, the client
MUST NOT assume that any uncompleted update operations have succeeded
or failed.
4. Elements of Protocol
The protocol is described using Abstract Syntax Notation One
([ASN.1]) and is transferred using a subset of ASN.1 Basic Encoding
Rules ([BER]). Section 5 specifies how the protocol elements are
encoded and transferred.
In order to support future extensions to this protocol, extensibility
is implied where it is allowed per ASN.1 (i.e., sequence, set,
choice, and enumerated types are extensible). In addition, ellipses
(...) have been supplied in ASN.1 types that are explicitly
extensible as discussed in [RFC4520]. Because of the implied
extensibility, clients and servers MUST (unless otherwise specified)
ignore trailing SEQUENCE components whose tags they do not recognize.
Changes to the protocol other than through the extension mechanisms
described here require a different version number. A client
indicates the version it is using as part of the BindRequest,
described in Section 4.2. If a client has not sent a Bind, the
server MUST assume the client is using version 3 or later.
Clients may attempt to determine the protocol versions a server
supports by reading the ’supportedLDAPVersion’ attribute from the
root DSE (DSA-Specific Entry) [RFC4512].
4.1. Common Elements
This section describes the LDAPMessage envelope Protocol Data Unit
(PDU) format, as well as data type definitions, which are used in the
protocol operations.
4.1.1. Message Envelope
For the purposes of protocol exchanges, all protocol operations are
encapsulated in a common envelope, the LDAPMessage, which is defined
as follows:
LDAPMessage ::= SEQUENCE {
messageID MessageID,
protocolOp CHOICE {
bindRequest BindRequest,
bindResponse BindResponse,
unbindRequest UnbindRequest,
searchRequest SearchRequest,
searchResEntry SearchResultEntry,
searchResDone SearchResultDone,
searchResRef SearchResultReference,
modifyRequest ModifyRequest,
modifyResponse ModifyResponse,
addRequest AddRequest,
addResponse AddResponse,
delRequest DelRequest,
delResponse DelResponse,
modDNRequest ModifyDNRequest,
modDNResponse ModifyDNResponse,
compareRequest CompareRequest,
compareResponse CompareResponse,
abandonRequest AbandonRequest,
extendedReq ExtendedRequest,
extendedResp ExtendedResponse,
...,
intermediateResponse IntermediateResponse },
controls [0] Controls OPTIONAL }
MessageID ::= INTEGER (0 .. maxInt)
maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
The ASN.1 type Controls is defined in Section 4.1.11.
The function of the LDAPMessage is to provide an envelope containing
common fields required in all protocol exchanges. At this time, the
only common fields are the messageID and the controls.
If the server receives an LDAPMessage from the client in which the
LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot
be parsed, the tag of the protocolOp is not recognized as a request,
or the encoding structures or lengths of data fields are found to be
incorrect, then the server SHOULD return the Notice of Disconnection
described in Section 4.4.1, with the resultCode set to protocolError,
and MUST immediately terminate the LDAP session as described in
Section 5.3.
In other cases where the client or server cannot parse an LDAP PDU,
it SHOULD abruptly terminate the LDAP session (Section 5.3) where
further communication (including providing notice) would be
pernicious. Otherwise, server implementations MUST return an
appropriate response to the request, with the resultCode set to
protocolError.
4.1.1.1. MessageID
All LDAPMessage envelopes encapsulating responses contain the
messageID value of the corresponding request LDAPMessage.
The messageID of a request MUST have a non-zero value different from
the messageID of any other request in progress in the same LDAP
session. The zero value is reserved for the unsolicited notification
message.
Typical clients increment a counter for each request.
A client MUST NOT send a request with the same messageID as an
earlier request in the same LDAP session unless it can be determined
that the server is no longer servicing the earlier request (e.g.,
after the final response is received, or a subsequent Bind
completes). Otherwise, the behavior is undefined. For this purpose,
note that Abandon and successfully abandoned operations do not send
responses.
4.1.2. String Types
The LDAPString is a notational convenience to indicate that, although
strings of LDAPString type encode as ASN.1 OCTET STRING types, the
[ISO10646] character set (a superset of [Unicode]) is used, encoded
following the UTF-8 [RFC3629] algorithm. Note that Unicode
characters U+0000 through U+007F are the same as ASCII 0 through 127,
respectively, and have the same single octet UTF-8 encoding. Other
Unicode characters have a multiple octet UTF-8 encoding.
LDAPString ::= OCTET STRING -- UTF-8 encoded,
-- [ISO10646] characters
The LDAPOID is a notational convenience to indicate that the
permitted value of this string is a (UTF-8 encoded) dotted-decimal
representation of an OBJECT IDENTIFIER. Although an LDAPOID is
encoded as an OCTET STRING, values are limited to the definition of
<numericoid> given in Section 1.4 of [RFC4512].
LDAPOID ::= OCTET STRING -- Constrained to <numericoid>
-- [RFC4512]
For example,
1.3.6.1.4.1.1466.1.2.3
4.1.3. Distinguished Name and Relative Distinguished Name
An LDAPDN is defined to be the representation of a Distinguished Name
(DN) after encoding according to the specification in [RFC4514].
LDAPDN ::= LDAPString
-- Constrained to <distinguishedName> [RFC4514]
A RelativeLDAPDN is defined to be the representation of a Relative
Distinguished Name (RDN) after encoding according to the
specification in [RFC4514].
RelativeLDAPDN ::= LDAPString
-- Constrained to <name-component> [RFC4514]
4.1.4. Attribute Descriptions
The definition and encoding rules for attribute descriptions are
defined in Section 2.5 of [RFC4512]. Briefly, an attribute
description is an attribute type and zero or more options.
AttributeDescription ::= LDAPString
-- Constrained to <attributedescription>
-- [RFC4512]
4.1.5. Attribute Value
A field of type AttributeValue is an OCTET STRING containing an
encoded attribute value. The attribute value is encoded according to
the LDAP-specific encoding definition of its corresponding syntax.
The LDAP-specific encoding definitions for different syntaxes and
attribute types may be found in other documents and in particular
[RFC4517].
AttributeValue ::= OCTET STRING
Note that there is no defined limit on the size of this encoding;
thus, protocol values may include multi-megabyte attribute values
(e.g., photographs).
Attribute values may be defined that have arbitrary and non-printable
syntax. Implementations MUST NOT display or attempt to decode an
attribute value if its syntax is not known. The implementation may
attempt to discover the subschema of the source entry and to retrieve
the descriptions of ’attributeTypes’ from it [RFC4512].
Clients MUST only send attribute values in a request that are valid
according to the syntax defined for the attributes.
4.1.6. Attribute Value Assertion
The AttributeValueAssertion (AVA) type definition is similar to the
one in the X.500 Directory standards. It contains an attribute
description and a matching rule ([RFC4512], Section 4.1.3) assertion
value suitable for that type. Elements of this type are typically
used to assert that the value in assertionValue matches a value of an
attribute.
AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription,
assertionValue AssertionValue }
AssertionValue ::= OCTET STRING
The syntax of the AssertionValue depends on the context of the LDAP
operation being performed. For example, the syntax of the EQUALITY
matching rule for an attribute is used when performing a Compare
operation. Often this is the same syntax used for values of the
attribute type, but in some cases the assertion syntax differs from
the value syntax. See objectIdentiferFirstComponentMatch in
[RFC4517] for an example.
4.1.7. Attribute and PartialAttribute
Attributes and partial attributes consist of an attribute description
and attribute values. A PartialAttribute allows zero values, while
Attribute requires at least one value.
PartialAttribute ::= SEQUENCE {
type AttributeDescription,
vals SET OF value AttributeValue }
Attribute ::= PartialAttribute(WITH COMPONENTS {
...,
vals (SIZE(1..MAX))})
No two of the attribute values may be equivalent as described by
Section 2.2 of [RFC4512]. The set of attribute values is unordered.
Implementations MUST NOT rely upon the ordering being repeatable.
4.1.8. Matching Rule Identifier
Matching rules are defined in Section 4.1.3 of [RFC4512]. A matching
rule is identified in the protocol by the printable representation of
either its <numericoid> or one of its short name descriptors
[RFC4512], e.g., ’caseIgnoreMatch’ or ’2.5.13.2’.
MatchingRuleId ::= LDAPString
4.1.9. Result Message
The LDAPResult is the construct used in this protocol to return
success or failure indications from servers to clients. To various
requests, servers will return responses containing the elements found
in LDAPResult to indicate the final status of the protocol operation
request.
LDAPResult ::= SEQUENCE {
resultCode ENUMERATED {
success (0),
operationsError (1),
protocolError (2),
timeLimitExceeded (3),
sizeLimitExceeded (4),
compareFalse (5),
compareTrue (6),
authMethodNotSupported (7),
strongerAuthRequired (8),
-- 9 reserved --
referral (10),
adminLimitExceeded (11),
unavailableCriticalExtension (12),
confidentialityRequired (13),
saslBindInProgress (14),
noSuchAttribute (16),
undefinedAttributeType (17),
inappropriateMatching (18),
constraintViolation (19),
attributeOrValueExists (20),
invalidAttributeSyntax (21),
-- 22-31 unused --
noSuchObject (32),
aliasProblem (33),
invalidDNSyntax (34),
-- 35 reserved for undefined isLeaf --
aliasDereferencingProblem (36),
-- 37-47 unused --
inappropriateAuthentication (48),
invalidCredentials (49),