Network Working Group                                        Tim Howes
INTERNET DRAFT                                              Mark Smith
OBSOLETES: RFC 1959                      Netscape Communications Corp.
                                                              May 1997

                          The LDAP URL Format

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 (US East Coast),  (Europe), (US West Coast), or (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.  This  docu-
ment  also  defines a second URL scheme prefix for LDAP running over the
TLS protocol defined in [6].

Howes & Smith                                                   [Page 1]

RFC DRAFT                                                       May 1997

3.  URL Definition

An LDAP URL begins with  the  protocol  prefix  "ldap"  (or  the  prefix
"ldaps" for LDAP over TLS) and is defined by the following grammar.

    ldapurl    = scheme "://" [hostport] "/"
                 [dn ["?" [attributes] ["?" [scope]
                 ["?" [filter]]]]]
    scheme     = "ldap" / "ldaps"
    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]

The "ldap" and "ldaps" prefixes indicate an entry or entries residing in
the  LDAP  server running on the given hostname at the given portnumber.
For regular LDAP servers, the default port is TCP port  389.   For  LDAP
servers running over the TLS protocol [6], the default port is 636.

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 attributes of the entry or entries should be requested.

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=*)"  is

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 part of the URL is missing, the URL can
be resolved by contacting any X.500-back-ended LDAP server.

Note that any URL-illegal characters (e.g.,  spaces)  and  the  reserved
character '?' occurring inside a dn, filter, or other element of an LDAP
URL must be escaped using the % method described in RFC 1738 [5].

Howes & Smith                                                   [Page 2]

RFC DRAFT                                                       May 1997

4.  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 any X.500-capable LDAP server:


The next example is an LDAP URL referring to the University of  Michigan
entry in a particular ldap server:


The URL corresponds 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:


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:


The next example is a secure LDAP URL referring to all children  of  the
c=GB entry:


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 '?'.


The final example illustrates the interaction between LDAP and URL quot-
ing mechanisms.

Howes & Smith                                                   [Page 3]

RFC DRAFT                                                       May 1997


The filter used 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.

5.  Security Considerations

The LDAP URL format does not provide a way to specify credentials to use
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.  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]  The TLS Protocol Version 1.0., T.  Dierks,  C.  Allen,  draft-ietf-
     tls-protocol-02.txt, March 1997.

7.  Author's Address

   Tim Howes
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043

Howes & Smith                                                   [Page 4]

RFC DRAFT                                                       May 1997

   +1 415 937-3419

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   +1 415 937-3477

Howes & Smith                                                   [Page 5]