idnits 2.17.1 draft-ietf-ldapbis-protocol-01.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 277: '... 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, ...' (177 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 (February 2001) is 8464 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 2080 looks like a reference -- Missing reference section? 'RFC1777' on line 2071 looks like a reference -- Missing reference section? 'RFC2252' on line 2558 looks like a reference -- Missing reference section? '0' on line 2386 looks like a reference -- Missing reference section? 'ISO10646' on line 533 looks like a reference -- Missing reference section? 'RFC2044' on line 2077 looks like a reference -- Missing reference section? 'RFC2253' on line 2093 looks like a reference -- Missing reference section? '5' on line 2556 looks like a reference -- Missing reference section? '3' on line 2322 looks like a reference -- Missing reference section? 'RFC2255' on line 2097 looks like a reference -- Missing reference section? 'RFC2396' on line 2100 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 2259 looks like a reference -- Missing reference section? 'RFC2222' on line 2083 looks like a reference -- Missing reference section? 'APPLICATION 1' on line 2273 looks like a reference -- Missing reference section? '7' on line 2307 looks like a reference -- Missing reference section? 'APPLICATION 2' on line 2277 looks like a reference -- Missing reference section? 'APPLICATION 3' on line 2279 looks like a reference -- Missing reference section? '1' on line 2387 looks like a reference -- Missing reference section? '2' on line 2321 looks like a reference -- Missing reference section? '4' on line 2323 looks like a reference -- Missing reference section? '6' on line 2306 looks like a reference -- Missing reference section? '8' on line 2308 looks like a reference -- Missing reference section? '9' on line 2309 looks like a reference -- Missing reference section? 'APPLICATION 4' on line 2325 looks like a reference -- Missing reference section? 'APPLICATION 19' on line 2333 looks like a reference -- Missing reference section? 'APPLICATION 5' on line 2335 looks like a reference -- Missing reference section? 'APPLICATION 6' on line 2337 looks like a reference -- Missing reference section? 'APPLICATION 7' on line 2353 looks like a reference -- Missing reference section? 'APPLICATION 8' on line 2355 looks like a reference -- Missing reference section? 'APPLICATION 9' on line 2363 looks like a reference -- Missing reference section? 'APPLICATION 10' on line 2365 looks like a reference -- Missing reference section? 'APPLICATION 11' on line 2367 looks like a reference -- Missing reference section? 'APPLICATION 12' on line 2369 looks like a reference -- Missing reference section? 'APPLICATION 13' on line 2375 looks like a reference -- Missing reference section? 'APPLICATION 14' on line 2377 looks like a reference -- Missing reference section? 'APPLICATION 15' on line 2381 looks like a reference -- Missing reference section? 'APPLICATION 16' on line 2383 looks like a reference -- Missing reference section? 'APPLICATION 23' on line 2385 looks like a reference -- Missing reference section? 'APPLICATION 24' on line 2389 looks like a reference -- Missing reference section? '10' on line 2391 looks like a reference -- Missing reference section? '11' on line 2392 looks like a reference -- Missing reference section? 'RFC1823' on line 2074 looks like a reference -- Missing reference section? 'RFC2234' on line 2086 looks like a reference -- Missing reference section? 'RFC2829' on line 2768 looks like a reference -- Missing reference section? 'RFC2830' on line 2762 looks like a reference -- Missing reference section? 'RFC 1823' on line 2565 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 Editor: J. Sermersheim 3 Intended Category: Standard Track Novell, Inc 4 Document: draft-ietf-ldapbis-protocol-01.txt February 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................................................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..........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.............................................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 Changes made to RFC 2251:..........................................45 94 B.1 Editorial......................................................45 95 B.2 Section 1......................................................45 96 B.3 Section 9......................................................45 97 B.4 Section 4.1.6..................................................45 98 B.5 Section 4.1.7..................................................45 99 B.6 Sections 4.2, 4.9, 4.10........................................45 100 B.7 Sections 4.5 and Appendix A....................................46 101 Appendix C - Outstanding Work Items................................46 102 C.1 Integrate result codes draft...................................46 103 C.2 Section 3.1....................................................46 104 C.3 Section 4......................................................46 105 C.4 Section 4.1.1..................................................46 106 C.5 Section 4.1.1.1................................................46 107 C.6 Section 4.1.2..................................................47 108 C.7 Section 4.1.4..................................................47 109 C.8 Section 4.1.5..................................................47 110 Lightweight Directory Access Protocol Version 3 112 C.9 Section 4.1.5.1................................................47 113 C.11 Section 4.1.7.................................................47 114 C.12 Section 4.1.8.................................................48 115 C.13 Section 4.1.11................................................48 116 C.14 Section 4.1.12................................................48 117 C.15 Section 4.2...................................................48 118 C.16 Section 4.2.1.................................................48 119 C.17 Section 4.2.2.................................................48 120 C.18 Section 4.2.3.................................................49 121 C.19 Section 4.3...................................................49 122 C.20 Section 4.4...................................................49 123 C.21 Section 4.5.1.................................................49 124 C.22 Section 4.5.2.................................................49 125 C.23 Section 4.5.3.................................................50 126 C.24 Section 4.5.3.1...............................................50 127 C.25 Section 4.6...................................................50 128 C.26 Section 4.7...................................................50 129 C.27 Section 4.10..................................................50 130 C.28 Section 4.11..................................................50 131 C.29 Section 4.12..................................................51 132 C.30 Section 5.1...................................................51 133 C.31 Section 5.2.1.................................................51 134 C.32 Section 6.1...................................................51 135 C.33 Section 7.....................................................51 137 2. Abstract 139 The protocol described in this document is designed to provide access 140 to directories supporting the [X.500] models, while not incurring the 141 resource requirements of the X.500 Directory Access Protocol (DAP). 142 This protocol is specifically targeted at management applications and 143 browser applications that provide read/write interactive access to 144 directories. When used with a directory supporting the X.500 145 protocols, it is intended to be a complement to the X.500 DAP. 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 149 to be interpreted as described in [RFC2119]. 151 Key aspects of this version of LDAP are: 153 - All protocol elements of LDAPv2 [RFC1777] are supported. The 154 protocol is carried directly over TCP or other transport, 155 bypassing much of the session/presentation overhead of X.500 DAP. 157 - Most protocol data elements can be encoded as ordinary strings 158 (e.g., Distinguished Names). 160 - Referrals to other servers may be returned. 162 - SASL mechanisms may be used with LDAP to provide association 163 security services. 165 Lightweight Directory Access Protocol Version 3 167 - Attribute values and Distinguished Names have been 168 internationalized through the use of the ISO 10646 character set. 170 - The protocol can be extended to support new operations, and 171 controls may be used to extend existing operations. 173 - Schema is published in the directory to be used by clients. 175 3. Models 177 Interest in X.500 directory technologies in the Internet has led to 178 efforts to reduce the high cost of entry associated with use of these 179 technologies. This document continues the efforts to define directory 180 protocol alternatives, updating the LDAPv2 protocol specification. 182 3.1. Protocol Model 184 The general model adopted by this protocol is one of clients 185 performing protocol operations against servers. In this model, a 186 client transmits a protocol request describing the operation to be 187 performed to a server. The server is then responsible for performing 188 the necessary operation(s) in the directory. Upon completion of the 189 operation(s), the server returns a response containing any results or 190 errors to the requesting client. 192 In keeping with the goal of easing the costs associated with use of 193 the directory, it is an objective of this protocol to minimize the 194 complexity of clients so as to facilitate widespread deployment of 195 applications capable of using the directory. 197 Note that although servers are required to return responses whenever 198 such responses are defined in the protocol, there is no requirement 199 for synchronous behavior on the part of either clients or servers. 200 Requests and responses for multiple operations may be exchanged 201 between a client and server in any order, provided the client 202 eventually receives a response for every request that requires one. 204 In LDAP versions 1 and 2, no provision was made for protocol servers 205 returning referrals to clients. However, for improved performance and 206 distribution, this version of the protocol permits servers to return 207 to clients, referrals to other servers. This allows servers to 208 offload the work of contacting other servers to progress operations. 210 Note that the core protocol operations defined in this document can 211 be mapped to a strict subset of the X.500(1997) directory abstract 212 service, so it can be cleanly provided by the DAP. However there is 213 not a one-to-one mapping between LDAP protocol operations and DAP 214 operations: server implementations acting as a gateway to X.500 215 directories may need to make multiple DAP requests. 217 218 3.2. Data Model 219 Lightweight Directory Access Protocol Version 3 221 This section provides a brief introduction to the X.500 data model, 222 as used by LDAP. 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 Lightweight Directory Access Protocol Version 3 277 Each entry MUST have an objectClass attribute. The objectClass 278 attribute specifies the object classes of an entry, which along with 279 the system and user schema determine the permitted attributes of an 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 Lightweight Directory Access Protocol Version 3 333 ordinary entries. LDAP clients SHOULD NOT assume that servers 334 implement any of the other aspects of X.500 subschema. A server which 335 masters entries and permits clients to modify these entries MUST 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 Lightweight Directory Access Protocol Version 3 389 which is named with the zero-length LDAPDN. These attributes are 390 retrievable if a client performs a base object search of the root 391 with filter "(objectClass=*)", however they are subject to access 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 Lightweight Directory Access Protocol Version 3 446 4.1. Common Elements 448 This section describes the LDAPMessage envelope PDU (Protocol Data 449 Unit) format, as well as data type definitions, which are used in the 450 protocol operations. 452 4.1.1. Message Envelope 454 For the purposes of protocol exchanges, all protocol operations are 455 encapsulated in a common envelope, the LDAPMessage, which is defined 456 as follows: 458 LDAPMessage ::= SEQUENCE { 459 messageID MessageID, 460 protocolOp CHOICE { 461 bindRequest BindRequest, 462 bindResponse BindResponse, 463 unbindRequest UnbindRequest, 464 searchRequest SearchRequest, 465 searchResEntry SearchResultEntry, 466 searchResDone SearchResultDone, 467 searchResRef SearchResultReference, 468 modifyRequest ModifyRequest, 469 modifyResponse ModifyResponse, 470 addRequest AddRequest, 471 addResponse AddResponse, 472 delRequest DelRequest, 473 delResponse DelResponse, 474 modDNRequest ModifyDNRequest, 475 modDNResponse ModifyDNResponse, 476 compareRequest CompareRequest, 477 compareResponse CompareResponse, 478 abandonRequest AbandonRequest, 479 extendedReq ExtendedRequest, 480 extendedResp ExtendedResponse }, 481 controls [0] Controls OPTIONAL } 483 MessageID ::= INTEGER (0 .. maxInt) 485 maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- 487 The function of the LDAPMessage is to provide an envelope containing 488 common fields required in all protocol exchanges. At this time the 489 only common fields are the message ID and the controls. 491 If the server receives a PDU from the client in which the LDAPMessage 492 SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 493 the tag of the protocolOp is not recognized as a request, or the 494 encoding structures or lengths of data fields are found to be 495 incorrect, then the server MUST return the notice of disconnection 496 described in section 4.4.1, with resultCode protocolError, and 497 immediately close the connection. In other cases that the server 498 cannot parse the request received by the client, the server MUST 499 Lightweight Directory Access Protocol Version 3 501 return an appropriate response to the request, with the resultCode 502 set to protocolError. 504 If the client receives a PDU from the server, which cannot be parsed, 505 the client may discard the PDU, or may abruptly close the connection. 507 The ASN.1 type Controls is defined in section 4.1.12. 509 4.1.1.1. Message ID 511 All LDAPMessage envelopes encapsulating responses contain the 512 messageID value of the corresponding request LDAPMessage. 514 The message ID of a request MUST have a value different from the 515 values of any other requests outstanding in the LDAP session of which 516 this message is a part. 518 A client MUST NOT send a second request with the same message ID as 519 an earlier request on the same connection if the client has not 520 received the final response from the earlier request. Otherwise the 521 behavior is undefined. Typical clients increment a counter for each 522 request. 524 A client MUST NOT reuse the message id of an abandonRequest of the 525 abandoned operation until it has received a response from the server 526 for another request invoked subsequent to the abandonRequest, as the 527 abandonRequest itself does not have a response. 529 4.1.2. String Types 531 The LDAPString is a notational convenience to indicate that, although 532 strings of LDAPString type encode as OCTET STRING types, the 533 [ISO10646] character set (a superset of Unicode) is used, encoded 534 following the UTF-8 algorithm [RFC2044]. Note that in the UTF-8 535 algorithm characters which are the same as ASCII (0x0000 through 536 0x007F) are represented as that same ASCII character in a single 537 byte. The other byte values are used to form a variable-length 538 encoding of an arbitrary character. 540 LDAPString ::= OCTET STRING 542 The LDAPOID is a notational convenience to indicate that the 543 permitted value of this string is a (UTF-8 encoded) dotted-decimal 544 representation of an OBJECT IDENTIFIER. 546 LDAPOID ::= OCTET STRING 548 For example, 550 1.3.6.1.4.1.1466.1.2.3 552 4.1.3. Distinguished Name and Relative Distinguished Name 553 Lightweight Directory Access Protocol Version 3 555 An LDAPDN and a RelativeLDAPDN are respectively defined to be the 556 representation of a Distinguished Name and a Relative Distinguished 557 Name after encoding according to the specification in [RFC2253], such 558 that: 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 Lightweight Directory Access Protocol Version 3 611 Some attribute type names which are used in this version of LDAP are 612 described in [RFC2252]. Servers may implement additional attribute 613 types. 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 ::=