diff options
Diffstat (limited to 'source4/ldap_server/devdocs/rfc2255.txt')
| -rw-r--r-- | source4/ldap_server/devdocs/rfc2255.txt | 563 |
1 files changed, 0 insertions, 563 deletions
diff --git a/source4/ldap_server/devdocs/rfc2255.txt b/source4/ldap_server/devdocs/rfc2255.txt deleted file mode 100644 index a03567154e..0000000000 --- a/source4/ldap_server/devdocs/rfc2255.txt +++ /dev/null @@ -1,563 +0,0 @@ - - - - - - -Network Working Group T. Howes -Request for Comments: 2255 M. Smith -Category: Standards Track Netscape Communications Corp. - December 1997 - - - The LDAP URL Format - -1. Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status 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 - any satisfactory authentication mechanisms. - - In accordance with RFC 2026, section 4.4.1, this specification is - being approved by IESG as a 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. to encourage 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 than LDAP), and - - c. to avoid delaying the advancement and deployment of other Internet - standards-track protocols which require the ability 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 the 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 their 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 [Page 2] - -RFC 2255 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 = 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 = 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 = token / xtoken - exvalue = LDAPString from section 4.1.2 of [2] - token = oid from section 4.1 of [3] - xtoken = ("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 - 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. - - 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 to - perform 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 format - specified in [4]. If filter is omitted, a filter of - "(objectClass=*)" is assumed. - - The 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 of type=value - pairs, where the =value portion MAY be omitted for options not - requiring it. Each type=value pair is a separate extension. These - LDAP URL 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 is 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 NOT - process 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 in - bilateral 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), 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 the - distinguished 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 the - distinguished 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 an appropriate authentication method. Note that for a NULL - distinguished name, no bind MAY be required to obtain anonymous - access to the 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. Use - of security services is at the client's discretion if not specified - in the 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's - 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=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=University%20of%20Michigan,c=US - - Both of these URLs correspond to a base object search of the - "o=University of Michigan, c=US" entry using a filter of - "(objectclass=*)", requesting all attributes. - - The next example is an LDAP URL referring to only the postalAddress - attribute of the University of Michigan entry: - - - -Howes & 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=University%20of%20Michigan, - c=US??sub?(cn=Babs%20Jensen) - - The next example is an LDAP URL referring to all children of the c=GB - entry: - - ldap://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=*)" is used. - - The next example is an LDAP URL to retrieve the mail attribute for - the LDAP entry named "o=Question?,c=US" is given below, illustrating - the use of the escaping mechanism on the reserved character '?'. - - ldap://ldap.question.com/o=Question%3f,c=US?mail - - The next example illustrates the interaction between LDAP and URL - quoting mechanisms. - - 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=\00\00\00\04). Because the \ character must - be 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=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 requires - particular 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 - policy permitting 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 many 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 of - Michigan. This material is based upon work supported by the National - Science Foundation under Grant No. NCR-9416667. The support of both - the University of Michigan and the National Science Foundation is - gratefully acknowledged. - - - - - - -Howes & Smith Standards Track [Page 8] - -RFC 2255 LDAP URL Format December 1997 - - - Several people have made valuable comments on this document. In - particular RL "Bob" Morgan and Mark Wahl deserve special thanks for - their contributions. - -9. References - - [1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access - Protocol (v3): UTF-8 String Representation of Distinguished Names", - RFC 2253, December 1997. - - [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access - Protocol (v3)", RFC 2251, December 1997. - - [3] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight - Directory Access Protocol (v3): Attribute Syntax Definitions", RFC - 2252, December 1997. - - [4] Howes, T., "A String Representation of LDAP Search Filters", RFC - 2254, December 1997. - - [5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource - Locators (URL)," RFC 1738, December 1994. - - [6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement - Levels," RFC 2119, March 1997. - -Authors' 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 [Page 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] - |