view Side-By-Side changes
Date: Tue, 09 Apr 2002 00:53:47 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Mon, 09 Jun 1997 12:02:00 GMT ETag: "2e9d4e-3e2f-339bf0b8" Accept-Ranges: bytes Content-Length: 15919 Connection: close Content-Type: text/plain Network Working GroupTimT. HowesINTERNET DRAFT MarkRequest for Comments: 2255 M. SmithOBSOLETES: RFC 1959Category: Standards Track Netscape Communications Corp.JuneDecember 1997 The LDAP URL Format<draft-ietf-asid-ldapv3-url-03.txt>1. Status of this Memo This documentisspecifies anInternet-Draft. Internet-Drafts are working docu- ments ofInternet standards track protocol for the InternetEngineering Task Force (IETF), its areas,community, andits working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents validrequests discussion and suggestions fora maximumimprovements. Please refer to the current edition ofsix monthsthe "Internet Official Protocol Standards" (STD 1) for the standardization state andmay be updated, replaced, or obsoleted by other documents atstatus of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1997). All Rights Reserved. IESG NOTE This document describes a directory access protocol that provides both read and update access. Update access requires secure authentication, but this document does not mandate implementation of anytime. Itsatisfactory authentication mechanisms. In accordance with RFC 2026, section 4.4.1, this specification isinappropriate to use Internet- Draftsbeing approved by IESG asreference materiala Proposed Standard despite this limitation, for the following reasons: a. to encourage implementation and interoperability testing of these protocols (with or without update access) before they are deployed, and b. tocite themencourage deployment and use of these protocols in read-only applications. (e.g. applications where LDAPv3 is used as a query language for directories which are updated by some secure mechanism other thanas ``work in progress.'' To learnLDAP), and c. to avoid delaying thecurrent statusadvancement and deployment ofany Internet-Draft, please checkother Internet standards-track protocols which require the``1id-abstracts.txt'' listing contained inability to query, but not update, LDAPv3 directory servers. Howes & Smith Standards Track [Page 1] RFC 2255 LDAP URL Format December 1997 Readers are hereby warned that until mandatory authentication mechanisms are standardized, clients and servers written according to this specification which make use of update functionality are UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. Implementors are hereby discouraged from deploying LDAPv3 clients or servers which implement theInternet- Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).update functionality, until a Proposed Standard for mandatory authentication in LDAPv3 has been approved and published as an RFC. 2. Abstract LDAP is the Lightweight Directory Access Protocol, defined in [1], [2] and [3]. This document describes a format for an LDAP Uniform Resource Locator. The format describes an LDAP search operation to perform to retrieve information from an LDAP directory. This document replaces RFC 1959. It updates the LDAP URL format for version 3 of LDAP and clarifies how LDAP URLs are resolved. This document also defines an extension mechanism for LDAP URLs, so that future documents can extend theirfunc- tionality,functionality, for example, to provide access to new LDAPv3 extensions as they are defined. The key words "MUST", "MAY", and "SHOULD" used in this document are to be interpreted as described in [6]. Howes & Smith Standards Track [Page1] =0C2] RFCDRAFT June2255 LDAP URL Format December 1997 3. URL Definition An LDAP URL begins with the protocol prefix "ldap" and is defined by the following grammar. ldapurl=3D= scheme "://" [hostport] ["/" [dn ["?" [attributes] ["?" [scope] ["?" [filter] ["?" extensions]]]]]] scheme=3D= "ldap" attributes=3D= attrdesc *("," attrdesc) scope=3D= "base" / "one" / "sub" dn=3D= distinguishedName from Section 3 of [1] hostport=3D= hostport from Section 5 of RFC 1738 [5] attrdesc=3D= AttributeDescription from Section 4.1.5 of [2] filter=3D= filter from Section 4 of [4] extensions=3D= extension *("," extension) extension=3D= ["!"] extype"=3D"["=" exvalue] extype = token / xtoken exvalue = LDAPString from section 4.1.2 of [2] token = oid from section 4.1 of [3] xtoken = ("X-" / "x-") token The "ldap" prefix indicates an entry or entries residing in the LDAP server running on the given hostname at the given portnumber. The default LDAP port is TCP port 389. If no hostport is given, the client must have some apriori knowledge of an appropriate LDAP server to contact. The dn is an LDAP Distinguished Name using the string format described in [1]. It identifies the base object of the LDAP search. ldapurl = scheme "://" [hostport] ["/" [dn ["?" [attributes] ["?" [scope] ["?" [filter] ["?" extensions]]]]]] scheme = "ldap" attributes = attrdesc *("," attrdesc) scope = "base" / "one" / "sub" dn = distinguishedName from Section 3 of [1] hostport = hostport from Section 5 of RFC 1738 [5] attrdesc = AttributeDescription from Section 4.1.5 of [2] filter = filter from Section 4 of [4] extensions = extension *("," extension) extension = ["!"] extype ["=" exvalue] extype=3D= token / xtoken exvalue=3D= LDAPString from section 4.1.2 of [2] token=3D <keystring>= oid from section4.2.14.1 of [3] xtoken=3D= ("X-" / "x-") token Howes & Smith Standards Track [Page 3] RFC 2255 LDAP URL Format December 1997 The "ldap" prefix indicates an entry or entries residing in the LDAP server running on the given hostname at the given portnumber. The default LDAP port is TCP port 389. If no hostport is given, the client must have some apriori knowledge of an appropriate LDAP server tocon- tact.contact. The dn is an LDAP Distinguished Name using the string format described in [1]. It identifies the base object of the LDAP search. The attributes construct is used to indicate which attributes should be returned from the entry or entries. Individual attrdesc names are as defined for AttributeDescription in [2]. If the attributes part is omitted, all user attributes of the entry or entries should be requested (e.g., by setting the attributes field AttributeDescriptionList in the LDAP search request to a NULL list, or (in LDAPv3) by requesting the special attribute name "*"). The scope construct is used to specify the scope of the search toper- formperform in the given LDAP server. The allowable scopes are "base" for a base object search, "one" for a one-level search, or "sub" for a subtree search. If scope is omitted, a scope of "base" is assumed. The filter is used to specify the search filter to apply to entries within the specified scope during the search. It has the formatspeci- fiedspecified in [4]. If filter is omitted, a filter of"(objectClass=3D*)" i= s"(objectClass=*)" is assumed.Howes & Smith [Page 2] =0C RFC DRAFT June 1997The extensions construct provides the LDAP URL with an extensibility mechanism, allowing the capabilities of the URL to be extended in the future. Extensions are a simple comma-separated list oftype=3Dvalu= e pairs.type=value pairs, where the =value portion MAY be omitted for options not requiring it. Eachtype=3Dvaluetype=value pair is a separate extension. These LDAPUR= LURL extensions are not necessarily related to any of the LDAPv3 extension mechanisms. Extensions may be supported or unsupported by the client resolving the URL. An extension prefixed with a '!' character (ASCII 33) is critical. An extension not prefixed with a'!'' !' character isnon- critical.non-critical. If an extension is supported by the client, the client MUST obey the extension if the extension is critical. The client SHOULD obey supported extensions that are non-critical. If an extension is unsupported by the client, the client MUST NOTpro- cessprocess the URL if the extension is critical. If an unsupported extension is non-critical, the client MUST ignore the extension. Howes & Smith Standards Track [Page 4] RFC 2255 LDAP URL Format December 1997 If a critical extension cannot be processed successfully by the client, the client MUST NOT process the URL. If a non-critical extension cannot be processed successfully by the client, the client SHOULD ignore the extension. Extension types prefixed by "X-" or "x-" are reserved for use inbila- teralbilateral agreements between communicating parties. Other extension types MUST be defined in this document, or in other standards-track documents. One LDAP URL extension is defined in this document in the next section. Other documents or a future version of this document MAY define other extensions. Note that any URL-illegal characters (e.g.,spaces)spaces), URL special characters (as defined in section 2.2 of RFC 1738) and the reserved character '?' (ASCII 63) occurring inside a dn, filter, or other element of an LDAP URL MUST be escaped using the % method described in RFC 1738 [5]. If a comma character ',' occurs inside an extension value, the character MUST also be escaped using the % method. 4. The Bindname Extension This section defines an LDAP URL extension for representing thedis- tinguisheddistinguished name for a client to use when authenticating to an LDAP directory during resolution of an LDAP URL. Clients MAY implement this extension. The extension type is "bindname". The extension value is thedis- tinguisheddistinguished name of the directory entry to authenticate as, in the same form as described for dn in the grammar above. The dn may be the NULL string to specify unauthenticated access. The extension may be either critical (prefixed with a '!' character) or non-critical (not prefixed with a '!' character). If the bindname extension is critical, the client resolving the URL MUST authenticate to the directory using the given distinguished name and anHowes & Smith [Page 3] =0C RFC DRAFT June 1997appropriate authentication method. Note that for a NULL distinguished name, no bind MAY be required to obtain anonymous access to thedirec- tory.directory. If the extension is non-critical, the client MAY bind to the directory using the given distinguished name. 5. URL Processing This section describes how an LDAP URL SHOULD be resolved by a client. Howes & Smith Standards Track [Page 5] RFC 2255 LDAP URL Format December 1997 First, the client obtains a connection to the LDAP server referenced in the URL, or an LDAP server of the client's choice if no LDAP server is explicitly referenced. This connection MAY be opened specifically for the purpose of resolving the URL or the client MAY reuse an already open connection. The connection MAY provide confidentiality, integrity, or other services, e.g., using TLS.ThisUse of security services is at the client's discretion if not specified in theURL and is at the client's discretion.URL. Next, the client authenticates itself to the LDAP server. This step is optional, unless the URL contains a critical bindname extension with a non-NULL value. If a bindname extension is given, the client proceeds according to the section above. If a bindname extension is not specified, the client MAY bind to the directory using a appropriate dn and authentication method of its own choosing (including NULL authentication). Next, the client performs the LDAP search operation specified in the URL. Additional fields in the LDAP protocol search request, such as sizelimit, timelimit, deref, and anything else not specified or defaulted in the URL specification, MAY be set at the client'sdiscre- tion.discretion. Once the search has completed, the client MAY close the connection to the LDAP server, or the client MAY keep the connection open for future use. 6. Examples The following are some example LDAP URLs using the format defined above. The first example is an LDAP URL referring to the University of Michigan entry, available from an LDAP server of the client's choosing:ldap:///o=3DUniversity%20of%20Michigan,c=3DUSldap:///o=University%20of%20Michigan,c=US The next example is an LDAP URL referring to the University of Michigan entry in a particular ldap server:ldap://ldap.itd.umich.edu/o=3DUniversity%20of%20Michigan,c=3DUS Howes & Smith [Page 4] =0C RFC DRAFT June 1997ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US Both of these URLs correspond to a base object search of the"o=3DUniversity"o=University of Michigan,c=3DUS"c=US" entry using a filter=of"(objectclass=3D*)","(objectclass=*)", requesting all attributes. The next example is an LDAP URL referring to only the postalAddress attribute of the University of Michigan entry:ldap://ldap.itd.umich.edu/o=3DUniversity%20of%20Michigan,c=3DUS?postalA= ddressHowes & Smith Standards Track [Page 6] RFC 2255 LDAP URL Format December 1997 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan, c=US?postalAddress The corresponding LDAP search operation is the same as in the previous example, except that only the postalAddress attribute is requested. The next example is an LDAP URL referring to the set of entries found by querying the given LDAP server on port 6666 and doing a subtree search of the University of Michigan for any entry with a common name of "Babs Jensen", retrieving all attributes:ldap://host.com:6666/o=3DUniversity%20of%20Michigan,c=3DUS??sub?(cn=3DB= abs%20Jensen)ldap://host.com:6666/o=University%20of%20Michigan, c=US??sub?(cn=Babs%20Jensen) The next example is an LDAP URL referring to all children of thec=3DG= Bc=GB entry:ldap://ldap.itd.umich.edu/c=3DGB?objectClass?oneldap://ldap.itd.umich.edu/c=GB?objectClass?one The objectClass attribute is requested to be returned along with the entries, and the default filter of"(objectclass=3D*)""(objectclass=*)" is used. The next example is an LDAP URL to retrieve the mail attribute for the LDAP entry named"o=3DQuestion?,c=3DUS""o=Question?,c=US" is given below, illustrating the=use of the escaping mechanism on the reserved character '?'.ldap://ldap.question.com/o=3DQuestion%3f,c=3DUS?mailldap://ldap.question.com/o=Question%3f,c=US?mail The next example illustrates the interaction between LDAP and URLquot- ingquoting mechanisms.ldap://ldap.netscape.com/o=3DBabsco,c=3DUS??(int=3D%5c00%5c00%5c00%5c04= )ldap://ldap.netscape.com/o=Babsco,c=US??(int=%5c00%5c00%5c00%5c04) The filter in this example uses the LDAP escaping mechanism of \ to encode three zero or null bytes in the value. In LDAP, the filter would be written as(int=3D\00\00\00\04).(int=\00\00\00\04). Because the \ character mustb= ebe escaped in a URL, the \'s are escaped as %5c in the URL encoding. The final example shows the use of the bindname extension to specify the dn a client should use for authentication when resolving the URL.ldap:///??sub??bindname=3Dcn=3DManager%2co=3DFoo ldap:///??sub??!bindname=3Dcn=3DManager%2co=3DFoo Howes & Smith [Page 5] =0C RFC DRAFT June 1997ldap:///??sub??bindname=cn=Manager%2co=Foo ldap:///??sub??!bindname=cn=Manager%2co=Foo The two URLs are the same, except that the second one marks the bindname extension as critical. Notice the use of the % encoding method to encode the comma in the distinguished name value in the Howes & Smith Standards Track [Page 7] RFC 2255 LDAP URL Format December 1997 bindname extension. 7. Security Considerations General URL security considerations discussed in [5] are relevant for LDAP URLs. The use of security mechanisms when processing LDAP URLs requirespar- ticularparticular care, since clients may encounter many different servers via URLs, and since URLs are likely to be processed automatically, without user intervention. A client SHOULD have a user-configurable policy about which servers to connect to using which security mechanisms, and SHOULD NOT make connections that are inconsistent with this policy. Sending authentication information, no matter the mechanism, may violate a user's privacy requirements. In the absence of specific policyper- mittingpermitting authentication information to be sent to a server, a client should use an anonymous connection. (Note that clients conforming to previous LDAP URL specifications, where all connections are anonymous and unprotected, are consistent with this specification; they simply have the default security policy.) Some authentication methods, in particular reusable passwords sent to the server, may reveal easily-abused information to the remote server or to eavesdroppers in transit, and should not be used in URL processing unless explicitly permitted by policy. Confirmation by the human user of the use of authentication information is appropriate in manycir- cumstances.circumstances. Use of strong authentication methods that do not reveal sensitive information is much preferred. The LDAP URL format allows the specification of an arbitrary LDAP search operation to be performed when evaluating the LDAP URL. Following an LDAP URL may cause unexpected results, for example, the retrieval of large amounts of data, the initiation of a long-lived search, etc. The security implications of resolving an LDAP URL are the same as those of resolving an LDAP search query. 8. Acknowledgements The LDAP URL format was originally defined at the University ofMichi- gan.Michigan. This material is based upon work supported by the National Science Foundation under Grant No. NCR-9416667. The support of both theUniver- sityUniversity of Michigan and the National Science Foundation is gratefullyack- nowledged.acknowledged. Howes & Smith Standards Track [Page 8] RFC 2255 LDAP URL Format December 1997 Several people have made valuable comments on this document. InHowes & Smith [Page 6] =0C RFC DRAFT June 1997particular RL "Bob" Morgan and Mark Wahl deserve special thanks for their contributions. 9. References [1]LightweightWahl, M., Kille, S., and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 StringRepresen- tationRepresentation of DistinguishedNames. M.Names", RFC 2253, December 1997. [2] Wahl, M., Howes, T., and S. Kille,draft-ietf- asid-ldapv3-dn-02.txt, March 1997. [2] Lightweight"Lightweight Directory Access Protocol(v3). M.(v3)", RFC 2251, December 1997. [3] Wahl,T.M., Coulbeck, A., Howes, T. and S. Kille,draft-ietf-asid-ldapv3-protocol-04.txt, March 1997. [3] Lightweight"Lightweight Directory Access Protocol (v3): Attribute SyntaxDefin- itions. M. Wahl, A. Coulbeck, T. Howes, S. Kille, draft-ietf- asid-ldapv3-attributes-04.txt, MarchDefinitions", RFC 2252, December 1997. [4]AHowes, T., "A String Representation of LDAP SearchFilters. T. Howes, draft- ietf-asid-ldapv3-filter.01.txt, MarchFilters", RFC 2254, December 1997. [5]Uniform Resource Locators (URL). T.Berners-Lee,L.T., Masinter, L. and M. McCahill,Request for Comment (RFC)"Uniform Resource Locators (URL)," RFC 1738, December 1994. [6]KeyBradner, S., "Key Words for use in RFCs to Indicate RequirementLevels, S. Bradner,Levels," RFC 2119, March 1997.10. Author's AddressAuthors' Addresses Tim Howes Netscape Communications Corp. 501 E. Middlefield Rd. Mountain View, CA 94043 USA Phone: +1 415 937-3419 EMail: howes@netscape.com Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd. Mountain View, CA 94043 USA Phone: +1 415 937-3477 EMail: mcs@netscape.com Howes & Smith Standards Track [Page7]9] RFC 2255 LDAP URL Format December 1997 Full Copyright Statement Copyright (C) The Internet Society (1997). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Howes & Smith Standards Track [Page 10] ----