home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ldapsdk.zip / doc / rfc / rfc2255.txt < prev    next >
Text File  |  1998-10-28  |  21KB  |  564 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                         T. Howes
  8. Request for Comments: 2255                                    M. Smith
  9. Category: Standards Track                Netscape Communications Corp.
  10.                                                          December 1997
  11.  
  12.  
  13.                           The LDAP URL Format
  14.  
  15. 1. Status of this Memo
  16.  
  17.    This document specifies an Internet standards track protocol for the
  18.    Internet community, and requests discussion and suggestions for
  19.    improvements.  Please refer to the current edition of the "Internet
  20.    Official Protocol Standards" (STD 1) for the standardization state
  21.    and status of this protocol.  Distribution of this memo is unlimited.
  22.  
  23. Copyright Notice
  24.  
  25.    Copyright (C) The Internet Society (1997).  All Rights Reserved.
  26.  
  27. IESG NOTE
  28.  
  29.    This document describes a directory access protocol that provides
  30.    both read and update access.  Update access requires secure
  31.    authentication, but this document does not mandate implementation of
  32.    any satisfactory authentication mechanisms.
  33.  
  34.    In accordance with RFC 2026, section 4.4.1, this specification is
  35.    being approved by IESG as a Proposed Standard despite this
  36.    limitation, for the following reasons:
  37.  
  38.    a. to encourage implementation and interoperability testing of
  39.       these protocols (with or without update access) before they
  40.       are deployed, and
  41.  
  42.    b. to encourage deployment and use of these protocols in read-only
  43.       applications.  (e.g. applications where LDAPv3 is used as
  44.       a query language for directories which are updated by some
  45.       secure mechanism other than LDAP), and
  46.  
  47.    c. to avoid delaying the advancement and deployment of other Internet
  48.       standards-track protocols which require the ability to query, but
  49.       not update, LDAPv3 directory servers.
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Howes & Smith               Standards Track                     [Page 1]
  59.  
  60. RFC 2255                    LDAP URL Format                December 1997
  61.  
  62.  
  63.    Readers are hereby warned that until mandatory authentication
  64.    mechanisms are standardized, clients and servers written according to
  65.    this specification which make use of update functionality are
  66.    UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
  67.    IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
  68.  
  69.    Implementors are hereby discouraged from deploying LDAPv3 clients or
  70.    servers which implement the update functionality, until a Proposed
  71.    Standard for mandatory authentication in LDAPv3 has been approved and
  72.    published as an RFC.
  73.  
  74. 2. Abstract
  75.  
  76.    LDAP is the Lightweight Directory Access Protocol, defined in [1],
  77.    [2] and [3].  This document describes a format for an LDAP Uniform
  78.    Resource Locator.  The format describes an LDAP search operation to
  79.    perform to retrieve information from an LDAP directory. This document
  80.    replaces RFC 1959. It updates the LDAP URL format for version 3 of
  81.    LDAP and clarifies how LDAP URLs are resolved. This document also
  82.    defines an extension mechanism for LDAP URLs, so that future
  83.    documents can extend their functionality, for example, to provide
  84.    access to new LDAPv3 extensions as they are defined.
  85.  
  86.    The key words "MUST", "MAY", and "SHOULD" used in this document are
  87.    to be interpreted as described in [6].
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Howes & Smith               Standards Track                     [Page 2]
  115.  
  116. RFC 2255                    LDAP URL Format                December 1997
  117.  
  118.  
  119. 3. URL Definition
  120.  
  121.    An LDAP URL begins with the protocol prefix "ldap" and is defined by
  122.    the following grammar.
  123.  
  124.        ldapurl    = scheme "://" [hostport] ["/"
  125.                     [dn ["?" [attributes] ["?" [scope]
  126.                     ["?" [filter] ["?" extensions]]]]]]
  127.        scheme     = "ldap"
  128.        attributes = attrdesc *("," attrdesc)
  129.        scope      = "base" / "one" / "sub"
  130.        dn         = distinguishedName from Section 3 of [1]
  131.        hostport   = hostport from Section 5 of RFC 1738 [5]
  132.        attrdesc   = AttributeDescription from Section 4.1.5 of [2]
  133.        filter     = filter from Section 4 of [4]
  134.        extensions = extension *("," extension)
  135.        extension  = ["!"] extype ["=" exvalue]
  136.        extype     = token / xtoken
  137.        exvalue    = LDAPString from section 4.1.2 of [2]
  138.        token      = oid from section 4.1 of [3]
  139.        xtoken     = ("X-" / "x-") token
  140.  
  141.    The "ldap" prefix indicates an entry or entries residing in the LDAP
  142.    server running on the given hostname at the given portnumber. The
  143.    default LDAP port is TCP port 389. If no hostport is given, the
  144.    client must have some apriori knowledge of an appropriate LDAP server
  145.    to contact.
  146.  
  147.    The dn is an LDAP Distinguished Name using the string format
  148.    described in [1]. It identifies the base object of the LDAP search.
  149.  
  150.    ldapurl    = scheme "://" [hostport] ["/"
  151.                     [dn ["?" [attributes] ["?" [scope]
  152.                     ["?" [filter] ["?" extensions]]]]]]
  153.        scheme     = "ldap"
  154.        attributes = attrdesc *("," attrdesc)
  155.        scope      = "base" / "one" / "sub"
  156.        dn         = distinguishedName from Section 3 of [1]
  157.        hostport   = hostport from Section 5 of RFC 1738 [5]
  158.        attrdesc   = AttributeDescription from Section 4.1.5 of [2]
  159.        filter     = filter from Section 4 of [4]
  160.        extensions = extension *("," extension)
  161.        extension  = ["!"] extype ["=" exvalue]
  162.        extype     = token / xtoken
  163.        exvalue    = LDAPString from section 4.1.2 of [2]
  164.        token      = oid from section 4.1 of [3]
  165.        xtoken     = ("X-" / "x-") token
  166.  
  167.  
  168.  
  169.  
  170. Howes & Smith               Standards Track                     [Page 3]
  171.  
  172. RFC 2255                    LDAP URL Format                December 1997
  173.  
  174.  
  175.    The "ldap" prefix indicates an entry or entries residing in the LDAP
  176.    server running on the given hostname at the given portnumber. The
  177.    default LDAP port is TCP port 389. If no hostport is given, the
  178.    client must have some apriori knowledge of an appropriate LDAP server
  179.    to contact.
  180.  
  181.    The dn is an LDAP Distinguished Name using the string format
  182.    described in [1]. It identifies the base object of the LDAP search.
  183.  
  184.    The attributes construct is used to indicate which attributes should
  185.    be returned from the entry or entries.  Individual attrdesc names are
  186.    as defined for AttributeDescription in [2].  If the attributes part
  187.    is omitted, all user attributes of the entry or entries should be
  188.    requested (e.g., by setting the attributes field
  189.    AttributeDescriptionList in the LDAP search request to a NULL list,
  190.    or (in LDAPv3) by requesting the special attribute name "*").
  191.  
  192.    The scope construct is used to specify the scope of the search to
  193.    perform in the given LDAP server.  The allowable scopes are "base"
  194.    for a base object search, "one" for a one-level search, or "sub" for
  195.    a subtree search.  If scope is omitted, a scope of "base" is assumed.
  196.  
  197.    The filter is used to specify the search filter to apply to entries
  198.    within the specified scope during the search.  It has the format
  199.    specified in [4].  If filter is omitted, a filter of
  200.    "(objectClass=*)" is assumed.
  201.  
  202.    The extensions construct provides the LDAP URL with an extensibility
  203.    mechanism, allowing the capabilities of the URL to be extended in the
  204.    future. Extensions are a simple comma-separated list of type=value
  205.    pairs, where the =value portion MAY be omitted for options not
  206.    requiring it. Each type=value pair is a separate extension. These
  207.    LDAP URL extensions are not necessarily related to any of the LDAPv3
  208.    extension mechanisms. Extensions may be supported or unsupported by
  209.    the client resolving the URL. An extension prefixed with a '!'
  210.    character (ASCII 33) is critical. An extension not prefixed with a '
  211.    !'  character is non-critical.
  212.  
  213.    If an extension is supported by the client, the client MUST obey the
  214.    extension if the extension is critical. The client SHOULD obey
  215.    supported extensions that are non-critical.
  216.  
  217.    If an extension is unsupported by the client, the client MUST NOT
  218.    process the URL if the extension is critical.  If an unsupported
  219.    extension is non-critical, the client MUST ignore the extension.
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Howes & Smith               Standards Track                     [Page 4]
  227.  
  228. RFC 2255                    LDAP URL Format                December 1997
  229.  
  230.  
  231.    If a critical extension cannot be processed successfully by the
  232.    client, the client MUST NOT process the URL. If a non-critical
  233.    extension cannot be processed successfully by the client, the client
  234.    SHOULD ignore the extension.
  235.  
  236.    Extension types prefixed by "X-" or "x-" are reserved for use in
  237.    bilateral agreements between communicating parties. Other extension
  238.    types MUST be defined in this document, or in other standards-track
  239.    documents.
  240.  
  241.    One LDAP URL extension is defined in this document in the next
  242.    section.  Other documents or a future version of this document MAY
  243.    define other extensions.
  244.  
  245.    Note that any URL-illegal characters (e.g., spaces), URL special
  246.    characters (as defined in section 2.2 of RFC 1738) and the reserved
  247.    character '?' (ASCII 63) occurring inside a dn, filter, or other
  248.    element of an LDAP URL MUST be escaped using the % method described
  249.    in RFC 1738 [5]. If a comma character ',' occurs inside an extension
  250.    value, the character MUST also be escaped using the % method.
  251.  
  252. 4. The Bindname Extension
  253.  
  254.    This section defines an LDAP URL extension for representing the
  255.    distinguished name for a client to use when authenticating to an LDAP
  256.    directory during resolution of an LDAP URL. Clients MAY implement
  257.    this extension.
  258.  
  259.    The extension type is "bindname". The extension value is the
  260.    distinguished name of the directory entry to authenticate as, in the
  261.    same form as described for dn in the grammar above. The dn may be the
  262.    NULL string to specify unauthenticated access. The extension may be
  263.    either critical (prefixed with a '!' character) or non-critical (not
  264.    prefixed with a '!' character).
  265.  
  266.    If the bindname extension is critical, the client resolving the URL
  267.    MUST authenticate to the directory using the given distinguished name
  268.    and an appropriate authentication method. Note that for a NULL
  269.    distinguished name, no bind MAY be required to obtain anonymous
  270.    access to the directory. If the extension is non-critical, the client
  271.    MAY bind to the directory using the given distinguished name.
  272.  
  273. 5. URL Processing
  274.  
  275.    This section describes how an LDAP URL SHOULD be resolved by a
  276.    client.
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Howes & Smith               Standards Track                     [Page 5]
  283.  
  284. RFC 2255                    LDAP URL Format                December 1997
  285.  
  286.  
  287.    First, the client obtains a connection to the LDAP server referenced
  288.    in the URL, or an LDAP server of the client's choice if no LDAP
  289.    server is explicitly referenced.  This connection MAY be opened
  290.    specifically for the purpose of resolving the URL or the client MAY
  291.    reuse an already open connection. The connection MAY provide
  292.    confidentiality, integrity, or other services, e.g., using TLS. Use
  293.    of security services is at the client's discretion if not specified
  294.    in the URL.
  295.  
  296.    Next, the client authenticates itself to the LDAP server.  This step
  297.    is optional, unless the URL contains a critical bindname extension
  298.    with a non-NULL value. If a bindname extension is given, the client
  299.    proceeds according to the section above.
  300.  
  301.    If a bindname extension is not specified, the client MAY bind to the
  302.    directory using a appropriate dn and authentication method of its own
  303.    choosing (including NULL authentication).
  304.  
  305.    Next, the client performs the LDAP search operation specified in the
  306.    URL. Additional fields in the LDAP protocol search request, such as
  307.    sizelimit, timelimit, deref, and anything else not specified or
  308.    defaulted in the URL specification, MAY be set at the client's
  309.    discretion.
  310.  
  311.    Once the search has completed, the client MAY close the connection to
  312.    the LDAP server, or the client MAY keep the connection open for
  313.    future use.
  314.  
  315. 6. Examples
  316.  
  317.    The following are some example LDAP URLs using the format defined
  318.    above.  The first example is an LDAP URL referring to the University
  319.    of Michigan entry, available from an LDAP server of the client's
  320.    choosing:
  321.  
  322.      ldap:///o=University%20of%20Michigan,c=US
  323.  
  324.    The next example is an LDAP URL referring to the University of
  325.    Michigan entry in a particular ldap server:
  326.  
  327.      ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
  328.  
  329.    Both of these URLs correspond to a base object search of the
  330.    "o=University of Michigan, c=US" entry using a filter of
  331.    "(objectclass=*)", requesting all attributes.
  332.  
  333.    The next example is an LDAP URL referring to only the postalAddress
  334.    attribute of the University of Michigan entry:
  335.  
  336.  
  337.  
  338. Howes & Smith               Standards Track                     [Page 6]
  339.  
  340. RFC 2255                    LDAP URL Format                December 1997
  341.  
  342.  
  343.      ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,
  344.             c=US?postalAddress
  345.  
  346.    The corresponding LDAP search operation is the same as in the
  347.    previous example, except that only the postalAddress attribute is
  348.    requested.
  349.  
  350.    The next example is an LDAP URL referring to the set of entries found
  351.    by querying the given LDAP server on port 6666 and doing a subtree
  352.    search of the University of Michigan for any entry with a common name
  353.    of "Babs Jensen", retrieving all attributes:
  354.  
  355.      ldap://host.com:6666/o=University%20of%20Michigan,
  356.             c=US??sub?(cn=Babs%20Jensen)
  357.  
  358.    The next example is an LDAP URL referring to all children of the c=GB
  359.    entry:
  360.  
  361.      ldap://ldap.itd.umich.edu/c=GB?objectClass?one
  362.  
  363.    The objectClass attribute is requested to be returned along with the
  364.    entries, and the default filter of "(objectclass=*)" is used.
  365.  
  366.    The next example is an LDAP URL to retrieve the mail attribute for
  367.    the LDAP entry named "o=Question?,c=US" is given below, illustrating
  368.    the use of the escaping mechanism on the reserved character '?'.
  369.  
  370.      ldap://ldap.question.com/o=Question%3f,c=US?mail
  371.  
  372.    The next example illustrates the interaction between LDAP and URL
  373.    quoting mechanisms.
  374.  
  375.      ldap://ldap.netscape.com/o=Babsco,c=US??(int=%5c00%5c00%5c00%5c04)
  376.  
  377.    The filter in this example uses the LDAP escaping mechanism of \ to
  378.    encode three zero or null bytes in the value. In LDAP, the filter
  379.    would be written as (int=\00\00\00\04). Because the \ character must
  380.    be escaped in a URL, the \'s are escaped as %5c in the URL encoding.
  381.  
  382.    The final example shows the use of the bindname extension to specify
  383.    the dn a client should use for authentication when resolving the URL.
  384.  
  385.      ldap:///??sub??bindname=cn=Manager%2co=Foo
  386.      ldap:///??sub??!bindname=cn=Manager%2co=Foo
  387.  
  388.    The two URLs are the same, except that the second one marks the
  389.    bindname extension as critical. Notice the use of the % encoding
  390.    method to encode the comma in the distinguished name value in the
  391.  
  392.  
  393.  
  394. Howes & Smith               Standards Track                     [Page 7]
  395.  
  396. RFC 2255                    LDAP URL Format                December 1997
  397.  
  398.  
  399.    bindname extension.
  400.  
  401. 7. Security Considerations
  402.  
  403.    General URL security considerations discussed in [5] are relevant for
  404.    LDAP URLs.
  405.  
  406.    The use of security mechanisms when processing LDAP URLs requires
  407.    particular care, since clients may encounter many different servers
  408.    via URLs, and since URLs are likely to be processed automatically,
  409.    without user intervention. A client SHOULD have a user-configurable
  410.    policy about which servers to connect to using which security
  411.    mechanisms, and SHOULD NOT make connections that are inconsistent
  412.    with this policy.
  413.  
  414.    Sending authentication information, no matter the mechanism, may
  415.    violate a user's privacy requirements.  In the absence of specific
  416.    policy permitting authentication information to be sent to a server,
  417.    a client should use an anonymous connection.  (Note that clients
  418.    conforming to previous LDAP URL specifications, where all connections
  419.    are anonymous and unprotected, are consistent with this
  420.    specification; they simply have the default security policy.)
  421.  
  422.    Some authentication methods, in particular reusable passwords sent to
  423.    the server, may reveal easily-abused information to the remote server
  424.    or to eavesdroppers in transit, and should not be used in URL
  425.    processing unless explicitly permitted by policy.  Confirmation by
  426.    the human user of the use of authentication information is
  427.    appropriate in many circumstances.  Use of strong authentication
  428.    methods that do not reveal sensitive information is much preferred.
  429.  
  430.    The LDAP URL format allows the specification of an arbitrary LDAP
  431.    search operation to be performed when evaluating the LDAP URL.
  432.    Following an LDAP URL may cause unexpected results, for example, the
  433.    retrieval of large amounts of data, the initiation of a long-lived
  434.    search, etc.  The security implications of resolving an LDAP URL are
  435.    the same as those of resolving an LDAP search query.
  436.  
  437. 8. Acknowledgements
  438.  
  439.    The LDAP URL format was originally defined at the University of
  440.    Michigan. This material is based upon work supported by the National
  441.    Science Foundation under Grant No. NCR-9416667. The support of both
  442.    the University of Michigan and the National Science Foundation is
  443.    gratefully acknowledged.
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Howes & Smith               Standards Track                     [Page 8]
  451.  
  452. RFC 2255                    LDAP URL Format                December 1997
  453.  
  454.  
  455.    Several people have made valuable comments on this document.  In
  456.    particular RL "Bob" Morgan and Mark Wahl deserve special thanks for
  457.    their contributions.
  458.  
  459. 9. References
  460.  
  461.    [1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access
  462.    Protocol (v3): UTF-8 String Representation of Distinguished Names",
  463.    RFC 2253, December 1997.
  464.  
  465.    [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
  466.    Protocol (v3)", RFC 2251, December 1997.
  467.  
  468.    [3] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
  469.    Directory Access Protocol (v3): Attribute Syntax Definitions", RFC
  470.    2252, December 1997.
  471.  
  472.    [4] Howes, T., "A String Representation of LDAP Search Filters", RFC
  473.    2254, December 1997.
  474.  
  475.    [5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
  476.    Locators (URL)," RFC 1738, December 1994.
  477.  
  478.    [6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement
  479.    Levels," RFC 2119, March 1997.
  480.  
  481. Authors' Addresses
  482.  
  483.    Tim Howes
  484.    Netscape Communications Corp.
  485.    501 E. Middlefield Rd.
  486.    Mountain View, CA 94043
  487.    USA
  488.  
  489.    Phone: +1 415 937-3419
  490.    EMail: howes@netscape.com
  491.  
  492.  
  493.    Mark Smith
  494.    Netscape Communications Corp.
  495.    501 E. Middlefield Rd.
  496.    Mountain View, CA 94043
  497.    USA
  498.  
  499.    Phone: +1 415 937-3477
  500.    EMail: mcs@netscape.com
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Howes & Smith               Standards Track                     [Page 9]
  507.  
  508. RFC 2255                    LDAP URL Format                December 1997
  509.  
  510.  
  511. Full Copyright Statement
  512.  
  513.    Copyright (C) The Internet Society (1997).  All Rights Reserved.
  514.  
  515.    This document and translations of it may be copied and furnished to
  516.    others, and derivative works that comment on or otherwise explain it
  517.    or assist in its implementation may be prepared, copied, published
  518.    and distributed, in whole or in part, without restriction of any
  519.    kind, provided that the above copyright notice and this paragraph are
  520.    included on all such copies and derivative works.  However, this
  521.    document itself may not be modified in any way, such as by removing
  522.    the copyright notice or references to the Internet Society or other
  523.    Internet organizations, except as needed for the purpose of
  524.    developing Internet standards in which case the procedures for
  525.    copyrights defined in the Internet Standards process must be
  526.    followed, or as required to translate it into languages other than
  527.    English.
  528.  
  529.    The limited permissions granted above are perpetual and will not be
  530.    revoked by the Internet Society or its successors or assigns.
  531.  
  532.    This document and the information contained herein is provided on an
  533.    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  534.    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
  535.    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
  536.    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  537.    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Howes & Smith               Standards Track                    [Page 10]
  563.  
  564.