rfc4511.txt

Network Working Group                                J. Sermersheim, Ed.
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



Sermersheim                 Standards Track                     [Page 1]

RFC 4511                         LDAPv3                        June 2006


           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








Sermersheim                 Standards Track                     [Page 2]

RFC 4511                         LDAPv3                        June 2006


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>.






Sermersheim                 Standards Track                     [Page 3]

RFC 4511                         LDAPv3                        June 2006


   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.





Sermersheim                 Standards Track                     [Page 4]

RFC 4511                         LDAPv3                        June 2006


   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.




Sermersheim                 Standards Track                     [Page 5]

RFC 4511                         LDAPv3                        June 2006


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



Sermersheim                 Standards Track                     [Page 6]

RFC 4511                         LDAPv3                        June 2006


   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




Sermersheim                 Standards Track                     [Page 7]

RFC 4511                         LDAPv3                        June 2006


   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






Sermersheim                 Standards Track                     [Page 8]

RFC 4511                         LDAPv3                        June 2006


   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 }






Sermersheim                 Standards Track                     [Page 9]

RFC 4511                         LDAPv3                        June 2006


        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),



Sermersheim                 Standards Track                    [Page 10]

RFC 4511                         LDAPv3                        June 2006


                       -- 22-31 unused --
                  noSuchObject                 (32),
                  aliasProblem                 (33),
                  invalidDNSyntax              (34),
                       -- 35 reserved for undefined isLeaf --
                  aliasDereferencingProblem    (36),
                       -- 37-47 unused --
                  inappropriateAuthentication  (48),
                  invalidCredentials           (49),
                  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.





Sermersheim                 Standards Track                    [Page 11]

RFC 4511                         LDAPv3                        June 2006


   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



Sermersheim                 Standards Track                    [Page 12]

RFC 4511                         LDAPv3                        June 2006


   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].






Sermersheim                 Standards Track                    [Page 13]

RFC 4511                         LDAPv3                        June 2006


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.





Sermersheim                 Standards Track                    [Page 14]

RFC 4511                         LDAPv3                        June 2006


   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.




Sermersheim                 Standards Track                    [Page 15]

RFC 4511                         LDAPv3                        June 2006


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.






Sermersheim                 Standards Track                    [Page 16]

RFC 4511                         LDAPv3                        June 2006


     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.








Sermersheim                 Standards Track                    [Page 17]

RFC 4511                         LDAPv3                        June 2006


   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.