idnits 2.17.1 draft-ietf-ldapbis-protocol-02.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. 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 231: '...e distinguished name (RDN), which MUST...' RFC 2119 keyword, line 245: '...ing or shadowing MUST ensure that they...' RFC 2119 keyword, line 281: '... Each entry MUST have an objectClass...' RFC 2119 keyword, line 300: '... Servers MUST NOT permit clients to ...' RFC 2119 keyword, line 308: '... Entries MAY contain, among others, ...' (175 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 (July 2001) is 8321 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 2078 looks like a reference -- Missing reference section? 'RFC1777' on line 2069 looks like a reference -- Missing reference section? 'RFC2252' on line 2598 looks like a reference -- Missing reference section? '0' on line 2381 looks like a reference -- Missing reference section? 'ISO10646' on line 2049 looks like a reference -- Missing reference section? 'RFC2044' on line 2075 looks like a reference -- Missing reference section? 'RFC2253' on line 2091 looks like a reference -- Missing reference section? '5' on line 2596 looks like a reference -- Missing reference section? '3' on line 2318 looks like a reference -- Missing reference section? 'RFC2255' on line 2095 looks like a reference -- Missing reference section? 'RFC2396' on line 2098 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 2256 looks like a reference -- Missing reference section? 'RFC2222' on line 2081 looks like a reference -- Missing reference section? 'APPLICATION 1' on line 2270 looks like a reference -- Missing reference section? '7' on line 2303 looks like a reference -- Missing reference section? 'APPLICATION 2' on line 2274 looks like a reference -- Missing reference section? 'APPLICATION 3' on line 2276 looks like a reference -- Missing reference section? '1' on line 2382 looks like a reference -- Missing reference section? '2' on line 2317 looks like a reference -- Missing reference section? '4' on line 2319 looks like a reference -- Missing reference section? '6' on line 2302 looks like a reference -- Missing reference section? '8' on line 2304 looks like a reference -- Missing reference section? '9' on line 2305 looks like a reference -- Missing reference section? 'APPLICATION 4' on line 2321 looks like a reference -- Missing reference section? 'APPLICATION 19' on line 2329 looks like a reference -- Missing reference section? 'APPLICATION 5' on line 2331 looks like a reference -- Missing reference section? 'APPLICATION 6' on line 2333 looks like a reference -- Missing reference section? 'APPLICATION 7' on line 2348 looks like a reference -- Missing reference section? 'APPLICATION 8' on line 2350 looks like a reference -- Missing reference section? 'APPLICATION 9' on line 2358 looks like a reference -- Missing reference section? 'APPLICATION 10' on line 2360 looks like a reference -- Missing reference section? 'APPLICATION 11' on line 2362 looks like a reference -- Missing reference section? 'APPLICATION 12' on line 2364 looks like a reference -- Missing reference section? 'APPLICATION 13' on line 2370 looks like a reference -- Missing reference section? 'APPLICATION 14' on line 2372 looks like a reference -- Missing reference section? 'APPLICATION 15' on line 2376 looks like a reference -- Missing reference section? 'APPLICATION 16' on line 2378 looks like a reference -- Missing reference section? 'APPLICATION 23' on line 2380 looks like a reference -- Missing reference section? 'APPLICATION 24' on line 2384 looks like a reference -- Missing reference section? '10' on line 2386 looks like a reference -- Missing reference section? '11' on line 2387 looks like a reference -- Missing reference section? 'RFC1823' on line 2072 looks like a reference -- Missing reference section? 'RFC2234' on line 2084 looks like a reference -- Missing reference section? 'RFC2829' on line 2796 looks like a reference -- Missing reference section? 'RFC2830' on line 2790 looks like a reference -- Missing reference section? 'RFC 1823' on line 2604 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 50 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft Editor: J. Sermersheim 3 Intended Category: Standard Track Novell, Inc 4 Document: draft-ietf-ldapbis-protocol-02.txt July 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.....................................................5 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................................................9 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..........11 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.............................................15 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...............................................21 66 4.3. Unbind Operation..............................................22 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...............................................27 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...........................................35 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.........................................37 88 8. Acknowledgements................................................37 89 9. Bibliography....................................................37 90 10. Editor's Address...............................................38 91 Appendix A - Complete ASN.1 Definition.............................40 92 Appendix B - Change History........................................45 93 B.1 Editorial......................................................45 94 B.2 Section 1......................................................45 95 B.3 Section 9......................................................45 96 B.4 Section 4.1.6..................................................45 97 B.5 Section 4.1.7..................................................45 98 B.6 Sections 4.2, 4.9, 4.10........................................45 99 B.7 Sections 4.5 and Appendix A....................................46 100 B.7 Section 3.4....................................................46 101 B.8 Section 4.1.12.................................................46 102 B.9 Section 4.2....................................................46 103 B.10 Section 4.2.(various).........................................46 104 B.11 Section 4.2.2.................................................46 105 Appendix C - Outstanding Work Items................................46 106 C.1 Integrate result codes draft...................................46 107 C.2 Section 3.1....................................................47 108 C.3 Section 4......................................................47 109 C.4 Section 4.1.1..................................................47 110 Lightweight Directory Access Protocol Version 3 112 C.5 Section 4.1.1.1................................................47 113 C.6 Section 4.1.2..................................................47 114 C.7 Section 4.1.4..................................................47 115 C.8 Section 4.1.5..................................................48 116 C.9 Section 4.1.5.1................................................48 117 C.11 Section 4.1.7.................................................48 118 C.12 Section 4.1.8.................................................48 119 C.13 Section 4.1.11................................................49 120 C.14 Section 4.1.12................................................49 121 C.15 Section 4.2...................................................49 122 C.17 Section 4.2.2.................................................49 123 C.18 Section 4.2.3.................................................49 124 C.19 Section 4.3...................................................49 125 C.20 Section 4.4...................................................50 126 C.21 Section 4.5.1.................................................50 127 C.22 Section 4.5.2.................................................50 128 C.23 Section 4.5.3.................................................50 129 C.24 Section 4.5.3.1...............................................50 130 C.25 Section 4.6...................................................51 131 C.26 Section 4.7...................................................51 132 C.27 Section 4.10..................................................51 133 C.28 Section 4.11..................................................51 134 C.29 Section 4.12..................................................51 135 C.30 Section 5.1...................................................51 136 C.31 Section 5.2.1.................................................51 137 C.32 Section 6.1...................................................51 138 C.33 Section 7.....................................................52 140 2. Abstract 142 The protocol described in this document is designed to provide access 143 to directories supporting the [X.500] models, while not incurring the 144 resource requirements of the X.500 Directory Access Protocol (DAP). 145 This protocol is specifically targeted at management applications and 146 browser applications that provide read/write interactive access to 147 directories. When used with a directory supporting the X.500 148 protocols, it is intended to be a complement to the X.500 DAP. 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 152 to be interpreted as described in [RFC2119]. 154 Key aspects of this version of LDAP are: 156 - All protocol elements of LDAPv2 [RFC1777] are supported. The 157 protocol is carried directly over TCP or other transport, 158 bypassing much of the session/presentation overhead of X.500 DAP. 160 - Most protocol data elements can be encoded as ordinary strings 161 (e.g., Distinguished Names). 163 - Referrals to other servers may be returned. 165 Lightweight Directory Access Protocol Version 3 167 - SASL mechanisms may be used with LDAP to provide association 168 security services. 170 - Attribute values and Distinguished Names have been 171 internationalized through the use of the ISO 10646 character set. 173 - The protocol can be extended to support new operations, and 174 controls may be used to extend existing operations. 176 - Schema is published in the directory to be used by clients. 178 3. Models 180 Interest in X.500 directory technologies in the Internet has led to 181 efforts to reduce the high cost of entry associated with use of these 182 technologies. This document continues the efforts to define directory 183 protocol alternatives, updating the LDAPv2 protocol specification. 185 3.1. Protocol Model 187 The general model adopted by this protocol is one of clients 188 performing protocol operations against servers. In this model, a 189 client transmits a protocol request describing the operation to be 190 performed to a server. The server is then responsible for performing 191 the necessary operation(s) in the directory. Upon completion of the 192 operation(s), the server returns a response containing any results or 193 errors to the requesting client. 195 In keeping with the goal of easing the costs associated with use of 196 the directory, it is an objective of this protocol to minimize the 197 complexity of clients so as to facilitate widespread deployment of 198 applications capable of using the directory. 200 Note that although servers are required to return responses whenever 201 such responses are defined in the protocol, there is no requirement 202 for synchronous behavior on the part of either clients or servers. 203 Requests and responses for multiple operations may be exchanged 204 between a client and server in any order, provided the client 205 eventually receives a response for every request that requires one. 207 In LDAP versions 1 and 2, no provision was made for protocol servers 208 returning referrals to clients. However, for improved performance and 209 distribution, this version of the protocol permits servers to return 210 to clients, referrals to other servers. This allows servers to 211 offload the work of contacting other servers to progress operations. 213 Note that the core protocol operations defined in this document can 214 be mapped to a strict subset of the X.500(1997) directory abstract 215 service, so it can be cleanly provided by the DAP. However there is 216 not a one-to-one mapping between LDAP protocol operations and DAP 217 operations: server implementations acting as a gateway to X.500 218 directories may need to make multiple DAP requests. 220 221 Lightweight Directory Access Protocol Version 3 223 3.2. Data Model 225 This section provides a brief introduction to the X.500 data model, 226 as used by LDAP. 228 The LDAP protocol assumes there are one or more servers which jointly 229 provide access to a Directory Information Tree (DIT). The tree is 230 made up of entries. Entries have names: one or more attribute values 231 from the entry form its relative distinguished name (RDN), which MUST 232 be unique among all its siblings. The concatenation of the relative 233 distinguished names of the sequence of entries from a particular 234 entry to an immediate subordinate of the root of the tree forms that 235 entry's Distinguished Name (DN), which is unique in the tree. An 236 example of a Distinguished Name is: 238 CN=Steve Kille, O=Isode Limited, C=GB 240 Some servers may hold cache or shadow copies of entries, which can be 241 used to answer search and comparison queries, but will return 242 referrals or contact other servers if modification operations are 243 requested. 245 Servers that perform caching or shadowing MUST ensure that they do 246 not violate any access control constraints placed on the data by the 247 originating server. 249 The largest collection of entries, starting at an entry that is 250 mastered by a particular server, and including all its subordinates 251 and their subordinates, down to the entries which are mastered by 252 different servers, is termed a naming context. The root of the DIT is 253 a DSA-specific Entry (DSE) and not part of any naming context: each 254 server has different attribute values in the root DSE. (DSA is an 255 X.500 term for the directory server). 257 3.2.1. Attributes of Entries 259 Entries consist of a set of attributes. An attribute is a type with 260 one or more associated values. The attribute type is identified by a 261 short descriptive name and an OID (object identifier). The attribute 262 type governs whether there can be more than one value of an attribute 263 of that type in an entry, the syntax to which the values must 264 conform, the kinds of matching which can be performed on values of 265 that attribute, and other functions. 267 An example of an attribute is "mail". There may be one or more values 268 of this attribute, they must be IA5 (ASCII) strings, and they are 269 case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM"). 271 Schema is the collection of attribute type definitions, object class 272 definitions and other information which a server uses to determine 273 how to match a filter or attribute value assertion (in a compare 274 operation) against the attributes of an entry, and whether to permit 275 add and modify operations. The definition of schema for use with LDAP 276 Lightweight Directory Access Protocol Version 3 278 is given in [RFC2252] and [X.501]. Additional schema elements may be 279 defined in other documents. 281 Each entry MUST have an objectClass attribute. The objectClass 282 attribute specifies the object classes of an entry, which along with 283 the system and user schema determine the permitted attributes of an 284 entry. Values of this attribute may be modified by clients, but the 285 objectClass attribute cannot be removed. Servers may restrict the 286 modifications of this attribute to prevent the basic structural class 287 of the entry from being changed (e.g. one cannot change a person into 288 a country). When creating an entry or adding an objectClass value to 289 an entry, all superclasses of the named classes are implicitly added 290 as well if not already present, and the client must supply values for 291 any mandatory attributes of new superclasses. 293 Some attributes, termed operational attributes, are used by servers 294 for administering the directory system itself. They are not returned 295 in search results unless explicitly requested by name. Attributes 296 which are not operational, such as "mail", will have their schema and 297 syntax constraints enforced by servers, but servers will generally 298 not make use of their values. 300 Servers MUST NOT permit clients to add attributes to an entry unless 301 those attributes are permitted by the object class definitions, the 302 schema controlling that entry (specified in the subschema � see 303 below), or are operational attributes known to that server and used 304 for administrative purposes. Note that there is a particular 305 objectClass 'extensibleObject' defined in [RFC2252] which permits all 306 user attributes to be present in an entry. 308 Entries MAY contain, among others, the following operational 309 attributes, defined in [RFC2252]. These attributes are maintained 310 automatically by the server and are not modifiable by clients: 312 - creatorsName: the Distinguished Name of the user who added this 313 entry to the directory. 315 - createTimestamp: the time this entry was added to the directory. 317 - modifiersName: the Distinguished Name of the user who last 318 modified this entry. 320 - modifyTimestamp: the time this entry was last modified. 322 - subschemaSubentry: the Distinguished Name of the subschema entry 323 (or subentry) which controls the schema for this entry. 325 3.2.2. Subschema Entries and Subentries 327 Subschema entries are used for administering information about the 328 directory schema, in particular the object classes and attribute 329 types supported by directory servers. A single subschema entry 330 contains all schema definitions used by entries in a particular part 331 of the directory tree. 333 Lightweight Directory Access Protocol Version 3 335 Servers which follow X.500(93) models SHOULD implement subschema 336 using the X.500 subschema mechanisms, and so these subschemas are not 337 ordinary entries. LDAP clients SHOULD NOT assume that servers 338 implement any of the other aspects of X.500 subschema. A server which 339 masters entries and permits clients to modify these entries MUST 340 implement and provide access to these subschema entries, so that its 341 clients may discover the attributes and object classes which are 342 permitted to be present. It is strongly recommended that all other 343 servers implement this as well. 345 The following four attributes MUST be present in all subschema 346 entries: 348 - cn: this attribute MUST be used to form the RDN of the subschema 349 entry. 351 - objectClass: the attribute MUST have at least the values "top" and 352 "subschema". 354 - objectClasses: each value of this attribute specifies an object 355 class known to the server. 357 - attributeTypes: each value of this attribute specifies an 358 attribute type known to the server. 360 These are defined in [RFC2252]. Other attributes MAY be present in 361 subschema entries, to reflect additional supported capabilities. 363 These include matchingRules, matchingRuleUse, dITStructureRules, 364 dITContentRules, nameForms and ldapSyntaxes. 366 Servers SHOULD provide the attributes createTimestamp and 367 modifyTimestamp in subschema entries, in order to allow clients to 368 maintain their caches of schema information. 370 Clients MUST only retrieve attributes from a subschema entry by 371 requesting a base object search of the entry, where the search filter 372 is "(objectClass=subschema)". This will allow LDAPv3 servers which 373 gateway to X.500(93) to detect that subentry information is being 374 requested. 376 3.3. Relationship to X.500 378 This document defines LDAP in terms of X.500 as an X.500 access 379 mechanism. An LDAP server MUST act in accordance with the X.500(1993) 380 series of ITU recommendations when providing the service. However, it 381 is not required that an LDAP server make use of any X.500 protocols 382 in providing this service, e.g. LDAP can be mapped onto any other 383 directory system so long as the X.500 data and service model as used 384 in LDAP is not violated in the LDAP interface. 386 3.4. Server-specific Data Requirements 387 Lightweight Directory Access Protocol Version 3 389 An LDAP server MUST provide information about itself and other 390 information that is specific to each server. This is represented as a 391 group of attributes located in the root DSE (DSA-Specific Entry), 392 which is named with the zero-length LDAPDN. These attributes are 393 retrievable if a client performs a base object search of the root 394 with filter "(objectClass=*)", however they are subject to access 395 control restrictions. The root DSE MUST NOT be included if the client 396 performs a subtree search starting from the root. 398 Servers may allow clients to modify these attributes. 400 The following attributes of the root DSE are defined in section 5 of 401 [RFC2252]. Additional attributes may be defined in other documents. 403 - namingContexts: naming contexts held in the server. Naming 404 contexts are defined in section 17 of [X.501]. 406 - subschemaSubentry: subschema entry (or subentry) holding the 407 schema for the root DSE. 409 - altServer: alternative servers in case this one is later 410 unavailable. 412 - supportedExtension: list of supported extended operations. 414 - supportedControl: list of supported controls. 416 - supportedSASLMechanisms: list of supported SASL security features. 418 - supportedLDAPVersion: LDAP versions implemented by the server. 420 If the server does not master entries and does not know the locations 421 of schema information, the subschemaSubentry attribute is not present 422 in the root DSE. If the server masters directory entries under one or 423 more schema rules, the schema for each entry is found by reading the 424 subschemaSubentry attribute for that entry. 426 4. Elements of Protocol 428 The LDAP protocol is described using Abstract Syntax Notation 1 429 (ASN.1) [X.680], and is typically transferred using a subset of ASN.1 430 Basic Encoding Rules [X.690] In order to support future extensions to 431 this protocol, clients and servers MUST ignore elements of SEQUENCE 432 encodings whose tags they do not recognize. 434 Note that unlike X.500, each change to the LDAP protocol other than 435 through the extension mechanisms will have a different version 436 number. A client will indicate the version it supports as part of the 437 bind request, described in section 4.2. If a client has not sent a 438 bind, the server MUST assume that version 3 is supported in the 439 client (since version 2 required that the client bind first). 441 Clients may determine the protocol version a server supports by 442 reading the supportedLDAPVersion attribute from the root DSE. Servers 443 Lightweight Directory Access Protocol Version 3 445 which implement version 3 or later versions MUST provide this 446 attribute. Servers which only implement version 2 may not provide 447 this attribute. 449 4.1. Common Elements 451 This section describes the LDAPMessage envelope PDU (Protocol Data 452 Unit) format, as well as data type definitions, which are used in the 453 protocol operations. 455 4.1.1. Message Envelope 457 For the purposes of protocol exchanges, all protocol operations are 458 encapsulated in a common envelope, the LDAPMessage, which is defined 459 as follows: 461 LDAPMessage ::= SEQUENCE { 462 messageID MessageID, 463 protocolOp CHOICE { 464 bindRequest BindRequest, 465 bindResponse BindResponse, 466 unbindRequest UnbindRequest, 467 searchRequest SearchRequest, 468 searchResEntry SearchResultEntry, 469 searchResDone SearchResultDone, 470 searchResRef SearchResultReference, 471 modifyRequest ModifyRequest, 472 modifyResponse ModifyResponse, 473 addRequest AddRequest, 474 addResponse AddResponse, 475 delRequest DelRequest, 476 delResponse DelResponse, 477 modDNRequest ModifyDNRequest, 478 modDNResponse ModifyDNResponse, 479 compareRequest CompareRequest, 480 compareResponse CompareResponse, 481 abandonRequest AbandonRequest, 482 extendedReq ExtendedRequest, 483 extendedResp ExtendedResponse }, 484 controls [0] Controls OPTIONAL } 486 MessageID ::= INTEGER (0 .. maxInt) 488 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 490 The function of the LDAPMessage is to provide an envelope containing 491 common fields required in all protocol exchanges. At this time the 492 only common fields are the message ID and the controls. 494 If the server receives a PDU from the client in which the LDAPMessage 495 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 496 the tag of the protocolOp is not recognized as a request, or the 497 encoding structures or lengths of data fields are found to be 498 incorrect, then the server MUST return the notice of disconnection 499 Lightweight Directory Access Protocol Version 3 501 described in section 4.4.1, with resultCode protocolError, and 502 immediately close the connection. In other cases that the server 503 cannot parse the request received by the client, the server MUST 504 return an appropriate response to the request, with the resultCode 505 set to protocolError. 507 If the client receives a PDU from the server, which cannot be parsed, 508 the client may discard the PDU, or may abruptly close the connection. 510 The ASN.1 type Controls is defined in section 4.1.12. 512 4.1.1.1. Message ID 514 All LDAPMessage envelopes encapsulating responses contain the 515 messageID value of the corresponding request LDAPMessage. 517 The message ID of a request MUST have a value different from the 518 values of any other requests outstanding in the LDAP session of which 519 this message is a part. 521 A client MUST NOT send a second request with the same message ID as 522 an earlier request on the same connection if the client has not 523 received the final response from the earlier request. Otherwise the 524 behavior is undefined. Typical clients increment a counter for each 525 request. 527 A client MUST NOT reuse the message id of an abandonRequest or of the 528 abandoned operation until it has received a response from the server 529 for another request invoked subsequent to the abandonRequest, as the 530 abandonRequest itself does not have a response. 532 4.1.2. String Types 534 The LDAPString is a notational convenience to indicate that, although 535 strings of LDAPString type encode as OCTET STRING types, the 536 [ISO10646] character set (a superset of Unicode) is used, encoded 537 following the UTF-8 algorithm [RFC2044]. Note that in the UTF-8 538 algorithm characters which are the same as ASCII (0x0000 through 539 0x007F) are represented as that same ASCII character in a single 540 byte. The other byte values are used to form a variable-length 541 encoding of an arbitrary character. 543 LDAPString ::= OCTET STRING 545 The LDAPOID is a notational convenience to indicate that the 546 permitted value of this string is a (UTF-8 encoded) dotted-decimal 547 representation of an OBJECT IDENTIFIER. 549 LDAPOID ::= OCTET STRING 551 For example, 553 1.3.6.1.4.1.1466.1.2.3 554 Lightweight Directory Access Protocol Version 3 556 4.1.3. Distinguished Name and Relative Distinguished Name 558 An LDAPDN and a RelativeLDAPDN are respectively defined to be the 559 representation of a Distinguished Name and a Relative Distinguished 560 Name after encoding according to the specification in [RFC2253], such 561 that: 563 distinguished-name = name 565 relative-distinguished-name = name-component 567 where name and name-component are as defined in [RFC2253]. 569 LDAPDN ::= LDAPString 571 RelativeLDAPDN ::= LDAPString 573 Only Attribute Types can be present in a relative distinguished name 574 component--the options of Attribute Descriptions (next section) MUST 575 NOT be used in specifying distinguished names. 577 4.1.4. Attribute Type 579 An AttributeType takes on as its value the textual string associated 580 with that AttributeType in its specification. 582 AttributeType ::= LDAPString 584 Each attribute type has a unique OBJECT IDENTIFIER which has been 585 assigned to it. This identifier may be written as decimal digits with 586 components separated by periods, e.g. "2.5.4.10". 588 A specification may also assign one or more textual names for an 589 attribute type. These names MUST begin with a letter, and only 590 contain ASCII letters, digit characters and hyphens. They are case 591 insensitive. These ASCII characters are identical to ISO 10646 592 characters whose UTF-8 encoding is a single byte between 0x00 and 593 0x7F. 595 If the server has a textual name for an attribute type, it MUST use a 596 textual name for attributes returned in search results. The dotted- 597 decimal OBJECT IDENTIFIER is only used if there is no textual name 598 for an attribute type. 600 Attribute type textual names are non-unique, as two different 601 specifications (neither in standards track RFCs) may choose the same 602 name. 604 A server which masters or shadows entries SHOULD list all the 605 attribute types it supports in the subschema entries, using the 606 attributeTypes attribute. Servers which support an open-ended set of 607 attributes SHOULD include at least the attributeTypes value for the 608 'objectClass' attribute. Clients MAY retrieve the attributeTypes 609 Lightweight Directory Access Protocol Version 3 611 value from subschema entries in order to obtain the OBJECT IDENTIFIER 612 and other information associated with attribute types. 614 Some attribute type names which are used in this version of LDAP are 615 described in [RFC2252]. Servers may implement additional attribute 616 types. 618 4.1.5. Attribute Description 620 An AttributeDescription is a superset of the definition of the 621 AttributeType. It has the same ASN.1 definition, but allows 622 additional options to be specified. They are also case insensitive. 624 AttributeDescription ::= LDAPString 626 A value of AttributeDescription is based on the following BNF: 628 ::= [ ";" ] 630 ::=