idnits 2.17.1 draft-ietf-ldapbis-protocol-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 5 longer pages, the longest (page 3) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' scope ENUMERATED {' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([RFC1777], [RFC2119]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 227: '...e distinguished name (RDN), which MUST...' RFC 2119 keyword, line 241: '...ing or shadowing MUST ensure that they...' RFC 2119 keyword, line 275: '... Each entry MUST have an objectClass...' RFC 2119 keyword, line 296: '... Servers MUST NOT permit clients to ...' RFC 2119 keyword, line 304: '... Entries MAY contain, among others, ...' (172 more instances...) == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: - Remove "typically" from "and is typically transferred" in the first paragraph. - Change "MUST ignore elements of SEQUENCE encodings whose tags they do not recognize" to "MUST ignore tagged elements of SEQUENCE encodings that they do not recognize" in the first paragraph. - Add "See Section 5.1 for information on mapping the LDAP protocol to BER." to the first paragraph. - Change "version 3 " to "version 3 or later" in the second paragraph. - Change "protocol version" to "protocol versions" in the third paragraph. - Change "version 2 may not provide this attribute." to "version 2 MAY NOT provide this attribute, or a root DSE." in the third paragraph. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 2001) is 8500 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC2026' on line 13 looks like a reference -- Missing reference section? 'RFC2119' on line 2066 looks like a reference -- Missing reference section? 'RFC1777' on line 2055 looks like a reference -- Missing reference section? 'RFC2252' on line 2500 looks like a reference -- Missing reference section? '0' on line 2369 looks like a reference -- Missing reference section? 'ISO10646' on line 532 looks like a reference -- Missing reference section? 'RFC2044' on line 2063 looks like a reference -- Missing reference section? 'RFC2253' on line 2079 looks like a reference -- Missing reference section? '5' on line 2498 looks like a reference -- Missing reference section? '3' on line 2305 looks like a reference -- Missing reference section? 'RFC2255' on line 2083 looks like a reference -- Missing reference section? 'RFC2396' on line 2086 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 2242 looks like a reference -- Missing reference section? 'RFC2222' on line 2069 looks like a reference -- Missing reference section? 'APPLICATION 1' on line 2256 looks like a reference -- Missing reference section? '7' on line 2290 looks like a reference -- Missing reference section? 'APPLICATION 2' on line 2260 looks like a reference -- Missing reference section? 'APPLICATION 3' on line 2262 looks like a reference -- Missing reference section? '1' on line 2370 looks like a reference -- Missing reference section? '2' on line 2304 looks like a reference -- Missing reference section? '4' on line 2306 looks like a reference -- Missing reference section? '6' on line 2289 looks like a reference -- Missing reference section? '8' on line 2291 looks like a reference -- Missing reference section? '9' on line 2292 looks like a reference -- Missing reference section? 'APPLICATION 4' on line 2308 looks like a reference -- Missing reference section? 'APPLICATION 19' on line 2316 looks like a reference -- Missing reference section? 'APPLICATION 5' on line 2318 looks like a reference -- Missing reference section? 'APPLICATION 6' on line 2320 looks like a reference -- Missing reference section? 'APPLICATION 7' on line 2336 looks like a reference -- Missing reference section? 'APPLICATION 8' on line 2338 looks like a reference -- Missing reference section? 'APPLICATION 9' on line 2346 looks like a reference -- Missing reference section? 'APPLICATION 10' on line 2348 looks like a reference -- Missing reference section? 'APPLICATION 11' on line 2350 looks like a reference -- Missing reference section? 'APPLICATION 12' on line 2352 looks like a reference -- Missing reference section? 'APPLICATION 13' on line 2358 looks like a reference -- Missing reference section? 'APPLICATION 14' on line 2360 looks like a reference -- Missing reference section? 'APPLICATION 15' on line 2364 looks like a reference -- Missing reference section? 'APPLICATION 16' on line 2366 looks like a reference -- Missing reference section? 'APPLICATION 23' on line 2368 looks like a reference -- Missing reference section? 'APPLICATION 24' on line 2372 looks like a reference -- Missing reference section? '10' on line 2374 looks like a reference -- Missing reference section? '11' on line 2375 looks like a reference -- Missing reference section? 'RFC1823' on line 2058 looks like a reference -- Missing reference section? 'RFC2234' on line 2072 looks like a reference -- Missing reference section? 'RFC2829' on line 2705 looks like a reference -- Missing reference section? 'RFC2830' on line 2699 looks like a reference -- Missing reference section? 'RFC 1823' on line 2504 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 50 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft J. Sermersheim 3 Intended Category: Standard Track Novell, Inc 4 Document: draft-ietf-ldapbis-protocol-00.txt January 2001 5 Obsoletes: RFC 2251 7 Lightweight Directory Access Protocol (v3) 9 1. Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of [RFC2026]. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Distribution of this memo is unlimited. Technical discussion of this 29 document will take place on the IETF LDAP Revision Working Group 30 (LDAPbis) mailing list . Please send 31 editorial comments directly to the editor . 33 Table of Contents 35 1. Status of this Memo..............................................1 36 2. Abstract.........................................................3 37 3. Models...........................................................4 38 3.1. Protocol Model.................................................4 39 3.2. Data Model.....................................................4 40 3.2.1. Attributes of Entries........................................5 41 3.2.2. Subschema Entries and Subentries.............................6 42 3.3. Relationship to X.500..........................................7 43 3.4. Server-specific Data Requirements..............................7 44 4. Elements of Protocol.............................................8 45 4.1. Common Elements................................................8 46 4.1.1. Message Envelope.............................................9 47 4.1.1.1. Message ID................................................10 48 4.1.2. String Types................................................10 49 4.1.3. Distinguished Name and Relative Distinguished Name..........10 50 4.1.4. Attribute Type..............................................11 51 4.1.5. Attribute Description.......................................12 52 4.1.5.1. Binary Option.............................................12 53 4.1.6. Attribute Value.............................................13 54 Lightweight Directory Access Protocol Version 3 56 4.1.7. Attribute Value Assertion...................................13 57 4.1.8. Attribute...................................................14 58 4.1.9. Matching Rule Identifier....................................14 59 4.1.10. Result Message.............................................14 60 4.1.11. Referral...................................................16 61 4.1.12. Controls...................................................17 62 4.2. Bind Operation................................................18 63 4.2.1. Sequencing of the Bind Request..............................19 64 4.2.2. Authentication and Other Security Services..................20 65 4.2.3. Bind Response...............................................20 66 4.3. Unbind Operation..............................................21 67 4.4. Unsolicited Notification......................................22 68 4.4.1. Notice of Disconnection.....................................22 69 4.5. Search Operation..............................................23 70 4.5.1. Search Request..............................................23 71 4.5.2. Search Result...............................................26 72 4.5.3. Continuation References in the Search Result................28 73 4.6. Modify Operation..............................................29 74 4.7. Add Operation.................................................31 75 4.8. Delete Operation..............................................32 76 4.9. Modify DN Operation...........................................32 77 4.10. Compare Operation............................................33 78 4.11. Abandon Operation............................................34 79 4.12. Extended Operation...........................................34 80 5. Protocol Element Encodings and Transfer.........................35 81 5.1. Mapping Onto BER-based Transport Services.....................35 82 5.2. Transfer Protocols............................................36 83 5.2.1. Transmission Control Protocol (TCP).........................36 84 6. Implementation Guidelines.......................................36 85 6.1. Server Implementations........................................36 86 6.2. Client Implementations........................................36 87 7. Security Considerations.........................................36 88 8. Acknowledgements................................................37 89 9. Bibliography....................................................37 90 10. Editor's Address...............................................38 91 Appendix A - Complete ASN.1 Definition.............................39 92 Appendix B - Change History........................................44 93 Changes made to RFC 2251:..........................................44 94 B.1 Editorial......................................................44 95 B.2 Section 1......................................................44 96 B.3 Section 9......................................................44 97 Appendix C - Outstanding Work Items................................44 98 C.1 Integrate result codes draft...................................44 99 C.2 Section 3.1....................................................44 100 C.3 Section 4......................................................44 101 C.4 Section 4.1.1..................................................44 102 C.5 Section 4.1.1.1................................................45 103 C.6 Section 4.1.2..................................................45 104 C.7 Section 4.1.4..................................................45 105 C.8 Section 4.1.5..................................................45 106 C.9 Section 4.1.5.1................................................45 107 C.10 Section 4.1.6.................................................45 108 C.11 Section 4.1.7.................................................46 109 C.12 Section 4.1.8.................................................46 110 Lightweight Directory Access Protocol Version 3 112 C.13 Section 4.1.11................................................46 113 C.14 Section 4.1.12................................................46 114 C.15 Section 4.2...................................................46 115 C.16 Section 4.2.1.................................................47 116 C.17 Section 4.2.2.................................................47 117 C.18 Section 4.2.3.................................................47 118 C.19 Section 4.3...................................................47 119 C.20 Section 4.4...................................................47 120 C.21 Section 4.5.1.................................................47 121 C.22 Section 4.5.2.................................................48 122 C.23 Section 4.5.3.................................................48 123 C.24 Section 4.5.3.1...............................................48 124 C.25 Section 4.6...................................................48 125 C.26 Section 4.7...................................................48 126 C.27 Section 4.10..................................................49 127 C.28 Section 4.11..................................................49 128 C.29 Section 4.12..................................................49 129 C.30 Section 5.1...................................................49 130 C.31 Section 5.2.1.................................................49 131 C.32 Section 6.1...................................................49 132 C.33 Section 7.....................................................49 133 C.34 Section 8.....................................................50 134 C.36 Various sections..............................................50 136 2. Abstract 138 The protocol described in this document is designed to provide access 139 to directories supporting the [X.500] models, while not incurring the 140 resource requirements of the X.500 Directory Access Protocol (DAP). 141 This protocol is specifically targeted at management applications and 142 browser applications that provide read/write interactive access to 143 directories. When used with a directory supporting the X.500 144 protocols, it is intended to be a complement to the X.500 DAP. 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 148 to be interpreted as described in [RFC2119]. 150 Key aspects of this version of LDAP are: 152 - All protocol elements of LDAPv2 [RFC1777] are supported. The 153 protocol is carried directly over TCP or other transport, 154 bypassing much of the session/presentation overhead of X.500 DAP. 156 - Most protocol data elements can be encoded as ordinary strings 157 (e.g., Distinguished Names). 159 - Referrals to other servers may be returned. 161 - SASL mechanisms may be used with LDAP to provide association 162 security services. 164 - Attribute values and Distinguished Names have been 165 internationalized through the use of the ISO 10646 character set. 167 Lightweight Directory Access Protocol Version 3 169 - The protocol can be extended to support new operations, and 170 controls may be used to extend existing operations. 172 - Schema is published in the directory to be used by clients. 174 3. Models 176 Interest in X.500 directory technologies in the Internet has led to 177 efforts to reduce the high cost of entry associated with use of these 178 technologies. This document continues the efforts to define directory 179 protocol alternatives, updating the LDAPv2 protocol specification. 181 3.1. Protocol Model 183 The general model adopted by this protocol is one of clients 184 performing protocol operations against servers. In this model, a 185 client transmits a protocol request describing the operation to be 186 performed to a server. The server is then responsible for performing 187 the necessary operation(s) in the directory. Upon completion of the 188 operation(s), the server returns a response containing any results or 189 errors to the requesting client. 191 In keeping with the goal of easing the costs associated with use of 192 the directory, it is an objective of this protocol to minimize the 193 complexity of clients so as to facilitate widespread deployment of 194 applications capable of using the directory. 196 Note that although servers are required to return responses whenever 197 such responses are defined in the protocol, there is no requirement 198 for synchronous behavior on the part of either clients or servers. 199 Requests and responses for multiple operations may be exchanged 200 between a client and server in any order, provided the client 201 eventually receives a response for every request that requires one. 203 In LDAP versions 1 and 2, no provision was made for protocol servers 204 returning referrals to clients. However, for improved performance and 205 distribution, this version of the protocol permits servers to return 206 to clients, referrals to other servers. This allows servers to 207 offload the work of contacting other servers to progress operations. 209 Note that the core protocol operations defined in this document can 210 be mapped to a strict subset of the X.500(1997) directory abstract 211 service, so it can be cleanly provided by the DAP. However there is 212 not a one-to-one mapping between LDAP protocol operations and DAP 213 operations: server implementations acting as a gateway to X.500 214 directories may need to make multiple DAP requests. 216 217 3.2. Data Model 219 This section provides a brief introduction to the X.500 data model, 220 as used by LDAP. 222 Lightweight Directory Access Protocol Version 3 224 The LDAP protocol assumes there are one or more servers which jointly 225 provide access to a Directory Information Tree (DIT). The tree is 226 made up of entries. Entries have names: one or more attribute values 227 from the entry form its relative distinguished name (RDN), which MUST 228 be unique among all its siblings. The concatenation of the relative 229 distinguished names of the sequence of entries from a particular 230 entry to an immediate subordinate of the root of the tree forms that 231 entry's Distinguished Name (DN), which is unique in the tree. An 232 example of a Distinguished Name is: 234 CN=Steve Kille, O=Isode Limited, C=GB 236 Some servers may hold cache or shadow copies of entries, which can be 237 used to answer search and comparison queries, but will return 238 referrals or contact other servers if modification operations are 239 requested. 241 Servers that perform caching or shadowing MUST ensure that they do 242 not violate any access control constraints placed on the data by the 243 originating server. 245 The largest collection of entries, starting at an entry that is 246 mastered by a particular server, and including all its subordinates 247 and their subordinates, down to the entries which are mastered by 248 different servers, is termed a naming context. The root of the DIT is 249 a DSA-specific Entry (DSE) and not part of any naming context: each 250 server has different attribute values in the root DSE. (DSA is an 251 X.500 term for the directory server). 253 3.2.1. Attributes of Entries 255 Entries consist of a set of attributes. An attribute is a type with 256 one or more associated values. The attribute type is identified by a 257 short descriptive name and an OID (object identifier). The attribute 258 type governs whether there can be more than one value of an attribute 259 of that type in an entry, the syntax to which the values must 260 conform, the kinds of matching which can be performed on values of 261 that attribute, and other functions. 263 An example of an attribute is "mail". There may be one or more values 264 of this attribute, they must be IA5 (ASCII) strings, and they are 265 case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM"). 267 Schema is the collection of attribute type definitions, object class 268 definitions and other information which a server uses to determine 269 how to match a filter or attribute value assertion (in a compare 270 operation) against the attributes of an entry, and whether to permit 271 add and modify operations. The definition of schema for use with LDAP 272 is given in [RFC2252] and [X.501]. Additional schema elements may be 273 defined in other documents. 275 Each entry MUST have an objectClass attribute. The objectClass 276 attribute specifies the object classes of an entry, which along with 277 the system and user schema determine the permitted attributes of an 278 Lightweight Directory Access Protocol Version 3 280 entry. Values of this attribute may be modified by clients, but the 281 objectClass attribute cannot be removed. Servers may restrict the 282 modifications of this attribute to prevent the basic structural class 283 of the entry from being changed (e.g. one cannot change a person into 284 a country). When creating an entry or adding an objectClass value to 285 an entry, all superclasses of the named classes are implicitly added 286 as well if not already present, and the client must supply values for 287 any mandatory attributes of new superclasses. 289 Some attributes, termed operational attributes, are used by servers 290 for administering the directory system itself. They are not returned 291 in search results unless explicitly requested by name. Attributes 292 which are not operational, such as "mail", will have their schema and 293 syntax constraints enforced by servers, but servers will generally 294 not make use of their values. 296 Servers MUST NOT permit clients to add attributes to an entry unless 297 those attributes are permitted by the object class definitions, the 298 schema controlling that entry (specified in the subschema � see 299 below), or are operational attributes known to that server and used 300 for administrative purposes. Note that there is a particular 301 objectClass 'extensibleObject' defined in [RFC2252] which permits all 302 user attributes to be present in an entry. 304 Entries MAY contain, among others, the following operational 305 attributes, defined in [RFC2252]. These attributes are maintained 306 automatically by the server and are not modifiable by clients: 308 - creatorsName: the Distinguished Name of the user who added this 309 entry to the directory. 311 - createTimestamp: the time this entry was added to the directory. 313 - modifiersName: the Distinguished Name of the user who last 314 modified this entry. 316 - modifyTimestamp: the time this entry was last modified. 318 - subschemaSubentry: the Distinguished Name of the subschema entry 319 (or subentry) which controls the schema for this entry. 321 3.2.2. Subschema Entries and Subentries 323 Subschema entries are used for administering information about the 324 directory schema, in particular the object classes and attribute 325 types supported by directory servers. A single subschema entry 326 contains all schema definitions used by entries in a particular part 327 of the directory tree. 329 Servers which follow X.500(93) models SHOULD implement subschema 330 using the X.500 subschema mechanisms, and so these subschemas are not 331 ordinary entries. LDAP clients SHOULD NOT assume that servers 332 implement any of the other aspects of X.500 subschema. A server which 333 masters entries and permits clients to modify these entries MUST 334 Lightweight Directory Access Protocol Version 3 336 implement and provide access to these subschema entries, so that its 337 clients may discover the attributes and object classes which are 338 permitted to be present. It is strongly recommended that all other 339 servers implement this as well. 341 The following four attributes MUST be present in all subschema 342 entries: 344 - cn: this attribute MUST be used to form the RDN of the subschema 345 entry. 347 - objectClass: the attribute MUST have at least the values "top" and 348 "subschema". 350 - objectClasses: each value of this attribute specifies an object 351 class known to the server. 353 - attributeTypes: each value of this attribute specifies an 354 attribute type known to the server. 356 These are defined in [RFC2252]. Other attributes MAY be present in 357 subschema entries, to reflect additional supported capabilities. 359 These include matchingRules, matchingRuleUse, dITStructureRules, 360 dITContentRules, nameForms and ldapSyntaxes. 362 Servers SHOULD provide the attributes createTimestamp and 363 modifyTimestamp in subschema entries, in order to allow clients to 364 maintain their caches of schema information. 366 Clients MUST only retrieve attributes from a subschema entry by 367 requesting a base object search of the entry, where the search filter 368 is "(objectClass=subschema)". This will allow LDAPv3 servers which 369 gateway to X.500(93) to detect that subentry information is being 370 requested. 372 3.3. Relationship to X.500 374 This document defines LDAP in terms of X.500 as an X.500 access 375 mechanism. An LDAP server MUST act in accordance with the X.500(1993) 376 series of ITU recommendations when providing the service. However, it 377 is not required that an LDAP server make use of any X.500 protocols 378 in providing this service, e.g. LDAP can be mapped onto any other 379 directory system so long as the X.500 data and service model as used 380 in LDAP is not violated in the LDAP interface. 382 3.4. Server-specific Data Requirements 384 An LDAP server MUST provide information about itself and other 385 information that is specific to each server. This is represented as a 386 group of attributes located in the root DSE (DSA-Specific Entry), 387 which is named with the zero-length LDAPDN. These attributes are 388 retrievable if a client performs a base object search of the root 389 with filter "(objectClass=*)", however they are subject to access 390 Lightweight Directory Access Protocol Version 3 392 control restrictions. The root DSE MUST NOT be included if the client 393 performs a subtree search starting from the root. 395 Servers may allow clients to modify these attributes. 397 The following attributes of the root DSE are defined in section 5 of 398 [RFC2252]. Additional attributes may be defined in other documents. 400 - namingContexts: naming contexts held in the server. Naming 401 contexts are defined in section 17 of [X.501]. 403 - subschemaSubentry: subschema entries (or subentries) known by this 404 server. 406 - altServer: alternative servers in case this one is later 407 unavailable. 409 - supportedExtension: list of supported extended operations. 411 - supportedControl: list of supported controls. 413 - supportedSASLMechanisms: list of supported SASL security features. 415 - supportedLDAPVersion: LDAP versions implemented by the server. 417 If the server does not master entries and does not know the locations 418 of schema information, the subschemaSubentry attribute is not present 419 in the root DSE. If the server masters directory entries under one or 420 more schema rules, there may be any number of values of the 421 subschemaSubentry attribute in the root DSE. 423 4. Elements of Protocol 425 The LDAP protocol is described using Abstract Syntax Notation 1 426 (ASN.1) [X.680], and is typically transferred using a subset of ASN.1 427 Basic Encoding Rules [X.690] In order to support future extensions to 428 this protocol, clients and servers MUST ignore elements of SEQUENCE 429 encodings whose tags they do not recognize. 431 Note that unlike X.500, each change to the LDAP protocol other than 432 through the extension mechanisms will have a different version 433 number. A client will indicate the version it supports as part of the 434 bind request, described in section 4.2. If a client has not sent a 435 bind, the server MUST assume that version 3 is supported in the 436 client (since version 2 required that the client bind first). 438 Clients may determine the protocol version a server supports by 439 reading the supportedLDAPVersion attribute from the root DSE. Servers 440 which implement version 3 or later versions MUST provide this 441 attribute. Servers which only implement version 2 may not provide 442 this attribute. 444 4.1. Common Elements 445 Lightweight Directory Access Protocol Version 3 447 This section describes the LDAPMessage envelope PDU (Protocol Data 448 Unit) format, as well as data type definitions, which are used in the 449 protocol operations. 451 4.1.1. Message Envelope 453 For the purposes of protocol exchanges, all protocol operations are 454 encapsulated in a common envelope, the LDAPMessage, which is defined 455 as follows: 457 LDAPMessage ::= SEQUENCE { 458 messageID MessageID, 459 protocolOp CHOICE { 460 bindRequest BindRequest, 461 bindResponse BindResponse, 462 unbindRequest UnbindRequest, 463 searchRequest SearchRequest, 464 searchResEntry SearchResultEntry, 465 searchResDone SearchResultDone, 466 searchResRef SearchResultReference, 467 modifyRequest ModifyRequest, 468 modifyResponse ModifyResponse, 469 addRequest AddRequest, 470 addResponse AddResponse, 471 delRequest DelRequest, 472 delResponse DelResponse, 473 modDNRequest ModifyDNRequest, 474 modDNResponse ModifyDNResponse, 475 compareRequest CompareRequest, 476 compareResponse CompareResponse, 477 abandonRequest AbandonRequest, 478 extendedReq ExtendedRequest, 479 extendedResp ExtendedResponse }, 480 controls [0] Controls OPTIONAL } 482 MessageID ::= INTEGER (0 .. maxInt) 484 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 486 The function of the LDAPMessage is to provide an envelope containing 487 common fields required in all protocol exchanges. At this time the 488 only common fields are the message ID and the controls. 490 If the server receives a PDU from the client in which the LDAPMessage 491 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 492 the tag of the protocolOp is not recognized as a request, or the 493 encoding structures or lengths of data fields are found to be 494 incorrect, then the server MUST return the notice of disconnection 495 described in section 4.4.1, with resultCode protocolError, and 496 immediately close the connection. In other cases that the server 497 cannot parse the request received by the client, the server MUST 498 return an appropriate response to the request, with the resultCode 499 set to protocolError. 501 Lightweight Directory Access Protocol Version 3 503 If the client receives a PDU from the server, which cannot be parsed, 504 the client may discard the PDU, or may abruptly close the connection. 506 The ASN.1 type Controls is defined in section 4.1.12. 508 4.1.1.1. Message ID 510 All LDAPMessage envelopes encapsulating responses contain the 511 messageID value of the corresponding request LDAPMessage. 513 The message ID of a request MUST have a value different from the 514 values of any other requests outstanding in the LDAP session of which 515 this message is a part. 517 A client MUST NOT send a second request with the same message ID as 518 an earlier request on the same connection if the client has not 519 received the final response from the earlier request. Otherwise the 520 behavior is undefined. Typical clients increment a counter for each 521 request. 523 A client MUST NOT reuse the message id of an abandonRequest of the 524 abandoned operation until it has received a response from the server 525 for another request invoked subsequent to the abandonRequest, as the 526 abandonRequest itself does not have a response. 528 4.1.2. String Types 530 The LDAPString is a notational convenience to indicate that, although 531 strings of LDAPString type encode as OCTET STRING types, the 532 [ISO10646] character set (a superset of Unicode) is used, encoded 533 following the UTF-8 algorithm [RFC2044]. Note that in the UTF-8 534 algorithm characters which are the same as ASCII (0x0000 through 535 0x007F) are represented as that same ASCII character in a single 536 byte. The other byte values are used to form a variable-length 537 encoding of an arbitrary character. 539 LDAPString ::= OCTET STRING 541 The LDAPOID is a notational convenience to indicate that the 542 permitted value of this string is a (UTF-8 encoded) dotted-decimal 543 representation of an OBJECT IDENTIFIER. 545 LDAPOID ::= OCTET STRING 547 For example, 549 1.3.6.1.4.1.1466.1.2.3 551 4.1.3. Distinguished Name and Relative Distinguished Name 553 An LDAPDN and a RelativeLDAPDN are respectively defined to be the 554 representation of a Distinguished Name and a Relative Distinguished 555 Name after encoding according to the specification in [RFC2253], such 556 that: 558 Lightweight Directory Access Protocol Version 3 560 distinguished-name = name 562 relative-distinguished-name = name-component 564 where name and name-component are as defined in [RFC2253]. 566 LDAPDN ::= LDAPString 568 RelativeLDAPDN ::= LDAPString 570 Only Attribute Types can be present in a relative distinguished name 571 component--the options of Attribute Descriptions (next section) MUST 572 NOT be used in specifying distinguished names. 574 4.1.4. Attribute Type 576 An AttributeType takes on as its value the textual string associated 577 with that AttributeType in its specification. 579 AttributeType ::= LDAPString 581 Each attribute type has a unique OBJECT IDENTIFIER which has been 582 assigned to it. This identifier may be written as decimal digits with 583 components separated by periods, e.g. "2.5.4.10". 585 A specification may also assign one or more textual names for an 586 attribute type. These names MUST begin with a letter, and only 587 contain ASCII letters, digit characters and hyphens. They are case 588 insensitive. These ASCII characters are identical to ISO 10646 589 characters whose UTF-8 encoding is a single byte between 0x00 and 590 0x7F. 592 If the server has a textual name for an attribute type, it MUST use a 593 textual name for attributes returned in search results. The dotted- 594 decimal OBJECT IDENTIFIER is only used if there is no textual name 595 for an attribute type. 597 Attribute type textual names are non-unique, as two different 598 specifications (neither in standards track RFCs) may choose the same 599 name. 601 A server which masters or shadows entries SHOULD list all the 602 attribute types it supports in the subschema entries, using the 603 attributeTypes attribute. Servers which support an open-ended set of 604 attributes SHOULD include at least the attributeTypes value for the 605 'objectClass' attribute. Clients MAY retrieve the attributeTypes 606 value from subschema entries in order to obtain the OBJECT IDENTIFIER 607 and other information associated with attribute types. 609 Some attribute type names which are used in this version of LDAP are 610 described in [RFC2252]. Servers may implement additional attribute 611 types. 613 Lightweight Directory Access Protocol Version 3 615 4.1.5. Attribute Description 617 An AttributeDescription is a superset of the definition of the 618 AttributeType. It has the same ASN.1 definition, but allows 619 additional options to be specified. They are also case insensitive. 621 AttributeDescription ::= LDAPString 623 A value of AttributeDescription is based on the following BNF: 625 ::= [ ";" ] 627 ::=