idnits 2.17.1 draft-rharrison-ldap-intermediate-resp-01.txt: 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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC2251, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year (Using the creation date from RFC2251, updated by this document, for RFC5378 checks: 1996-03-14) -- 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 (March 28, 2003) is 7699 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: 'APPLICATION 25' is mentioned on line 170, but not defined -- Looks like a reference, but probably isn't: '0' on line 171 -- Looks like a reference, but probably isn't: '1' on line 172 == Missing Reference: 'RFCnnnn' is mentioned on line 410, but not defined ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 3377 (Obsoleted by RFC 4510) ** Obsolete normative reference: RFC 3383 (Obsoleted by RFC 4520) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT R. Harrison 3 draft-rharrison-ldap-intermediate-resp-01.txt Novell, Inc. 4 Updates: 2251 K. Zeilenga 5 Intended Category: Standards Track OpenLDAP Foundation 6 March 28, 2003 8 The Lightweight Directory Access Protocol (LDAP) 9 Intermediate Response Message 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 This document is intended to be, after appropriate review and 17 revision, submitted to the RFC Editor as a Standard Track document. 19 Distribution of this memo is unlimited. Technical discussion of 20 this document will take place on the IETF LDAP Extensions Working 21 Group (ldapext) mailing list . Please 22 send editorial comments directly to the document editor 23 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. Internet-Drafts are draft documents valid for a maximum of 29 six months and may be updated, replaced, or obsoleted by other 30 documents at any time. It is inappropriate to use Internet-Drafts 31 as reference material or to cite them other than as "work in 32 progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 Copyright Notice 41 Copyright (C) The Internet Society (2003). All Rights Reserved. 43 Abstract 45 The Lightweight Directory Access Protocol (LDAP) version 3 is a 46 client-request/server-response based protocol. With the exception 47 of the search operation, the entire response to an operation request 48 is returned in a single LDAP message. While this single- 49 request/single-response paradigm is sufficient for many operations 50 (including all but one of those currently defined by LDAP), both 51 intuition and practical experience validate the notion that it is 52 insufficient for some operations. When multiple messages are sent 53 in response to a single request, all but the last of these response 54 messages are referred to as "intermediate responses". 56 This document defines and describes the IntermediateResponse 57 message, a general mechanism for defining single-request/multiple- 58 response operations in LDAP. The IntermediateResponse message is 59 defined in a way that maintains the protocol behavior of existing 60 LDAP operations. This message is intended to be used in conjunction 61 with the LDAP ExtendedRequest and ExtendedResponse to define new 62 single-request/multiple-response operations or in conjunction with a 63 control when extending existing LDAP operations in a way that 64 requires them to return intermediate response information. 66 1. Introduction 68 The Lightweight Directory Access Protocol (LDAP), version 3 69 [RFC3377] is an extensible protocol. Extended operations ([RFC2251] 70 Section 4.12) are defined to allow operations to be added to LDAP 71 without requiring a new revision of the protocol. Similarly, 72 controls ([RFC2251] section 4.1.12) are defined to extend or modify 73 the behavior of existing LDAP operations. 75 LDAP is a client-request/server-response based protocol. With the 76 exception of the search operation, the entire response to an 77 operation request is returned in a single protocol data unit (i.e. 78 LDAP message). While this single-request/single-response paradigm 79 is sufficient for many operations (including all but one of those 80 currently defined by [RFC3377]), both intuition and practical 81 experience validate the notion that it is insufficient for some 82 operations. 84 For example, the LDAP delete operation could be extended via a 85 subtree control to mean that an entire subtree is to be deleted. A 86 subtree delete operation needs to return continuation references 87 based upon subordinate knowledge information contained in the server 88 so that the client can complete the operation. Returning references 89 as they are found instead of with the final result allows the client 90 to progress the operation more efficiently because it does not have 91 to wait for the final result to get this continuation reference 92 information. 94 Similarly, an engineer might choose to design the subtree delete 95 operation as an extended operation of its own rather than using a 96 subtree control in conjunction with the delete operation. Once 97 again, the same continuation reference information is needed by the 98 client to complete the operation, and sending the continuation 99 references as they are found would allow the client progress the 100 operation more efficiently. 102 Operations that complete in stages or that progress through various 103 states as they complete might want to send intermediate responses to 104 the client, thereby informing it of the status of the operation. 105 For example, an LDAP implementation might define an extended 106 operation to create a new replica of an administrative area on a 107 server, and the operation completes in three stages: (1) begin 108 creation of replica, (2) send replica data to server, (3) replica 109 creation complete. Intermediate messages might be sent from the 110 server to the client at the beginning of each stage with the final 111 response for the extended operation being sent after stage (3) is 112 complete. 114 As LDAP [RFC3377] is currently defined, there is no general LDAP 115 message type that can be used to return intermediate results. A 116 single, reusable LDAP message for carrying intermediate response 117 information is desired to avoid repeated modification of the 118 protocol. Although the ExtendedResponse message is defined in LDAP, 119 it is defined to be the one and only response message to an 120 ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited 121 responses (LDAP Section 4.4), and to return intermediate responses 122 for the search operation ([RFC3377] Section 4.5.2, also see Section 123 5 below). The adaptation of ExtendedResponse as a general 124 intermediate response mechanism would be problematic. In 125 particular, existing APIs would likely have to be redesigned. It is 126 believed (based upon operational experience) that the addition of a 127 new message to carry intermediate result information is easier to 128 implement and is less likely to cause interoperability problems with 129 existing deployed implementations. 131 This document defines and describes the LDAP IntermediateResponse 132 message. This message is intended to be used in conjunction with 133 ExtendedRequest and ExtendedResponse to define new single- 134 request/multiple-response operations or in conjunction with a 135 control when extending existing LDAP operations in a way that 136 requires them to return intermediate response information. 138 It is intended that the definitions and descriptions of extended 139 operations and controls that make use of the IntermediateResponse 140 message will define the circumstances when an IntermediateResponse 141 message can be sent by a server and the associated meaning of an 142 IntermediateResponse message sent in a particular circumstance. 143 Similarly, it is intended that clients will explicitly solicit 144 IntermediateResponse messages by issuing operations that 145 specifically call for their return. 147 The LDAP Content Sync Operation [draft-zeilenga-ldup-sync] (a work 148 in progress) demonstrates one use of LDAP Intermediate Response 149 messages. 151 2. Conventions used in this document 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in [RFC2119]. 157 The term "request control" is used to describe a control that is 158 included in an LDAP request message sent from an LDAP client to an 159 LDAP server. 161 3. The IntermediateResponse Message 163 This document extends the protocolOp CHOICE of LDAPMessage 164 ([RFC2251] Section 4.1.1) to include the field: 166 intermediateResponse IntermediateResponse 168 where IntermediateResponse is defined as: 170 IntermediateResponse ::= [APPLICATION 25] SEQUENCE { 171 responseName [0] LDAPOID OPTIONAL, 172 responseValue [1] OCTET STRING OPTIONAL } 174 IntermediateResponse messages SHALL NOT be returned to the client 175 unless the client issues a request that specifically solicits their 176 return. This document defines two forms of solicitation: extended 177 operation and request control. 179 Although the responseName and responseValue are optional in some 180 circumstances, generally speaking IntermediateResponse messages have 181 a predefined responseName and a responseValue. The value of the 182 responseName (if present), the syntax of the responseValue (if 183 present) and the semantics associated with a particular 184 IntermediateResponse message MUST be specified in documents 185 describing the extended operation or request control that uses them. 186 Sections 3.1 and 3.2 describe additional requirements on the 187 inclusion of responseName and responseValue in IntermediateResponse 188 messages. 190 3.1. Usage with LDAP ExtendedRequest and ExtendedResponse 192 A single-request/multiple-response operation may be defined using a 193 single ExtendedRequest message to solicit zero or more 194 IntermediateResponse messages of one or more kinds followed by an 195 ExtendedResponse message. 197 An extended operation that defines the return of multiple kinds of 198 IntermediateResponse messages MUST provide and document a mechanism 199 for the client to distinguish the kind of IntermediateResponse 200 message being sent. This SHALL be accomplished by using different 201 responseName values for each type of IntermediateResponse message 202 associated with the extended operation or by including identifying 203 information in the responseValue of each type of 204 IntermediateResponse message associated with the extended operation. 206 3.2. Usage with LDAP Request Controls 208 Any LDAP operation may be extended by the addition of one or more 209 controls ([RFC2251] Section 4.1.12). A control's semantics may 210 include the return of zero or more IntermediateResponse messages 211 prior to returning the final result code for the operation. One or 212 more kinds of IntermediateResponse messages may be sent in response 213 to a request control. 215 All IntermediateResponse messages associated with request controls 216 SHALL include a responseName. This requirement ensures that the 217 client can correctly identify the source of IntermediateResponse 218 messages when 220 (a) two or more controls using IntermediateResponse messages 221 are included in a request for any LDAP operation or 223 (b) one or more controls using IntermediateResponse messages 224 are included in a request with an LDAP extended 225 operation that uses IntermediateResponse messages. 227 A request control that defines the return of multiple kinds of 228 IntermediateResponse messages MUST provide and document a mechanism 229 for the client to distinguish the kind of IntermediateResponse 230 message being sent. This SHALL be accomplished by using different 231 responseName values for each type of IntermediateResponse message 232 associated with the request control or by including identifying 233 information in the responseValue of each type of 234 IntermediateResponse message associated with the request control. 236 4. Advertising Support for IntermediateResponse Messages 238 Because IntermediateResponse messages are associated with extended 239 operations or controls and LDAP provides a means for advertising the 240 extended operations and controls supported by a server (using the 241 supportedExtensions and supportedControls attributes of the root DSE 242 attributes), no separate means for advertising support for 243 IntermediateResponse messages is needed (or provided). 245 5. Use of IntermediateResponse and ExtendedResponse with Search 247 It is noted that ExtendedResponse messages may be sent in response 248 to LDAP search operations with controls ([RFC2251] Section 4.5.1). 249 This use of ExtendedResponse messages SHOULD be viewed as deprecated 250 in favor of use of the IntermediateResponse messages. 252 6. Security Considerations 254 This document describes an enhancement to LDAP. All security 255 considerations of [RFC3377] apply to this document, however it does 256 not introduce any new security considerations to LDAP. 258 Security considerations specific to each extension using this 259 protocol mechanism shall be discussed in the technical specification 260 detailing the extension. 262 7. IANA Considerations 263 Registration of the following value is requested [RFC3383]. 265 7.1. LDAP Message Type 267 It is requested that IANA register upon Standards Action an LDAP 268 Message Type to identify the LDAP IntermediateResponse message as 269 defined in section 3 of this document. 271 The following registration template is suggested: 273 Subject: Request for LDAP Message Type Registration 274 Person & email address to contact for further information: 275 Roger Harrison 276 Specification: RFCXXXX 277 Author/Change Controller: IESG 278 Comments: Identifies the LDAP IntermediateResponse Message 280 Acknowledgments 282 The authors would like to acknowledge the members of the IETF LDAP 283 Extensions (ldapext) working group mail list who responded to the 284 suggestion that a multiple-response paradigm might be useful for 285 LDAP extended requests. Special thanks go to two individuals: David 286 Wilbur who first introduced the idea on the working group list, and 287 Thomas Salter, who succinctly summarized the group's discussion. 289 Normative References 291 [RFC2119] 292 Bradner, S., "Key Words for use in RFCs to Indicate Requirement 293 Levels", BCP 14, RFC 2119, March 1997. 295 [RFC2251] 296 Wahl, M., Howes, T., and S. Kille, "Lightweight Directory 297 Access Protocol (v3)", RFC 2251, December 1997. 299 [RFC3377] 300 Hodges, J. and R. Morgan, "Lightweight Directory Access 301 Protocol (v3): Technical Specification", RFC 3377, September 302 2002. 304 [RFC3383] 305 Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 306 Considerations for the Lightweight Directory Access Protocol 307 (LDAP)", RFC 3383, September 2002. 309 Informative References 311 [draft-zeilenga-ldup-sync] 312 Zeilenga, K., "LDAP Content Synchronization Operation", Work in 313 Progress. 315 Authors' Addresses 317 Roger Harrison 318 Novell, Inc. 319 1800 S. Novell Place 320 Provo, UT 84606 321 +1 801 861 2642 322 roger_harrison@novell.com 324 Kurt D. Zeilenga 325 OpenLDAP Foundation 326 Kurt@OpenLDAP.org 328 Full Copyright Statement 330 "Copyright (C) The Internet Society (date). All Rights Reserved. 331 This document and translations of it may be copied and furnished to 332 others, and derivative works that comment on or otherwise explain it 333 or assist in its implementation may be prepared, copied, published 334 and distributed, in whole or in part, without restriction of any 335 kind, provided that the above copyright notice and this paragraph 336 are included on all such copies and derivative works. However, this 337 document itself may not be modified in any way, such as by removing 338 the copyright notice or references to the Internet Society or other 339 Internet organizations, except as needed for the purpose of 340 developing Internet standards in which case the procedures for 341 copyrights defined in the Internet Standards process must be 342 followed, or as required to translate it into languages other than 343 English. 345 The limited permissions granted above are perpetual and will not be 346 revoked by the Internet Society or its successors or assigns. 348 This document and the information contained herein is provided on an 349 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 350 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 351 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 352 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 353 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 355 Appendix A - Document Revision History 356 Editors' Note: this appendix should be removed prior to publication 357 as an RFC. It is provided as an aid to reviewers of this "work in 358 progress." 360 A.1. draft-rharrison-ldap-extPartResp-00.txt 362 Initial revision of draft. 364 A.2. draft-rharrison-ldap-extPartResp-01.txt 366 Changed responseName to be optional to align with [RFC3377] 367 definition of ExtendedResponse. 369 A.3. draft-rharrison-ldap-extPartResp-02.txt 371 Minor terminology corrections. Clarified use of 372 ExtendedPartialResponse with LDAP extended operations and other LDAP 373 operations with controls. 375 A.4. draft-rharrison-ldap-intermediateResp-00.txt 377 - Changed name of ExtendedPartialResponse to IntermediateResponse. 379 - Retitled "Motivation" section to "Background and Intended Usage" 380 and expanded its contents. 382 - Added detail surrounding the use of the IntermediateResponse with 383 extended operations and request controls. 385 - Generalized the way that Intermediate response fits into the ASN.1 386 definition of LDAP. 388 - Added information on advertising IntermediateResponse. 390 - Added information on the use of IntermediateResponse with the 391 search operation. 393 A.5. draft-rharrison-ldap-intermediateResp-01.txt 395 This draft was oriented primarily to preparing the draft for 396 publication in accordance with established RFC formatting 397 guidelines. No substantial change in overall content was made. 398 Changes included the following: 400 - Retitled document 402 - Rewrote abstract 404 - Retitled "Background and Intended Usage" section to "Introduction" 405 and expanded its contents. 407 - Retitled Section 3 from "The Intermediate Response PDU" to "The 408 Intermediate Response Message". 410 - Renamed references to [RFCnnnn] format 412 - Added IANA Considerations section 414 - Retitled "References" section to "Normative References" 416 - Other small edits to bring draft in line with RFC formatting 417 guidelines.