error, and that all requested modifications have been performed if
the Modify Response indicates successful completion of the Modify
operation. Whether or not the modification was applied cannot be
determined by the client if the Modify Response was not received
(e.g., the LDAP session was terminated or the Modify operation was
abandoned).
Servers MUST ensure that entries conform to user and system schema
rules or other data model constraints. The Modify operation cannot
be used to remove from an entry any of its distinguished values,
i.e., those values which form the entry’s relative distinguished
name. An attempt to do so will result in the server returning the
notAllowedOnRDN result code. The Modify DN operation described in
Section 4.9 is used to rename an entry.
For attribute types that specify no equality matching, the rules in
Section 2.5.1 of [RFC4512] are followed.
Note that due to the simplifications made in LDAP, there is not a
direct mapping of the changes in an LDAP ModifyRequest onto the
changes of a DAP ModifyEntry operation, and different implementations
of LDAP-DAP gateways may use different means of representing the
change. If successful, the final effect of the operations on the
entry MUST be identical.
4.7. Add Operation
The Add operation allows a client to request the addition of an entry
into the Directory. The Add Request is defined as follows:
AddRequest ::= [APPLICATION 8] SEQUENCE {
entry LDAPDN,
attributes AttributeList }
AttributeList ::= SEQUENCE OF attribute Attribute
Fields of the Add Request are:
- entry: the name of the entry to be added. The server SHALL NOT
dereference any aliases in locating the entry to be added.
- attributes: the list of attributes that, along with those from the
RDN, make up the content of the entry being added. Clients MAY or
MAY NOT include the RDN attribute(s) in this list. Clients MUST
NOT supply NO-USER-MODIFICATION attributes such as the
createTimestamp or creatorsName attributes, since the server
maintains these automatically.
Servers MUST ensure that entries conform to user and system schema
rules or other data model constraints. For attribute types that
specify no equality matching, the rules in Section 2.5.1 of [RFC4512]
are followed (this applies to the naming attribute in addition to any
multi-valued attributes being added).
The entry named in the entry field of the AddRequest MUST NOT exist
for the AddRequest to succeed. The immediate superior (parent) of an
object or alias entry to be added MUST exist. For example, if the
client attempted to add <CN=JS,DC=Example,DC=NET>, the
<DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
exist, then the server would return the noSuchObject result code with
the matchedDN field containing <DC=NET>.
Upon receipt of an Add Request, a server will attempt to add the
requested entry. The result of the Add attempt will be returned to
the client in the Add Response, defined as follows:
AddResponse ::= [APPLICATION 9] LDAPResult
A response of success indicates that the new entry has been added to
the Directory.
4.8. Delete Operation
The Delete operation allows a client to request the removal of an
entry from the Directory. The Delete Request is defined as follows:
DelRequest ::= [APPLICATION 10] LDAPDN
The Delete Request consists of the name of the entry to be deleted.
The server SHALL NOT dereference aliases while resolving the name of
the target entry to be removed.
Only leaf entries (those with no subordinate entries) can be deleted
with this operation.
Upon receipt of a Delete Request, a server will attempt to perform
the entry removal requested and return the result in the Delete
Response defined as follows:
DelResponse ::= [APPLICATION 11] LDAPResult
4.9. Modify DN Operation
The Modify DN operation allows a client to change the Relative
Distinguished Name (RDN) of an entry in the Directory and/or to move
a subtree of entries to a new location in the Directory. The Modify
DN Request is defined as follows:
ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
entry LDAPDN,
newrdn RelativeLDAPDN,
deleteoldrdn BOOLEAN,
newSuperior [0] LDAPDN OPTIONAL }
Fields of the Modify DN Request are:
- entry: the name of the entry to be changed. This entry may or may
not have subordinate entries.
- newrdn: the new RDN of the entry. The value of the old RDN is
supplied when moving the entry to a new superior without changing
its RDN. Attribute values of the new RDN not matching any
attribute value of the entry are added to the entry, and an
appropriate error is returned if this fails.
- deleteoldrdn: a boolean field that controls whether the old RDN
attribute values are to be retained as attributes of the entry or
deleted from the entry.
- newSuperior: if present, this is the name of an existing object
entry that becomes the immediate superior (parent) of the
existing entry.
The server SHALL NOT dereference any aliases in locating the objects
named in entry or newSuperior.
Upon receipt of a ModifyDNRequest, a server will attempt to perform
the name change and return the result in the Modify DN Response,
defined as follows:
ModifyDNResponse ::= [APPLICATION 13] LDAPResult
For example, if the entry named in the entry field was <cn=John
Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the
newSuperior field was absent, then this operation would attempt to
rename the entry as <cn=John Cougar Smith,c=US>. If there was
already an entry with that name, the operation would fail with the
entryAlreadyExists result code.
Servers MUST ensure that entries conform to user and system schema
rules or other data model constraints. For attribute types that
specify no equality matching, the rules in Section 2.5.1 of [RFC4512]
are followed (this pertains to newrdn and deleteoldrdn).
The object named in newSuperior MUST exist. For example, if the
client attempted to add <CN=JS,DC=Example,DC=NET>, the
<DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did
exist, then the server would return the noSuchObject result code with
the matchedDN field containing <DC=NET>.
If the deleteoldrdn field is TRUE, the attribute values forming the
old RDN (but not the new RDN) are deleted from the entry. If the
deleteoldrdn field is FALSE, the attribute values forming the old RDN
will be retained as non-distinguished attribute values of the entry.
Note that X.500 restricts the ModifyDN operation to affect only
entries that are contained within a single server. If the LDAP
server is mapped onto DAP, then this restriction will apply, and the
affectsMultipleDSAs result code will be returned if this error
occurred. In general, clients MUST NOT expect to be able to perform
arbitrary movements of entries and subtrees between servers or
between naming contexts.
4.10. Compare Operation
The Compare operation allows a client to compare an assertion value
with the values of a particular attribute in a particular entry in
the Directory. The Compare Request is defined as follows:
CompareRequest ::= [APPLICATION 14] SEQUENCE {
entry LDAPDN,
ava AttributeValueAssertion }
Fields of the Compare Request are:
- entry: the name of the entry to be compared. The server SHALL NOT
dereference any aliases in locating the entry to be compared.
- ava: holds the attribute value assertion to be compared.
Upon receipt of a Compare Request, a server will attempt to perform
the requested comparison and return the result in the Compare
Response, defined as follows:
CompareResponse ::= [APPLICATION 15] LDAPResult
The resultCode is set to compareTrue, compareFalse, or an appropriate
error. compareTrue indicates that the assertion value in the ava
field matches a value of the attribute or subtype according to the
attribute’s EQUALITY matching rule. compareFalse indicates that the
assertion value in the ava field and the values of the attribute or
subtype did not match. Other result codes indicate either that the
result of the comparison was Undefined (Section 4.5.1.7), or that
some error occurred.
Note that some directory systems may establish access controls that
permit the values of certain attributes (such as userPassword) to be
compared but not interrogated by other means.
4.11. Abandon Operation
The function of the Abandon operation is to allow a client to request
that the server abandon an uncompleted operation. The Abandon
Request is defined as follows:
AbandonRequest ::= [APPLICATION 16] MessageID
The MessageID is that of an operation that was requested earlier at
this LDAP message layer. The Abandon request itself has its own
MessageID. This is distinct from the MessageID of the earlier
operation being abandoned.
There is no response defined in the Abandon operation. Upon receipt
of an AbandonRequest, the server MAY abandon the operation identified
by the MessageID. Since the client cannot tell the difference
between a successfully abandoned operation and an uncompleted
operation, the application of the Abandon operation is limited to
uses where the client does not require an indication of its outcome.
Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned.
In the event that a server receives an Abandon Request on a Search
operation in the midst of transmitting responses to the Search, that
server MUST cease transmitting entry responses to the abandoned
request immediately, and it MUST NOT send the SearchResultDone. Of
course, the server MUST ensure that only properly encoded LDAPMessage
PDUs are transmitted.
The ability to abandon other (particularly update) operations is at
the discretion of the server.
Clients should not send Abandon requests for the same operation
multiple times, and they MUST also be prepared to receive results
from operations they have abandoned (since these might have been in
transit when the Abandon was requested or might not be able to be
abandoned).
Servers MUST discard Abandon requests for messageIDs they do not
recognize, for operations that cannot be abandoned, and for
operations that have already been abandoned.
4.12. Extended Operation
The Extended operation allows additional operations to be defined for
services not already available in the protocol; for example, to Add
operations to install transport layer security (see Section 4.14).
The Extended operation allows clients to make requests and receive
responses with predefined syntaxes and semantics. These may be
defined in RFCs or be private to particular implementations.
Each Extended operation consists of an Extended request and an
Extended response.
ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
requestName [0] LDAPOID,
requestValue [1] OCTET STRING OPTIONAL }
The requestName is a dotted-decimal representation of the unique
OBJECT IDENTIFIER corresponding to the request. The requestValue is
information in a form defined by that request, encapsulated inside an
OCTET STRING.
The server will respond to this with an LDAPMessage containing an
ExtendedResponse.
ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
COMPONENTS OF LDAPResult,
responseName [10] LDAPOID OPTIONAL,
responseValue [11] OCTET STRING OPTIONAL }
The responseName field, when present, contains an LDAPOID that is
unique for this extended operation or response. This field is
optional (even when the extension specification defines an LDAPOID
for use in this field). The field will be absent whenever the server
is unable or unwilling to determine the appropriate LDAPOID to
return, for instance, when the requestName cannot be parsed or its
value is not recognized.
Where the requestName is not recognized, the server returns
protocolError. (The server may return protocolError in other cases.)
The requestValue and responseValue fields contain information
associated with the operation. The format of these fields is defined
by the specification of the Extended operation. Implementations MUST
be prepared to handle arbitrary contents of these fields, including
zero bytes. Values that are defined in terms of ASN.1 and BER-
encoded according to Section 5.1 also follow the extensibility rules
in Section 4.
Servers list the requestName of Extended Requests they recognize in
the ’supportedExtension’ attribute in the root DSE (Section 5.1 of
[RFC4512]).
Extended operations may be specified in other documents. The
specification of an Extended operation consists of:
- the OBJECT IDENTIFIER assigned to the requestName,
- the OBJECT IDENTIFIER (if any) assigned to the responseName (note
that the same OBJECT IDENTIFIER may be used for both the
requestName and responseName),
- the format of the contents of the requestValue and responseValue
(if any), and
- the semantics of the operation.
4.13. IntermediateResponse Message
While the Search operation provides a mechanism to return multiple
response messages for a single Search request, other operations, by
nature, do not provide for multiple response messages.
The IntermediateResponse message provides a general mechanism for
defining single-request/multiple-response operations in LDAP. This
message is intended to be used in conjunction with the Extended
operation to define new single-request/multiple-response operations
or in conjunction with a control when extending existing LDAP
operations in a way that requires them to return Intermediate
response information.
It is intended that the definitions and descriptions of Extended
operations and controls that make use of the IntermediateResponse
message will define the circumstances when an IntermediateResponse
message can be sent by a server and the associated meaning of an
IntermediateResponse message sent in a particular circumstance.
IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
responseName [0] LDAPOID OPTIONAL,
responseValue [1] OCTET STRING OPTIONAL }
IntermediateResponse messages SHALL NOT be returned to the client
unless the client issues a request that specifically solicits their
return. This document defines two forms of solicitation: Extended
operation and request control. IntermediateResponse messages are
specified in documents describing the manner in which they are
solicited (i.e., in the Extended operation or request control
specification that uses them). These specifications include:
- the OBJECT IDENTIFIER (if any) assigned to the responseName,
- the format of the contents of the responseValue (if any), and
- the semantics associated with the IntermediateResponse message.
Extensions that allow the return of multiple types of
IntermediateResponse messages SHALL identify those types using unique
responseName values (note that one of these may specify no value).
Sections 4.13.1 and 4.13.2 describe additional requirements on the
inclusion of responseName and responseValue in IntermediateResponse
messages.
4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse
A single-request/multiple-response operation may be defined using a
single ExtendedRequest message to solicit zero or more
IntermediateResponse messages of one or more kinds, followed by an
ExtendedResponse message.
4.13.2. Usage with LDAP Request Controls
A control’s semantics may include the return of zero or more
IntermediateResponse messages prior to returning the final result
code for the operation. One or more kinds of IntermediateResponse
messages may be sent in response to a request control.
All IntermediateResponse messages associated with request controls
SHALL include a responseName. This requirement ensures that the
client can correctly identify the source of IntermediateResponse
messages when:
- two or more controls using IntermediateResponse messages are
included in a request for any LDAP operation or
- one or more controls using IntermediateResponse messages are
included in a request with an LDAP Extended operation that uses
IntermediateResponse messages.
4.14. StartTLS Operation
The Start Transport Layer Security (StartTLS) operation’s purpose is
to initiate installation of a TLS layer. The StartTLS operation is
defined using the Extended operation mechanism described in Section
4.12.
4.14.1. StartTLS Request
A client requests TLS establishment by transmitting a StartTLS
request message to the server. The StartTLS request is defined in
terms of an ExtendedRequest. The requestName is
"1.3.6.1.4.1.1466.20037", and the requestValue field is always
absent.
The client MUST NOT send any LDAP PDUs at this LDAP message layer
following this request until it receives a StartTLS Extended response
and, in the case of a successful response, completes TLS
negotiations.
Detected sequencing problems (particularly those detailed in Section
3.1.1 of [RFC4513]) result in the resultCode being set to
operationsError.
If the server does not support TLS (whether by design or by current
configuration), it returns with the resultCode set to protocolError
as described in Section 4.12.
4.14.2. StartTLS Response
When a StartTLS request is received, servers supporting the operation
MUST return a StartTLS response message to the requestor. The
responseName is "1.3.6.1.4.1.1466.20037" when provided (see Section
4.12). The responseValue is always absent.
If the server is willing and able to negotiate TLS, it returns the
StartTLS response with the resultCode set to success. Upon client
receipt of a successful StartTLS response, protocol peers may
commence with TLS negotiation as discussed in Section 3 of [RFC4513].
If the server is otherwise unwilling or unable to perform this
operation, the server is to return an appropriate result code
indicating the nature of the problem. For example, if the TLS
subsystem is not presently available, the server may indicate this by
returning with the resultCode set to unavailable. In cases where a
non-success result code is returned, the LDAP session is left without
a TLS layer.
4.14.3. Removal of the TLS Layer
Either the client or server MAY remove the TLS layer and leave the
LDAP message layer intact by sending and receiving a TLS closure
alert.
The initiating protocol peer sends the TLS closure alert and MUST
wait until it receives a TLS closure alert from the other peer before
sending further LDAP PDUs.
When a protocol peer receives the initial TLS closure alert, it may
choose to allow the LDAP message layer to remain intact. In this
case, it MUST immediately transmit a TLS closure alert. Following
this, it MAY send and receive LDAP PDUs.
Protocol peers MAY terminate the LDAP session after sending or
receiving a TLS closure alert.
5. Protocol Encoding, Connection, and Transfer
This protocol is designed to run over connection-oriented, reliable
transports, where the data stream is divided into octets (8-bit
units), with each octet and each bit being significant.
One underlying service, LDAP over TCP, is defined in Section 5.2.
This service is generally applicable to applications providing or
consuming X.500-based directory services on the Internet. This
specification was generally written with the TCP mapping in mind.
Specifications detailing other mappings may encounter various
obstacles.
Implementations of LDAP over TCP MUST implement the mapping as
described in Section 5.2.
This table illustrates the relationship among the different layers
involved in an exchange between two protocol peers:
+----------------------+
| LDAP message layer |
+----------------------+ > LDAP PDUs
+----------------------+ < data
| SASL layer |
+----------------------+ > SASL-protected data
+----------------------+ < data
| TLS layer |
Application +----------------------+ > TLS-protected data
------------+----------------------+ < data
Transport | transport connection |
+----------------------+
5.1. Protocol Encoding
The protocol elements of LDAP SHALL be encoded for exchange using the
Basic Encoding Rules [BER] of [ASN.1] with the following
restrictions:
- Only the definite form of length encoding is used.
- OCTET STRING values are encoded in the primitive form only.
- If the value of a BOOLEAN type is true, the encoding of the value
octet is set to hex "FF".
- If a value of a type is its default value, it is absent. Only some
BOOLEAN and INTEGER types have default values in this protocol
definition.
These restrictions are meant to ease the overhead of encoding and
decoding certain elements in BER.
These restrictions do not apply to ASN.1 types encapsulated inside of
OCTET STRING values, such as attribute values, unless otherwise
stated.
5.2. Transmission Control Protocol (TCP)
The encoded LDAPMessage PDUs are mapped directly onto the TCP
[RFC793] bytestream using the BER-based encoding described in Section
5.1. It is recommended that server implementations running over the
TCP provide a protocol listener on the Internet Assigned Numbers
Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may
instead provide a listener on a different port number. Clients MUST
support contacting servers on any valid TCP port.
5.3. Termination of the LDAP session
Termination of the LDAP session is typically initiated by the client
sending an UnbindRequest (Section 4.3), or by the server sending a
Notice of Disconnection (Section 4.4.1). In these cases, each
protocol peer gracefully terminates the LDAP session by ceasing
exchanges at the LDAP message layer, tearing down any SASL layer,
tearing down any TLS layer, and closing the transport connection.
A protocol peer may determine that the continuation of any
communication would be pernicious, and in this case, it may abruptly
terminate the session by ceasing communication and closing the
transport connection.
In either case, when the LDAP session is terminated, uncompleted
operations are handled as specified in Section 3.1.
6. Security Considerations
This version of the protocol provides facilities for simple
authentication using a cleartext password, as well as any SASL
[RFC4422] mechanism. Installing SASL and/or TLS layers can provide
integrity and other data security services.
It is also permitted that the server can return its credentials to
the client, if it chooses to do so.
Use of cleartext password is strongly discouraged where the
underlying transport service cannot guarantee confidentiality and may
result in disclosure of the password to unauthorized parties.
Servers are encouraged to prevent directory modifications by clients
that have authenticated anonymously [RFC4513].
Security considerations for authentication methods, SASL mechanisms,
and TLS are described in [RFC4513].
Note that SASL authentication exchanges do not provide data
confidentiality or integrity protection for the version or name
fields of the BindRequest or the resultCode, diagnosticMessage, or
referral fields of the BindResponse, nor for any information
contained in controls attached to Bind requests or responses. Thus,
information contained in these fields SHOULD NOT be relied on unless
it is otherwise protected (such as by establishing protections at the
transport layer).
Implementors should note that various security factors (including