idnits 2.17.1 draft-zeilenga-ldapv3bis-rfc2255-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** 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? 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 = "base" / "one" / "sub"' ) ** 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 an Authors' Addresses Section. ** 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 abstract seems to indicate that this document obsoletes RFC1959, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 377 has weird spacing: '...nism of to...' == Line 379 has weird spacing: '...use the chara...' == Line 507 has weird spacing: '...for the purpo...' == 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 (4 July 2000) is 8689 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) -- Looks like a reference, but probably isn't: 'RFC 2255' on line 42 ** 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) Summary: 13 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Kurt D. Zeilenga 3 Intended Category: Standard Track OpenLDAP Foundation 4 Expires: 4 January 2001 4 July 2000 6 LDAPv3bis Suggestions: 7 The LDAP URL Format 8 10 Status of Memo 12 This document is an Internet-Draft and is in full conformance with all 13 provisions of Section 10 of RFC2026. 15 This document is intended to be, after appropriate review and 16 revision, submitted to the RFC Editor as a Standard Track document. 17 Distribution of this memo is unlimited. Technical discussion of this 18 document will take place on the IETF LDAP Extension Working Group 19 mailing list . Please send editorial 20 comments directly to the author . 22 Internet-Drafts are working documents of the Internet Engineering Task 23 Force (IETF), its areas, and its working groups. Note that other 24 groups may also distribute working documents as Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as ``work in progress.'' 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft 32 Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 34 Copyright 2000, The Internet Society. All Rights Reserved. 36 Please see the Copyright section near the end of this document for 37 more information. 39 Forward 41 This Internet Draft suggests a number of updates to "The LDAP URL 42 Format" [RFC 2255]. This document is not intended to be published as 43 an RFC but used to identify LDAPv3bis work items. 45 The remainer of this documents incorporates the substantive portion of 46 RFC 2255 text (less status of memo, appendices, etc). Comments and 47 suggested updates to this text are inserted as inline notes prefixed 48 with '//'. 50 // Start of RFC 2255 text 52 2. Abstract 54 LDAP is the Lightweight Directory Access Protocol, defined in [1], [2] 55 and [3]. This document describes a format for an LDAP Uniform 56 Resource Locator. The format describes an LDAP search operation to 57 perform to retrieve information from an LDAP directory. 59 // Or, in the context of an Referral resulting from a non-search 60 // operation, the format describes a reference to service where 61 // the operation may be progressed. 63 This document replaces RFC 1959. It updates the LDAP URL format for 64 version 3 of LDAP and clarifies how LDAP URLs are resolved. This 65 document also defines an extension mechanism for LDAP URLs, so that 66 future documents can extend their functionality, for example, to 67 provide access to new LDAPv3 extensions as they are defined. 69 // Add: 70 // A number of extensions are defined to support mandatory 71 // to implement authentication and privacy features. 73 The key words "MUST", "MAY", and "SHOULD" used in this document are to 74 be interpreted as described in [6]. 76 3. URL Definition 78 An LDAP URL begins with the protocol prefix "ldap" and is defined by 79 the following grammar. 81 ldapurl = scheme "://" [hostport] ["/" 82 [dn ["?" [attributes] ["?" [scope] 83 ["?" [filter] ["?" extensions]]]]]] 84 scheme = "ldap" 85 attributes = attrdesc *("," attrdesc) 86 scope = "base" / "one" / "sub" 87 dn = distinguishedName from Section 3 of [1] 88 hostport = hostport from Section 5 of RFC 1738 [5] 89 attrdesc = AttributeDescription from Section 4.1.5 of [2] 90 filter = filter from Section 4 of [4] 91 extensions = extension *("," extension) 92 extension = ["!"] extype ["=" exvalue] 93 extype = token / xtoken 94 exvalue = LDAPString from section 4.1.2 of [2] 95 token = oid from section 4.1 of [3] 96 xtoken = ("X-" / "x-") token 98 The "ldap" prefix indicates an entry or entries residing in the LDAP 99 server running on the given hostname at the given portnumber. The 100 default LDAP port is TCP port 389. If no hostport is given, the client 101 must have some apriori knowledge of an appropriate LDAP server to 102 contact. 104 The dn is an LDAP Distinguished Name using the string format described 105 in [1]. It identifies the base object of the LDAP search. 107 // or the target of a non-search operation. 109 ldapurl = scheme "://" [hostport] ["/" 110 [dn ["?" [attributes] ["?" [scope] 111 ["?" [filter] ["?" extensions]]]]]] 112 scheme = "ldap" 113 attributes = attrdesc *("," attrdesc) 114 scope = "base" / "one" / "sub" 115 dn = distinguishedName from Section 3 of [1] 116 hostport = hostport from Section 5 of RFC 1738 [5] 117 attrdesc = AttributeDescription from Section 4.1.5 of [2] 118 filter = filter from Section 4 of [4] 119 extensions = extension *("," extension) 120 extension = ["!"] extype ["=" exvalue] 121 extype = token / xtoken 122 exvalue = LDAPString from section 4.1.2 of [2] 123 token = oid from section 4.1 of [3] 124 xtoken = ("X-" / "x-") token 126 // remove duplicated text 128 The "ldap" prefix indicates an entry or entries residing in the LDAP 129 server running on the given hostname at the given portnumber. The 130 default LDAP port is TCP port 389. If no hostport is given, the client 131 must have some apriori knowledge of an appropriate LDAP server to 132 contact. 134 // remove duplicated text 136 The dn is an LDAP Distinguished Name using the string format described 137 in [1]. It identifies the base object of the LDAP search. 138 // remove duplicated text 140 // Attributes, scope, and filter components SHOULD NOT be present 141 // when non-search referral URLs. If present, the referral should 142 // be treated as a protocol error. 144 The attributes construct is used to indicate which attributes should 145 be returned from the entry or entries. Individual attrdesc names are 146 as defined for AttributeDescription in [2]. If the attributes part is 147 omitted, all user attributes of the entry or entries should be 148 requested (e.g., by setting the attributes field 149 AttributeDescriptionList in the LDAP search request to a NULL list, or 150 (in LDAPv3) by requesting the special attribute name "*"). 152 The scope construct is used to specify the scope of the search to 153 perform in the given LDAP server. The allowable scopes are "base" for 154 a base object search, "one" for a one-level search, or "sub" for a 155 subtree search. If scope is omitted, a scope of "base" is assumed. 157 // In the context of a search continuation, if scope is omitted, 158 // the scope derived by the scope of the original operation. If 159 // the original operation had scope subtree, a scope of "subtree" 160 // shall be assumed. If the original scope was one-level, scope 161 // of "base" shall be assumed. If the original scope was base, 162 // the continuation should be treated as a protocol error. 164 The filter is used to specify the search filter to apply to entries 165 within the specified scope during the search. It has the format 166 specified in [4]. If filter is omitted, a filter of "(objectClass=*)" 167 is assumed. 169 // Except in the context of a referral or search continuation where 170 // the original filter should be reused. 172 The extensions construct provides the LDAP URL with an extensibility 173 mechanism, allowing the capabilities of the URL to be extended in the 174 future. Extensions are a simple comma-separated list of type=value 175 pairs, where the =value portion MAY be omitted for options not 176 requiring it. Each type=value pair is a separate extension. These LDAP 177 URL extensions are not necessarily related to any of the LDAPv3 178 extension mechanisms. Extensions may be supported or unsupported by 179 the client resolving the URL. An extension prefixed with a '!' 180 character (ASCII 33) is critical. An extension not prefixed with a ' 181 !' character is non-critical. 183 If an extension is supported by the client, the client MUST obey the 184 extension if the extension is critical. The client SHOULD obey 185 supported extensions that are non-critical. 187 If an extension is unsupported by the client, the client MUST NOT 188 process the URL if the extension is critical. If an unsupported 189 extension is non-critical, the client MUST ignore the extension. 191 If a critical extension cannot be processed successfully by the 192 client, the client MUST NOT process the URL. If a non-critical 193 extension cannot be processed successfully by the client, the client 194 SHOULD ignore the extension. 196 Extension types prefixed by "X-" or "x-" are reserved for use in 197 bilateral agreements between communicating parties. Other extension 198 types MUST be defined in this document, or in other standards-track 199 documents. 201 // Add: 202 // As extensions may relate to operations and/or controls upon 203 // options, they shall be processed in order (left-to-right) 204 presented. 206 One LDAP URL extension is defined in this document in the next 207 section. 209 // Replace: 210 // Multiple URL extensions are defined in this document in following 211 // section. 213 Other documents or a future version of this document MAY define other 214 extensions. 216 Note that any URL-illegal characters (e.g., spaces), URL special 217 characters (as defined in section 2.2 of RFC 1738) and the reserved 218 character '?' (ASCII 63) occurring inside a dn, filter, or other 219 element of an LDAP URL MUST be escaped using the % method described in 220 RFC 1738 [5]. If a comma character ',' occurs inside an extension 221 value, the character MUST also be escaped using the % method. 223 // Insert: 224 // 4. URL Extensions 225 // 226 // Insert descriptions of TLS (StartTLS), sasl, and related 227 // extensions here. Text for these extensions will initially 228 // be provided in a separate draft but eventually inserted 229 // here. Examples using these extensions, however, are 230 // provided below. 232 4. The Bindname Extension 234 // Change to 4.x 236 This section defines an LDAP URL extension for representing the 237 distinguished name for a client to use when authenticating to an LDAP 238 directory during resolution of an LDAP URL. Clients MAY implement this 239 extension. 241 The extension type is "bindname". The extension value is the 242 distinguished name of the directory entry to authenticate as, in the 243 same form as described for dn in the grammar above. The dn may be the 244 NULL string to specify unauthenticated access. The extension may be 245 either critical (prefixed with a '!' character) or non-critical (not 246 prefixed with a '!' character). 248 If the bindname extension is critical, the client resolving the URL 249 MUST authenticate to the directory using the given distinguished name 250 and an appropriate authentication method. Note that for a NULL 251 distinguished name, no bind MAY be required to obtain anonymous access 252 to the directory. If the extension is non-critical, the client MAY 253 bind to the directory using the given distinguished name. 255 5. URL Processing 257 This section describes how an LDAP URL SHOULD be resolved by a client. 259 First, the client obtains a connection to the LDAP server referenced 260 in the URL, or an LDAP server of the client's choice if no LDAP server 261 is explicitly referenced. This connection MAY be opened specifically 262 for the purpose of resolving the URL or the client MAY reuse an 263 already open connection. 265 // if the open connection is compatible with URL. 267 The connection MAY provide confidentiality, integrity, or other 268 services, e.g., using TLS. 270 // s/connection/The underlying transport/ s/TLS/IPSEC/ 271 // to avoid confusion with ldaps:// and TLS extension 273 Use of security services is at the client's discretion if not 274 specified in the URL. 276 // Add: but encouraged if request or any potential responses 277 // contain sensitive materials. If the URL represents a update 278 // operation referral, security services should be used. 280 // Insert: 281 // Next, the client SHALL process extensions in order (left to 282 // right) presented which require independent operations and/or 283 // are associated with these options. If any of the extensions 284 // are marked critical and the associated operation is cannot 285 // be completed, no further processing SHALL be attempted. 287 // Insert Start TLS processing 288 // Note that in absence of the start TLS extension, the client may 289 // Start TLS at its discretion. 291 Next, the client authenticates itself to the LDAP server. This step 292 is optional, unless the URL contains a critical bindname extension 293 with a non-NULL value. If a bindname extension is given, the client 294 proceeds according to the section above. 296 // Replace with SASL processing, drop 'Next' as processing is done 297 // in order of options. 299 If a bindname extension is not specified, the client MAY bind to the 300 directory using a appropriate dn and authentication method of its own 301 choosing (including NULL authentication). 303 // s/dn and authentication method/authentication method/mechanism 304 // and credentials/ 305 // Add: 306 // The client may interrogate the server for the most appropriate 307 // method. 309 Next, the client performs the LDAP search operation specified in the 310 URL. Additional fields in the LDAP protocol search request, such as 311 sizelimit, timelimit, deref, and anything else not specified or 312 defaulted in the URL specification, MAY be set at the client's 313 discretion. 315 Once the search has completed, the client MAY close the connection to 316 the LDAP server, or the client MAY keep the connection open for future 317 use. 319 // Any future use must be compatible prior uses. 321 6. Examples 323 The following are some example LDAP URLs using the format defined 324 above. The first example is an LDAP URL referring to the University 325 of Michigan entry, available from an LDAP server of the client's 326 choosing: 328 ldap:///o=University%20of%20Michigan,c=US 330 The next example is an LDAP URL referring to the University of 331 Michigan entry in a particular ldap server: 333 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US 335 Both of these URLs correspond to a base object search of the 336 "o=University of Michigan, c=US" entry using a filter of 337 "(objectclass=*)", requesting all attributes. 339 The next example is an LDAP URL referring to only the postalAddress 340 attribute of the University of Michigan entry: 342 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan, 343 c=US?postalAddress 345 The corresponding LDAP search operation is the same as in the previous 346 example, except that only the postalAddress attribute is requested. 348 The next example is an LDAP URL referring to the set of entries found 349 by querying the given LDAP server on port 6666 and doing a subtree 350 search of the University of Michigan for any entry with a common name 351 of "Babs Jensen", retrieving all attributes: 353 ldap://host.com:6666/o=University%20of%20Michigan, 354 c=US??sub?(cn=Babs%20Jensen) 356 // Modify examples to use example.com/example.net hostnames 358 The next example is an LDAP URL referring to all children of the c=GB 359 entry: 361 ldap://ldap.itd.umich.edu/c=GB?objectClass?one 363 The objectClass attribute is requested to be returned along with the 364 entries, and the default filter of "(objectclass=*)" is used. 366 The next example is an LDAP URL to retrieve the mail attribute for the 367 LDAP entry named "o=Question?,c=US" is given below, illustrating the 368 use of the escaping mechanism on the reserved character '?'. 370 ldap://ldap.question.com/o=Question%3f,c=US?mail 372 The next example illustrates the interaction between LDAP and URL 373 quoting mechanisms. 375 ldap://ldap.netscape.com/o=Babsco,c=US??(int=%5c00%5c00%5c00%5c04) 377 The filter in this example uses the LDAP escaping mechanism of to 378 encode three zero or null bytes in the value. In LDAP, the filter 379 would be written as (int= 0 0 0 4). Because the character must be 380 escaped in a URL, the 's are escaped as %5c in the URL encoding. 382 The final example shows the use of the bindname extension to specify 383 the dn a client should use for authentication when resolving the URL. 385 ldap:///??sub??bindname=cn=Manager%2co=Foo 386 ldap:///??sub??!bindname=cn=Manager%2co=Foo 388 The two URLs are the same, except that the second one marks the 389 bindname extension as critical. Notice the use of the % encoding 390 method to encode the comma in the distinguished name value in the 391 bindname extension. 393 // Add TLS/SASL examples: 394 // ldap://example.net/????!tls,!sasl 395 // ldap://example.net/????sasl 396 // ldap://example.net/????!sasl=external 397 // ldap://example.net/????sasl=gssapi%2cexternal%2cdigest-md5 398 // ldap://example.net/????!sasl,saslopts=!integrity%2c!privacy 399 // ldap://example.net/????tls,sasl,saslopts=integrity%2cprivacy 400 // insert examples of authcId and authzId extensions 402 7. Security Considerations 404 // Add consideration requiring the use of strong authentication 405 // to update the directory. 407 General URL security considerations discussed in [5] are relevant for 408 LDAP URLs. 410 The use of security mechanisms when processing LDAP URLs requires 411 particular care, since clients may encounter many different servers 412 via URLs, and since URLs are likely to be processed automatically, 413 without user intervention. A client SHOULD have a user-configurable 414 policy about which servers to connect to using which security 415 mechanisms, and SHOULD NOT make connections that are inconsistent with 416 this policy. 418 // Comment regarding connection reuse would be appropriate. 420 Sending authentication information, no matter the mechanism, may 421 violate a user's privacy requirements. 423 // Connecting may violate the user's privacy requirements. 425 In the absence of specific policy permitting authentication 426 information to be sent to a server, a client should use an anonymous 427 connection. (Note that clients conforming to previous LDAP URL 428 specifications, where all connections are anonymous and unprotected, 429 are consistent with this specification; they simply have the default 430 security policy.) 432 Some authentication methods, in particular reusable passwords sent to 433 the server, may reveal easily-abused information to the remote server 434 or to eavesdroppers in transit, and should not be used in URL 435 processing unless explicitly permitted by policy. Confirmation by the 436 human user of the use of authentication information is appropriate in 437 many circumstances. Use of strong authentication methods that do not 438 reveal sensitive information is much preferred. 440 The LDAP URL format allows the specification of an arbitrary LDAP 441 search operation to be performed when evaluating the LDAP URL. 442 Following an LDAP URL may cause unexpected results, for example, the 443 retrieval of large amounts of data, the initiation of a long-lived 444 search, etc. The security implications of resolving an LDAP URL are 445 the same as those of resolving an LDAP search query. 447 8. Acknowledgements 449 The LDAP URL format was originally defined at the University of 450 Michigan. This material is based upon work supported by the National 451 Science Foundation under Grant No. NCR-9416667. The support of both 452 the University of Michigan and the National Science Foundation is 453 gratefully acknowledged. 455 Several people have made valuable comments on this document. In 456 particular RL "Bob" Morgan and Mark Wahl deserve special thanks for 457 their contributions. 459 9. References 461 [1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access 462 Protocol (v3): UTF-8 String Representation of Distinguished Names", 463 RFC 2253, December 1997. 465 [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access 466 Protocol (v3)", RFC 2251, December 1997. 468 [3] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight 469 Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 470 2252, December 1997. 472 [4] Howes, T., "A String Representation of LDAP Search Filters", RFC 473 2254, December 1997. 475 [5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource 476 Locators (URL)," RFC 1738, December 1994. 478 [6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement 479 Levels," RFC 2119, March 1997. 481 // Remainder Trimmed 483 // End of RFC 2255 text 485 Additional Information 487 Discussions regarding these suggestions may directed to the author: 489 Kurt D. Zeilenga 490 OpenLDAP Foundation 491 493 or the LDAPext Working Group mailing list: 495 497 Copyright 2000, The Internet Society. All Rights Reserved. 499 This document and translations of it may be copied and furnished 500 to others, and derivative works that comment on or otherwise explain 501 it or assist in its implementation may be prepared, copied, published 502 and distributed, in whole or in part, without restriction of any 503 kind, provided that the above copyright notice and this paragraph 504 are included on all such copies and derivative works. However, 505 this document itself may not be modified in any way, such as by 506 removing the copyright notice or references to the Internet Society 507 or other Internet organizations, except as needed for the purpose 508 of developing Internet standards in which case the procedures for 509 copyrights defined in the Internet Standards process must be 510 followed, or as required to translate it into languages other than 511 English. 513 The limited permissions granted above are perpetual and will not 514 be revoked by the Internet Society or its successors or assigns. 516 This document and the information contained herein is provided on 517 an "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE 518 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS 519 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE 520 OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY 521 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR 522 PURPOSE.