One document matched: draft-zeilenga-ldapv3bis-rfc2255-00.txt
INTERNET-DRAFT Kurt D. Zeilenga
Intended Category: Standard Track OpenLDAP Foundation
Expires: 4 January 2001 4 July 2000
LDAPv3bis Suggestions:
The LDAP URL Format
<draft-zeilenga-ldapv3bis-rfc2255-00.txt>
Status of Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
This document is intended to be, after appropriate review and
revision, submitted to the RFC Editor as a Standard Track document.
Distribution of this memo is unlimited. Technical discussion of this
document will take place on the IETF LDAP Extension Working Group
mailing list <ietf-ldapext@netscape.com>. Please send editorial
comments directly to the author <Kurt@OpenLDAP.org>.
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as ``work in progress.''
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft
Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
Copyright 2000, The Internet Society. All Rights Reserved.
Please see the Copyright section near the end of this document for
more information.
Forward
This Internet Draft suggests a number of updates to "The LDAP URL
Format" [RFC 2255]. This document is not intended to be published as
an RFC but used to identify LDAPv3bis work items.
The remainer of this documents incorporates the substantive portion of
RFC 2255 text (less status of memo, appendices, etc). Comments and
suggested updates to this text are inserted as inline notes prefixed
Zeilenga [Page 1]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
with '//'.
// Start of RFC 2255 text
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.
// Or, in the context of an Referral resulting from a non-search
// operation, the format describes a reference to service where
// the operation may be progressed.
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.
// Add:
// A number of extensions are defined to support mandatory
// to implement authentication and privacy features.
The key words "MUST", "MAY", and "SHOULD" used in this document are to
be interpreted as described in [6].
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]
Zeilenga [Page 2]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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.
// or the target of a non-search operation.
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
// remove duplicated text
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.
// remove duplicated text
The dn is an LDAP Distinguished Name using the string format described
in [1]. It identifies the base object of the LDAP search.
// remove duplicated text
// Attributes, scope, and filter components SHOULD NOT be present
// when non-search referral URLs. If present, the referral should
// be treated as a protocol error.
Zeilenga [Page 3]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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.
// In the context of a search continuation, if scope is omitted,
// the scope derived by the scope of the original operation. If
// the original operation had scope subtree, a scope of "subtree"
// shall be assumed. If the original scope was one-level, scope
// of "base" shall be assumed. If the original scope was base,
// the continuation should be treated as a protocol error.
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.
// Except in the context of a referral or search continuation where
// the original filter should be reused.
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.
If a critical extension cannot be processed successfully by the
Zeilenga [Page 4]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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.
// Add:
// As extensions may relate to operations and/or controls upon
// options, they shall be processed in order (left-to-right)
presented.
One LDAP URL extension is defined in this document in the next
section.
// Replace:
// Multiple URL extensions are defined in this document in following
// 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.
// Insert:
// 4. URL Extensions
//
// Insert descriptions of TLS (StartTLS), sasl, and related
// extensions here. Text for these extensions will initially
// be provided in a separate draft but eventually inserted
// here. Examples using these extensions, however, are
// provided below.
4. The Bindname Extension
// Change to 4.x
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.
Zeilenga [Page 5]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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.
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.
// if the open connection is compatible with URL.
The connection MAY provide confidentiality, integrity, or other
services, e.g., using TLS.
// s/connection/The underlying transport/ s/TLS/IPSEC/
// to avoid confusion with ldaps:// and TLS extension
Use of security services is at the client's discretion if not
specified in the URL.
// Add: but encouraged if request or any potential responses
// contain sensitive materials. If the URL represents a update
// operation referral, security services should be used.
// Insert:
// Next, the client SHALL process extensions in order (left to
// right) presented which require independent operations and/or
// are associated with these options. If any of the extensions
// are marked critical and the associated operation is cannot
// be completed, no further processing SHALL be attempted.
// Insert Start TLS processing
// Note that in absence of the start TLS extension, the client may
Zeilenga [Page 6]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
// Start TLS at its discretion.
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.
// Replace with SASL processing, drop 'Next' as processing is done
// in order of options.
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).
// s/dn and authentication method/authentication method/mechanism
// and credentials/
// Add:
// The client may interrogate the server for the most appropriate
// method.
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.
// Any future use must be compatible prior uses.
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
Zeilenga [Page 7]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
"(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=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)
// Modify examples to use example.com/example.net hostnames
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= 0 0 0 4). 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.
Zeilenga [Page 8]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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
bindname extension.
// Add TLS/SASL examples:
// ldap://example.net/????!tls,!sasl
// ldap://example.net/????sasl
// ldap://example.net/????!sasl=external
// ldap://example.net/????sasl=gssapi%2cexternal%2cdigest-md5
// ldap://example.net/????!sasl,saslopts=!integrity%2c!privacy
// ldap://example.net/????tls,sasl,saslopts=integrity%2cprivacy
// insert examples of authcId and authzId extensions
7. Security Considerations
// Add consideration requiring the use of strong authentication
// to update the directory.
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.
// Comment regarding connection reuse would be appropriate.
Sending authentication information, no matter the mechanism, may
violate a user's privacy requirements.
// Connecting may violate the 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
Zeilenga [Page 9]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
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.
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.
Zeilenga [Page 10]
INTERNET-DRAFT draft-zeilenga-ldapv3bis-rfc2255-00 4 July 2000
// Remainder Trimmed
// End of RFC 2255 text
Additional Information
Discussions regarding these suggestions may directed to the author:
Kurt D. Zeilenga
OpenLDAP Foundation
<Kurt@OpenLDAP.org>
or the LDAPext Working Group mailing list:
<ietf-ldapext@netscape.com>
Copyright 2000, The Internet Society. 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 AUTHORS, 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.
Zeilenga [Page 11]
| PAFTECH AB 2003-2026 | 2026-04-23 09:40:47 |