The LDAP URL Format
draft-ietf-asid-ldapv3-url-03
The information below is for an old version of the document that is already published as an RFC.
Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 2255.
|
|
---|---|---|---|
Authors | Mark C. Smith , Tim Howes | ||
Last updated | 2013-03-02 (Latest revision 1997-06-09) | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Intended RFC status | Proposed Standard | ||
Formats | |||
Additional resources | Mailing list discussion | ||
Stream | WG state | (None) | |
Document shepherd | (None) | ||
IESG | IESG state | Became RFC 2255 (Proposed Standard) | |
Consensus boilerplate | Unknown | ||
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-ietf-asid-ldapv3-url-03
Network Working Group Tim Howes
INTERNET DRAFT Mark Smith
OBSOLETES: RFC 1959 Netscape Communications Corp.
June 1997
The LDAP URL Format
<draft-ietf-asid-ldapv3-url-03.txt>
1. Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working docu-
ments 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.''
To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet- 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).
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 func-
tionality, 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 [Page 1]
=0C
RFC DRAFT June 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 =3D token / xtoken
exvalue =3D LDAPString from section 4.1.2 of [2]
token =3D <keystring> from section 4.2.1 of [3]
xtoken =3D ("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 con-
tact.
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 per-
form 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 speci-
fied in [4]. If filter is omitted, a filter of "(objectClass=3D*)" i=
s
assumed.
Howes & Smith [Page 2]
=0C
RFC DRAFT June 1997
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=3Dvalu=
e
pairs. Each type=3Dvalue pair is a separate extension. These LDAP UR=
L
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 pro-
cess the URL if the extension is critical. If an unsupported extension
is non-critical, the client MUST ignore the extension.
Extension types prefixed by "X-" or "x-" are reserved for use in bila-
teral 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) 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 dis-
tinguished 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 dis-
tinguished 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
Howes & Smith [Page 3]
=0C
RFC DRAFT June 1997
appropriate authentication method. Note that for a NULL distinguished
name, no bind MAY be required to obtain anonymous access to the direc-
tory. 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. The connection MAY provide confidentiality, integrity, or
other services, e.g., using TLS. This is not specified in the URL and is
at the client's 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.
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 discre-
tion.
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=3DUS
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 1997
Both of these URLs correspond to a base object search of the
"o=3DUniversity of Michigan, c=3DUS" entry using a filter =
of
"(objectclass=3D*)", 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=
ddress
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)
The next example is an LDAP URL referring to all children of the c=3DG=
B
entry:
ldap://ldap.itd.umich.edu/c=3DGB?objectClass?one
The objectClass attribute is requested to be returned along with the
entries, and the default filter of "(objectclass=3D*)" is used.
The next example is an LDAP URL to retrieve the mail attribute for the
LDAP entry named "o=3DQuestion?,c=3DUS" is given below, illustrating the =
use
of the escaping mechanism on the reserved character '?'.
ldap://ldap.question.com/o=3DQuestion%3f,c=3DUS?mail
The next example illustrates the interaction between LDAP and URL quot-
ing mechanisms.
ldap://ldap.netscape.com/o=3DBabsco,c=3DUS??(int=3D%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). Because the \ character must b=
e
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 1997
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.
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 par-
ticular 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 per-
mitting 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 cir-
cumstances. 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 Michi-
gan. This material is based upon work supported by the National Science
Foundation under Grant No. NCR-9416667. The support of both the Univer-
sity of Michigan and the National Science Foundation is gratefully ack-
nowledged.
Several people have made valuable comments on this document. In
Howes & Smith [Page 6]
=0C
RFC DRAFT June 1997
particular RL "Bob" Morgan and Mark Wahl deserve special thanks for
their contributions.
9. References
[1] Lightweight Directory Access Protocol (v3): UTF-8 String Represen-
tation of Distinguished Names. M. Wahl, S. Kille, draft-ietf-
asid-ldapv3-dn-02.txt, March 1997.
[2] Lightweight Directory Access Protocol (v3). M. Wahl, T. Howes, S.
Kille, draft-ietf-asid-ldapv3-protocol-04.txt, March 1997.
[3] Lightweight Directory Access Protocol (v3): Attribute Syntax Defin-
itions. M. Wahl, A. Coulbeck, T. Howes, S. Kille, draft-ietf-
asid-ldapv3-attributes-04.txt, March 1997.
[4] A String Representation of LDAP Search Filters. T. Howes, draft-
ietf-asid-ldapv3-filter.01.txt, March 1997.
[5] Uniform Resource Locators (URL). T. Berners-Lee, L. Masinter, M.
McCahill, Request for Comment (RFC) 1738, December 1994.
[6] Key Words for use in RFCs to Indicate Requirement Levels, S.
Bradner, RFC 2119, March 1997.
10. Author's Address
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 415 937-3419
howes@netscape.com
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 415 937-3477
mcs@netscape.com
Howes & Smith [Page 7]