rfc4516.txt

samba最新软件

Network Working Group                                      M. Smith, Ed.
Request for Comments: 4516                           Pearl Crescent, LLC
Obsoletes: 2255                                                 T. Howes
Category: Standards Track                                  Opsware, Inc.
                                                               June 2006


             Lightweight Directory Access Protocol (LDAP):
                        Uniform Resource Locator

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 (2006).

Abstract

   This document describes a format for a Lightweight Directory Access
   Protocol (LDAP) Uniform Resource Locator (URL).  An LDAP URL
   describes an LDAP search operation that is used to retrieve
   information from an LDAP directory, or, in the context of an LDAP
   referral or reference, an LDAP URL describes a service where an LDAP
   operation may be progressed.

Table of Contents

   1. Introduction ....................................................2
   2. URL Definition ..................................................2
      2.1. Percent-Encoding ...........................................4
   3. Defaults for Fields of the LDAP URL .............................5
   4. Examples ........................................................6
   5. Security Considerations .........................................8
   6. Normative References ............................................9
   7. Informative References .........................................10
   8. Acknowledgements ...............................................10
   Appendix A: Changes Since RFC 2255 ................................11
      A.1. Technical Changes .........................................11
      A.2. Editorial Changes .........................................11






Smith & Howes               Standards Track                     [Page 1]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


1.  Introduction

   LDAP is the Lightweight Directory Access Protocol [RFC4510].  This
   document specifies 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.  This mechanism may be used to
   provide access to new LDAP extensions.

   Note that not all the parameters of the LDAP search operation
   described in [RFC4511] can be expressed using the format defined in
   this document.  Note also that URLs may be used to represent
   reference knowledge, including that for non-search operations.

   This document is an integral part of the LDAP technical specification
   [RFC4510], which obsoletes the previously defined LDAP technical
   specification, RFC 3377, in its entirety.

   This document replaces RFC 2255.  See Appendix A for a list of
   changes relative to RFC 2255.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14 [RFC2119].

2.  URL Definition

   An LDAP URL begins with the protocol prefix "ldap" and is defined by
   the following grammar, following the ABNF notation defined in
   [RFC4234].

      ldapurl     = scheme COLON SLASH SLASH [host [COLON port]]
                       [SLASH dn [QUESTION [attributes]
                       [QUESTION [scope] [QUESTION [filter]
                       [QUESTION extensions]]]]]
                                      ; <host> and <port> are defined
                                      ;   in Sections 3.2.2 and 3.2.3
                                      ;   of [RFC3986].
                                      ; <filter> is from Section 3 of
                                      ;   [RFC4515], subject to the
                                      ;   provisions of the
                                      ;   "Percent-Encoding" section
                                      ;   below.

      scheme      = "ldap"







Smith & Howes               Standards Track                     [Page 2]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


      dn          = distinguishedName ; From Section 3 of [RFC4514],
                                      ; subject to the provisions of
                                      ; the "Percent-Encoding"
                                      ; section below.

      attributes  = attrdesc *(COMMA attrdesc)
      attrdesc    = selector *(COMMA selector)
      selector    = attributeSelector ; From Section 4.5.1 of
                                      ; [RFC4511], subject to the
                                      ; provisions of the
                                      ; "Percent-Encoding" section
                                      ; below.

      scope       = "base" / "one" / "sub"
      extensions  = extension *(COMMA extension)
      extension   = [EXCLAMATION] extype [EQUALS exvalue]
      extype      = oid               ; From section 1.4 of [RFC4512].

      exvalue     = LDAPString        ; From section 4.1.2 of
                                      ; [RFC4511], subject to the
                                      ; provisions of the
                                      ; "Percent-Encoding" section
                                      ; below.

      EXCLAMATION = %x21              ; exclamation mark ("!")
      SLASH       = %x2F              ; forward slash ("/")
      COLON       = %x3A              ; colon (":")
      QUESTION    = %x3F              ; question mark ("?")

   The "ldap" prefix indicates an entry or entries accessible from the
   LDAP server running on the given hostname at the given portnumber.
   Note that the <host> may contain literal IPv6 addresses as specified
   in Section 3.2.2 of [RFC3986].

   The <dn> is an LDAP Distinguished Name using the string format
   described in [RFC4514].  It identifies the base object of the LDAP
   search or the target of a non-search operation.

   The <attributes> construct is used to indicate which attributes
   should be returned from the entry or entries.

   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.






Smith & Howes               Standards Track                     [Page 3]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


   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 [RFC4515].

   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 LDAP extension mechanisms.  Extensions may be supported or
   unsupported by the client resolving the URL.  An extension prefixed
   with a '!' character (ASCII 0x21) is critical.  An extension not
   prefixed with a '!' character is non-critical.

   If an LDAP URL extension is implemented (that is, if the
   implementation understands it and is able to use it), the
   implementation MUST make use of it.  If an extension is not
   implemented and is marked critical, the implementation MUST NOT
   process the URL.  If an extension is not implemented and is not
   marked critical, the implementation MUST ignore the extension.

   The extension type (<extype>) MAY be specified using the numeric OID
   <numericoid> form (e.g., 1.2.3.4) or the descriptor <descr> form
   (e.g., myLDAPURLExtension).  Use of the <descr> form SHOULD be
   restricted to registered object identifier descriptive names.  See
   [RFC4520] for registration details and usage guidelines for
   descriptive names.

   No LDAP URL extensions are defined in this document.  Other documents
   or a future version of this document MAY define one or more
   extensions.

