idnits 2.17.1 draft-smith-ldapv3-url-update-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: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([2], [3], [6], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == 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 document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (22 November 2000) is 8556 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) ** Obsolete normative reference: RFC 2253 (ref. '1') (Obsoleted by RFC 4510, RFC 4514) ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (ref. '3') (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) ** Obsolete normative reference: RFC 2254 (ref. '4') (Obsoleted by RFC 4510, RFC 4515) ** Obsolete normative reference: RFC 1738 (ref. '5') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 2829 (ref. '7') (Obsoleted by RFC 4510, RFC 4513) Summary: 15 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Tim Howes 3 Request for Comments: DRAFT Loudcloud, Inc. 4 Obsoletes: RFC 2255 Mark Smith 5 Netscape Communications Corp. 6 22 November 2000 8 The LDAP URL Format 9 11 1. 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. Internet-Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its areas, 16 and its working groups. Note that other groups may also distribute 17 working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet- Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Discussion of this document should take place on the LDAP Extensions 31 Working Group mailing list . After 32 appropriate review and discussion, this document will be submitted as 33 a Standards Track replacement for RFC 2255. 35 Copyright Notice 37 Copyright (C) The Internet Society (2000). All Rights Reserved. 39 2. Abstract 41 LDAP is the Lightweight Directory Access Protocol, defined in [1], 42 [2] and [3]. This document describes a format for an LDAP Uniform 43 Resource Locator. The format describes an LDAP search operation to 44 perform to retrieve information from an LDAP directory, or, in the 45 context of an LDAPv3 referral or reference, the format describes a 46 service where an LDAP operation may be progressed. 48 This document specifies the LDAP URL format for version 3 of LDAP and 49 clarifies how LDAP URLs are resolved. This document also defines an 50 extension mechanism for LDAP URLs, so that future documents can 51 extend their functionality, for example, to provide access to new 52 LDAPv3 extensions as they are defined. 54 This document replaces RFC 2255. See Appendix A for a list of changes 55 relative to RFC 2255. 57 The key words "MUST", "MAY", and "SHOULD" used in this document are 58 to be interpreted as described in [6]. 60 3. URL Definition 62 An LDAP URL begins with the protocol prefix "ldap" and is defined by 63 the following grammar. 65 ldapurl = scheme "://" [hostport] ["/" 66 [dn ["?" [attributes] ["?" [scope] 67 ["?" [filter] ["?" extensions]]]]]] 68 scheme = "ldap" 69 attributes = attrdesc *("," attrdesc) 70 scope = "base" / "one" / "sub" 71 dn = distinguishedName from Section 3 of [1] 72 hostport = hostport from Section 5 of RFC 1738 [5] 73 attrdesc = AttributeDescription from Section 4.1.5 of [2] / "*" 74 filter = filter from Section 4 of [4] 75 extensions = extension *("," extension) 76 extension = ["!"] extype ["=" exvalue] 77 extype = token / xtoken 78 exvalue = LDAPString from section 4.1.2 of [2] 79 token = oid from section 4.1 of [3] 80 xtoken = ("X-" / "x-") token 82 The "ldap" prefix indicates an entry or entries residing in the LDAP 83 server running on the given hostname at the given portnumber. 85 The dn is an LDAP Distinguished Name using the string format 86 described in [1]. It identifies the base object of the LDAP search or 87 the target of a non-search operation. 89 The attributes construct is used to indicate which attributes should 90 be returned from the entry or entries. Individual attrdesc names are 91 as defined for AttributeDescription in [2]. 93 The scope construct is used to specify the scope of the search to 94 perform in the given LDAP server. The allowable scopes are "base" 95 for a base object search, "one" for a one-level search, or "sub" for 96 a subtree search. 98 The filter is used to specify the search filter to apply to entries 99 within the specified scope during the search. It has the format 100 specified in [4]. 102 The extensions construct provides the LDAP URL with an extensibility 103 mechanism, allowing the capabilities of the URL to be extended in the 104 future. Extensions are a simple comma-separated list of type=value 105 pairs, where the =value portion MAY be omitted for options not 106 requiring it. Each type=value pair is a separate extension. These 107 LDAP URL extensions are not necessarily related to any of the LDAPv3 108 extension mechanisms. Extensions may be supported or unsupported by 109 the client resolving the URL. An extension prefixed with a '!' 110 character (ASCII 33) is critical. An extension not prefixed with a 111 '!' character is non-critical. 113 If an extension is supported by the client, the client MUST obey the 114 extension if the extension is critical. The client SHOULD obey 115 supported extensions that are non-critical. 117 If an extension is unsupported by the client, the client MUST NOT 118 process the URL if the extension is critical. If an unsupported 119 extension is non-critical, the client MUST ignore the extension. 121 If a critical extension cannot be processed successfully by the 122 client, the client MUST NOT process the URL. If a non-critical 123 extension cannot be processed successfully by the client, the client 124 SHOULD ignore the extension. 126 Extension types prefixed by "X-" or "x-" are reserved for use in 127 bilateral agreements between communicating parties. Other extension 128 types MUST be defined in this document, or in other standards-track 129 documents. 131 One LDAP URL extension is defined in this document (see the section 132 "The Bindname Extension" below). Other documents or a future version 133 of this document MAY define other extensions. 135 Note that any Unsafe characters (e.g., spaces) (as defined in section 136 2.2 of RFC 1738), and the single Reserved character '?' occurring 137 inside a dn, filter, or other element of an LDAP URL MUST be escaped 138 using the % method described in RFC 1738 [5]. If a comma character 139 ',' occurs inside an extension value, the character MUST also be 140 escaped using the % method. 142 4. Defaults for Fields of the LDAP URL 144 Some fields of the LDAP URL are optional, as described above. In the 145 absence of any other specification, the following defaults SHOULD be 146 used when a field is absent: 148 hostport 149 The default LDAP port is TCP port 389. If no hostport is given, 150 the client must have some apriori knowledge of an appropriate LDAP 151 server to contact. 153 dn 154 If no dn is given, the default is the zero-length DN, "". 156 attributes 157 If the attributes part is omitted, all user attributes of the 158 entry or entries should be requested (e.g., by setting the 159 attributes field AttributeDescriptionList in the LDAP search 160 request to a NULL list, or (in LDAPv3) by requesting the special 161 attribute name "*"). 163 scope 164 If scope is omitted, a scope of "base" is assumed. 166 filter 167 If filter is omitted, a filter of "(objectClass=*)" is assumed. 169 extensions 170 If extensions is omitted, no extensions are assumed. 172 5. The Bindname Extension 174 This section defines an LDAP URL extension for representing the 175 distinguished name for a client to use when authenticating to an LDAP 176 directory during resolution of an LDAP URL. Clients MAY implement 177 this extension. 179 The extension type is "bindname". The extension value is the 180 distinguished name of the directory entry to authenticate as, in the 181 same form as described for dn in the grammar above. The dn may be the 182 NULL string to specify unauthenticated access. The extension may be 183 either critical (prefixed with a '!' character) or non-critical (not 184 prefixed with a '!' character). 186 If the bindname extension is critical, the client resolving the URL 187 MUST authenticate to the directory using the given distinguished name 188 and an appropriate authentication method. Note that for a NULL 189 distinguished name, no bind MAY be required to obtain anonymous 190 access to the directory. If the extension is non-critical, the client 191 MAY bind to the directory using the given distinguished name. 193 6. URL Processing 195 This section describes how an LDAP URL SHOULD be resolved by a 196 client. 198 First, the client obtains a connection to the LDAP server referenced 199 in the URL, or an LDAP server of the client's choice if no LDAP 200 server is explicitly referenced. This connection MAY be opened 201 specifically for the purpose of resolving the URL or the client MAY 202 reuse an already open connection if the open connection is compatible 203 with the URL. The connection MAY provide confidentiality, integrity, 204 or other services, e.g., using TLS. Use of security services is at 205 the client's discretion if not specified in the URL but is encouraged 206 if the request or any potential responses contains sensitive 207 information. If the URL represents a referral for an update 208 operation, security services SHOULD be used. 210 Next, the client authenticates itself to the LDAP server. This step 211 is optional, unless the URL contains a critical bindname extension 212 with a non-NULL value. If a bindname extension is given, the client 213 proceeds according to the section above. 215 If a bindname extension is not specified, the client MAY bind to the 216 directory using an appropriate authentication method of its own 217 choosing (including NULL authentication). The client may interrogate 218 the server to determine the most appropriate method. 220 Next, the client performs the LDAP search operation specified in the 221 URL. Additional fields in the LDAP protocol search request, such as 222 sizelimit, timelimit, deref, and anything else not specified or 223 defaulted in the URL specification, MAY be set at the client's 224 discretion. 226 Once the search has completed, the client MAY close the connection to 227 the LDAP server, or the client MAY keep the connection open for 228 future use. 230 7. Examples 232 The following are some example LDAP URLs using the format defined 233 above. The first example is an LDAP URL referring to the University 234 of Michigan entry, available from an LDAP server of the client's 235 choosing: 237 ldap:///o=University%20of%20Michigan,c=US 239 The next example is an LDAP URL referring to the University of 240 Michigan entry in a particular ldap server: 242 ldap://ldap1.example.net/o=University%20of%20Michigan,c=US 244 Both of these URLs correspond to a base object search of the 245 "o=University of Michigan,c=US" entry using a filter of 246 "(objectclass=*)", requesting all attributes. 248 The next example is an LDAP URL referring to only the postalAddress 249 attribute of the University of Michigan entry: 251 ldap://ldap1.example.net/o=University%20of%20Michigan, 252 c=US?postalAddress 254 The corresponding LDAP search operation is the same as in the 255 previous example, except that only the postalAddress attribute is 256 requested. 258 The next example is an LDAP URL referring to the set of entries found 259 by querying the given LDAP server on port 6666 and doing a subtree 260 search of the University of Michigan for any entry with a common name 261 of "Babs Jensen", retrieving all attributes: 263 ldap://ldap1.example.net:6666/o=University%20of%20Michigan, 264 c=US??sub?(cn=Babs%20Jensen) 266 The next example is an LDAP URL referring to all children of the c=GB 267 entry: 269 ldap://ldap1.example.com/c=GB?objectClass?one 271 The objectClass attribute is requested to be returned along with the 272 entries, and the default filter of "(objectclass=*)" is used. 274 The next example is an LDAP URL to retrieve the mail attribute for 275 the LDAP entry named "o=Question?,c=US" is given below, illustrating 276 the use of the escaping mechanism on the reserved character '?'. 278 ldap://ldap2.example.com/o=Question%3f,c=US?mail 280 The next example illustrates the interaction between LDAP and URL 281 quoting mechanisms. 283 ldap://ldap3.example.com/o=Babsco,c=US???(int=%5c00%5c00%5c00%5c04) 285 The filter in this example uses the LDAP escaping mechanism of \ to 286 encode three zero or null bytes in the value. In LDAP, the filter 287 would be written as (int=\00\00\00\04). Because the \ character must 288 be escaped in a URL, the \'s are escaped as %5c in the URL encoding. 290 The final example shows the use of the bindname extension to specify 291 the dn a client should use for authentication when resolving the URL. 293 ldap:///??sub??bindname=cn=Manager%2co=Foo 294 ldap:///??sub??!bindname=cn=Manager%2co=Foo 296 The two URLs are the same, except that the second one marks the 297 bindname extension as critical. Notice the use of the % encoding 298 method to encode the comma in the distinguished name value in the 299 bindname extension. 301 8. Security Considerations 303 General URL security considerations discussed in [5] are relevant for 304 LDAP URLs. 306 The use of security mechanisms when processing LDAP URLs requires 307 particular care, since clients may encounter many different servers 308 via URLs, and since URLs are likely to be processed automatically, 309 without user intervention. A client SHOULD have a user-configurable 310 policy about which servers to connect to using which security 311 mechanisms, and SHOULD NOT make connections that are inconsistent 312 with this policy. If a client chooses to reuse an existing 313 connection when resolving one or more LDAP URL, it MUST ensure that 314 the connection is compatible with the URL and that no security 315 policies are violated. 317 Sending authentication information, no matter the mechanism, may 318 violate a user's privacy requirements. In the absence of specific 319 policy permitting authentication information to be sent to a server, 320 a client should use an anonymous connection. (Note that clients 321 conforming to previous LDAP URL specifications, where all connections 322 are anonymous and unprotected, are consistent with this 323 specification; they simply have the default security policy.) Simply 324 opening a connection to another server may violate some users' 325 privacy requirements, so clients should provide the user with a way 326 to control URL processing. 328 Some authentication methods, in particular reusable passwords sent to 329 the server, may reveal easily-abused information to the remote server 330 or to eavesdroppers in transit, and should not be used in URL 331 processing unless explicitly permitted by policy. Confirmation by 332 the human user of the use of authentication information is 333 appropriate in many circumstances. Use of strong authentication 334 methods that do not reveal sensitive information is much preferred. 335 If the URL represents a referral for an update operation, strong 336 authentication methods SHOULD be used. Please refer to the Security 337 Considerations section of [7] for more information. 339 The LDAP URL format allows the specification of an arbitrary LDAP 340 search operation to be performed when evaluating the LDAP URL. 341 Following an LDAP URL may cause unexpected results, for example, the 342 retrieval of large amounts of data, the initiation of a long-lived 343 search, etc. The security implications of resolving an LDAP URL are 344 the same as those of resolving an LDAP search query. 346 9. Acknowledgements 348 The LDAP URL format was originally defined at the University of 349 Michigan. This material is based upon work supported by the National 350 Science Foundation under Grant No. NCR-9416667. The support of both 351 the University of Michigan and the National Science Foundation is 352 gratefully acknowledged. 354 Several people have made valuable comments on this document. In 355 particular RL "Bob" Morgan, Mark Wahl, and Kurt Zeilenga deserve 356 special thanks for their contributions. 358 10. References 360 [1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access 361 Protocol (v3): UTF-8 String Representation of Distinguished Names", 362 RFC 2253, December 1997. 364 [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access 365 Protocol (v3)", RFC 2251, December 1997. 367 [3] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight 368 Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 369 2252, December 1997. 371 [4] Howes, T., "A String Representation of LDAP Search Filters", RFC 372 2254, December 1997. 374 [5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource 375 Locators (URL)," RFC 1738, December 1994. 377 [6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement 378 Levels," RFC 2119, March 1997. 380 [7] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, 381 "Authentication Methods for LDAP", RFC 2829, May 2000. 383 11. Authors' Address 385 Tim Howes 386 Loudcloud, Inc. 387 599 N. Mathilda Ave. 388 Sunnyvale, CA 94086 389 USA 390 +1 408 744-7509 391 howes@loudcloud.com 393 Mark Smith 394 Netscape Communications Corp. 395 Mailstop USCA17-201 396 4170 Network Circle 397 Santa Clara, CA 95054 398 USA 399 +1 650 937-3477 400 mcs@netscape.com 402 12. Full Copyright Statement 404 Copyright (C) The Internet Society (2000). All Rights Reserved. 406 This document and translations of it may be copied and furnished to 407 others, and derivative works that comment on or otherwise explain it 408 or assist in its implementation may be prepared, copied, published 409 and distributed, in whole or in part, without restriction of any 410 kind, provided that the above copyright notice and this paragraph are 411 included on all such copies and derivative works. However, this 412 document itself may not be modified in any way, such as by removing 413 the copyright notice or references to the Internet Society or other 414 Internet organizations, except as needed for the purpose of 415 developing Internet standards in which case the procedures for 416 copyrights defined in the Internet Standards process must be 417 followed, or as required to translate it into languages other than 418 English. 420 The limited permissions granted above are perpetual and will not be 421 revoked by the Internet Society or its successors or assigns. 423 This document and the information contained herein is provided on an 424 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 425 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 426 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 427 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 428 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 430 13. Appendix A: Changes Since RFC 2255 432 13.1. Technical Changes 434 "URL Definition" section: added missing "*" as an alternative for the 435 attrdesc part of the URL. It is believed that existing 436 implementations of RFC 2255 already support this. 438 13.2. Editorial Changes 440 "Abstract" section: changed the text indicate that RFC 2255 is 441 replaced by this document (instead of RFC 1959). Added text to 442 indicate that LDAP URLs are used for references and referrals. 444 IESG Note: removed note about lack of satisfactory mandatory 445 authentication mechanisms. 447 "URL Definition" section: removed second copy of ldapurl grammar and 448 following two paragraphs (editorial error in RFC 2255). Fixed line 449 break within '!' sequence. Reworded last paragraph to clarify which 450 characters must be URL escaped. Added text to indicate that LDAP 451 URLs are used for references and referrals. 453 "Defaults for Fields of the LDAP URL" section: added; formed by 454 moving text about defaults out of the "URL Definition" section. 456 "URL Processing" section: clarified that connections MAY be reused 457 only if the open connection is compatible with the URL. Added text 458 to indicate that use of security services is encouraged and that they 459 SHOULD be used when updates are involved. Removed "dn" from 460 discussion of authentication methods. Added note that the client MAY 461 interrogate the server to determine the most appropriate method. 463 "Examples" section: Modified examples to use example.com and 464 example.net hostnames. Added missing '?' to the LDAP URL example 465 whose filter contains three null bytes. Removed space after one 466 comma within a DN. 468 "Security Considerations" section: Added a note about connection 469 reuse. Added a note about using strong authentication methods for 470 updates. Added a reference to RFC 2829. Added note that simply 471 opening a connection may violate some users' privacy requirements. 473 "Acknowledgements" section: added Kurt Zeilenga. 475 "References" section: added an entry for RFC 2829. 477 Authors: updated affiliation and contact information. 479 Copyright: updated the year. 481 "Appendix C: Loose Ends" section: added. 483 "Table of Contents" section: added. 485 14. Appendix B: Changes since draft-smith-ldapv3-url-update-00.txt 487 Note that these changes are also listed in Appendix A, but are included 488 here for those who have already reviewed draft-smith-ldapv3-url-update- 489 00.txt. 491 14.1. Technical Changes 493 "URL Definition" section: added missing "*" as an alternative for the 494 attrdesc part of the URL. It is believed that existing 495 implementations of RFC 2255 already support this. 497 14.2. Editorial Changes 499 "Examples" section: Removed space after one comma within a DN. 501 "Defaults for Fields of the LDAP URL" section: added; formed by 502 moving text about defaults out of the "URL Definition" section. 504 "Appendix C: Loose Ends" section: added two items (RFC 1738 reference 505 needs to be updated to 2396 and need to use ABNF from RFC 2234). 507 "Table of Contents" section: added. 509 15. Appendix C: Loose Ends 511 Search URLs vs. Referral URLs: This document was originally written 512 with a focus on LDAP search operations, but LDAPv3 also uses this 513 format to describe referrals and search continuation references. 514 Some suggestions made by Kurt Zeilenga have been incorporated in this 515 update, but more remains to be done (and not all of Kurt's 516 suggestions have been incorporated yet). 518 Other Extensions: Suggestions for TLS and SASL URL extensions have 519 been made, but more discussion is needed about whether they are 520 needed, how they will be specified, and whether they should be added 521 to this document. 523 The reference to RFC 1738 needs to be updated to reference RFC 2396 524 instead. We need to consider whether it makes sense to support 525 constructs like @: within the hostport field. 527 The BNF needs to be updated to use the ABNF specified in RFC 2234, 528 and a reference to 2234 needs to be added. 530 This Internet Draft expires in May 2001. 532 1. Status of this Memo............................................1 533 2. Abstract.......................................................1 534 3. URL Definition.................................................2 535 4. Defaults for Fields of the LDAP URL............................4 536 5. The Bindname Extension.........................................4 537 6. URL Processing.................................................5 538 7. Examples.......................................................5 539 8. Security Considerations........................................7 540 9. Acknowledgements...............................................8 541 10. References.....................................................8 542 11. Authors' Address...............................................9 543 12. Full Copyright Statement.......................................9 544 13. Appendix A: Changes Since RFC 2255.............................10 545 13.1. Technical Changes...........................................10 546 13.2. Editorial Changes...........................................10 547 14. Appendix B: Changes since draft-smith-ldapv3-url-update-00.txt.11 548 14.1. Technical Changes...........................................11 549 14.2. Editorial Changes...........................................11 550 15. Appendix C: Loose Ends.........................................11