view Side-By-Side changes
Network Working Group Tim Howes
INTERNET DRAFT Mark Smith
OBSOLETES: RFC 1959 Netscape Communications Corp.
March
Expires in six months April 1997
The LDAP URL Format
<draft-ietf-asid-ldapv3-url-00.txt>
<draft-ietf-asid-ldapv3-url-01.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 defines a
way to indicate whether the URL references a master or slave server. LDAP. This document docu-
ment also defines a second URL scheme prefix for LDAP running over the secure sockets layer protocol.
TLS protocol defined in [6].
Howes & Smith [Page 1]
INTERNET
RFC DRAFT March April 1997
3. URL Definition
An LDAP URL begins with the protocol prefix "ldap" (or the prefix
"ldaps" for LDAP over SSL) TLS) and is defined by the following grammar.
<ldapurl> ::= <scheme>
ldapurl = scheme "://" [ <hostport> ] [hostport] "/"
[ <dn> [ "?" [ <attributes> ] [ "?" [ <scope> ]
[ "?" [ <filter> ] [ "?" <masterorslave> ] ] ] ] ]
<scheme> ::=
[dn ["?" [attributes] ["?" [scope]
["?" [filter]]]]]
scheme = "ldap" | / "ldaps"
<hostport> ::= <hostname> [ ":" <portnumber> ]
<dn> ::= a distinguished name string as defined in [1]
<attributes> ::= NULL
| <attributedesc>
| <attributedesc> [ "," <attributes> ]
<attributedesc> ::= an AttributeDescription string as defined in [3]
<scope> ::=
attributes = [attrdesc *("," attrdesc)]
scope = "base" | / "one" | / "sub"
<filter> ::= a
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 string as defined in = filter from Section 4 of [4]
<masterorslave> ::= "master" | "slave"
The "ldap" and "ldaps" prefixes indicate an entry or entries residing in
the LDAP server running on the given <hostname> hostname at the given <port-
number>. portnumber.
For regular LDAP servers, the default port is TCP port 389. For LDAP
servers running over secure sockets layer transport the TLS protocol [6], the default port is 636.
The <dn> dn is an LDAP Distinguished Name using the string format described
in [1]. It identifies the base object of the LDAP search.
The <attributes> attributes construct is used to indicate which attributes should be
returned from the entry or entries. Individual <attributetype> attrdesc names are as
defined for AttributeType AttributeDescription in RFC 1777. [2]. If the <attributes> attributes part is
omitted, all attributes of the entry or entries should be returned.
The <scope> 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> scope is omitted, a scope of "base" is assumed.
The <filter> filter is used to specify the search filter to apply to entries
within the specified scope during the search. It has the format
Howes & Smith [Page 2]
INTERNET DRAFT March 1997
specified speci-
fied in [4]. If <filter> filter is omitted, a filter of "(objectClass=*)" is
assumed.
The <masterorslave> construct is optionally used to indicate whether the
LDAP URL refers to a master LDAP server (i.e., one able to update the
data referenced) or a slave LDAP server (i.e., one unable to update the
data referenced).
Note that if
If the entry or entries reside in the X.500 namespace, they should be
reachable from any LDAP server that is providing front-end access to the
X.500 directory. If the <hostport> hostport part of the URL is missing, the URL can
be resolved by contacting any X.500-back-ended LDAP server.
Note that any any URL-illegal characters (e.g., spaces) and the reserved
character '?' occurring inside a <dn>, <filter>, dn, filter, or other element of an LDAP
URL must be escaped using the % method described in RFC 1738. 1738 [5].
Howes & Smith [Page 2]
RFC DRAFT April 1997
4. Examples
The following are some example LDAP URLs using the format defined above.
An LDAP URL referring to the University of Michigan entry, available
from any X.500-capable LDAP server:
ldap:///o=University%20of%20Michigan,c=US
An LDAP URL referring to the University of Michigan entry in a particu-
lar ldap server:
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
This URL corresponds to a base object search of the "o=University of
Michigan, c=US" entry using a filter of (objectclass=*), requesting all
attributes.
An LDAP URL referring to only the postalAddress attribute of the Univer-
sity 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.
An LDAP URL referring to the set of entries found by querying any
X.500-capable LDAP server and doing a subtree search of the University
of Michigan for any entry with a common name of "Babs Jensen", retriev-
ing all attributes:
Howes & Smith [Page 3]
INTERNET DRAFT March 1997
ldap:///o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
A secure LDAP URL referring to the master server containing all children of the c=GB entry:
ldaps://ldap.itd.umich.edu/c=GB?objectClass?one??master
ldaps://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.
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
5. Security Considerations
The LDAP URL format does not provide a way to specify credentials to use
Howes & Smith [Page 3]
RFC DRAFT April 1997
when resolving the URL. Therefore, it is expected that such requests
will be unauthenticated, unless some out-of-band mechanism is used.
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.
6. Bibliography 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.00.txt, March 1997.
[5] Uniform Resource Locators (URL). T. Berners-Lee, L. Masinter, M.
McCahill, Request for Comment (RFC) 1738, December 1994.
[6] The SSL TLS Protocol Version 3.0. A. Freier, P. Karlton, P. Kocher,
draft-ietf-tls-ssl-version3-00.txt, November 1996. 1.0., T. Dierks, C. Allen, draft-ietf-
tls-protocol-02.txt, March 1997.
7. Author's Address
Tim Howes
Howes & Smith [Page 4]
INTERNET DRAFT March 1997
University of Michigan
ITD Research Systems
535 W William St.
Ann Arbor, MI 48103-4943
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 313 747-4454
tim@umich.edu 415 937-3419
howes@netscape.com
Mark Smith
University of Michigan
ITD Research Systems
535 W William St.
Ann Arbor, MI 48103-4943
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 313 764-2277
mcs@umich.edu 415 937-3477
mcs@netscape.com
Howes & Smith [Page 5] 4]
----