rfc2255.txt

RFC 的详细文档！

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]