2.1.  Percent-Encoding

   A generated LDAP URL MUST consist only of the restricted set of
   characters included in one of the following three productions defined
   in [RFC3986]:

         <reserved>
         <unreserved>
         <pct-encoded>

   Implementations SHOULD accept other valid UTF-8 strings [RFC3629] as
   input.  An octet MUST be encoded using the percent-encoding mechanism
   described in section 2.1 of [RFC3986] in any of these situations:





Smith & Howes               Standards Track                     [Page 4]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


      The octet is not in the reserved set defined in section 2.2 of
      [RFC3986] or in the unreserved set defined in section 2.3 of
      [RFC3986].

      It is the single Reserved character '?' and occurs inside a <dn>,
      <filter>, or other element of an LDAP URL.

      It is a comma character ',' that occurs inside an <exvalue>.

   Note that before the percent-encoding mechanism is applied, the
   extensions component of the LDAP URL may contain one or more null
   (zero) bytes.  No other component may.

3.  Defaults for Fields of the LDAP URL

   Some fields of the LDAP URL are optional, as described above.  In the
   absence of any other specification, the following general defaults
   SHOULD be used when a field is absent.  Note that other documents MAY
   specify different defaulting rules; for example, section 4.1.10 of
   [RFC4511] specifies a different rule for determining the correct DN
   to use when it is absent in an LDAP URL that is returned as a
   referral.

   <host>
      If no <host> is given, the client must have some a priori
      knowledge of an appropriate LDAP server to contact.

   <port>
      The default LDAP port is TCP port 389.

   <dn>
      If no <dn> is given, the default is the zero-length DN, "".

   <attributes>
      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 by using the special <alluserattrs>
      selector "*").

   <scope>
      If <scope> is omitted, a <scope> of "base" is assumed.

   <filter>
      If <filter> is omitted, a filter of "(objectClass=*)" is assumed.

   <extensions>
      If <extensions> is omitted, no extensions are assumed.



Smith & Howes               Standards Track                     [Page 5]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


4.  Examples

   The following are some example LDAP URLs that use 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://ldap1.example.net/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
   "(objectclass=*)", requesting all attributes.

   The next example is an LDAP URL referring to only the postalAddress
   attribute of the University of Michigan entry:

      ldap://ldap1.example.net/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://ldap1.example.net:6666/o=University%20of%20Michigan,
             c=US??sub?(cn=Babs%20Jensen)

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

      LDAP://ldap1.example.com/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", illustrating the use of the
   percent-encoding mechanism on the reserved character '?'.




Smith & Howes               Standards Track                     [Page 6]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


      ldap://ldap2.example.com/o=Question%3f,c=US?mail

   The next example (which is broken into two lines for readability)
   illustrates the interaction between the LDAP string representation of
   the filters-quoting mechanism and the URL-quoting mechanisms.

      ldap://ldap3.example.com/o=Babsco,c=US
              ???(four-octet=%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 (four-octet=\00\00\00\04).  Because the \
   character must be escaped in a URL, the \s are percent-encoded as %5c
   (or %5C) in the URL encoding.

   The next example illustrates the interaction between the LDAP string
   representation of the DNs-quoting mechanism and URL-quoting
   mechanisms.

      ldap://ldap.example.com/o=An%20Example%5C2C%20Inc.,c=US

   The DN encoded in the above URL is:

      o=An Example\2C Inc.,c=US

   That is, the left-most RDN value is:

      An Example, Inc.

   The following three URLs are equivalent, assuming that the defaulting
   rules specified in Section 3 of this document are used:

      ldap://ldap.example.net
      ldap://ldap.example.net/
      ldap://ldap.example.net/?

   These three URLs point to the root DSE on the ldap.example.net
   server.

   The final two examples show use of a hypothetical, experimental bind
   name extension (the value associated with the extension is an LDAP
   DN).

      ldap:///??sub??e-bindname=cn=Manager%2cdc=example%2cdc=com
      ldap:///??sub??!e-bindname=cn=Manager%2cdc=example%2cdc=com






Smith & Howes               Standards Track                     [Page 7]

RFC 4516             LDAP: Uniform Resource Locator            June 2006


   The two URLs are the same, except that the second one marks the
   e-bindname extension as critical.  Notice the use of the percent-
   encoding mechanism to encode the commas within the distinguished name
   value in the e-bindname extension.

5.  Security Considerations

   The general URL security considerations discussed in [RFC3986] 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 that controls which servers the client will establish LDAP
   sessions with and with which security mechanisms, and SHOULD NOT
   establish LDAP sessions that are inconsistent with this policy.  If a
   client chooses to reuse an existing LDAP session when resolving one
   or more LDAP URLs, it MUST ensure that the session is compatible with
   the URL and that no security policies are violated.

   Sending authentication information, no matter the mechanism, may
   violate a user's privacy requirements.  In the absence of specific
   policy permitting authentication information to be sent to a server,