]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2255.txt
Sync with HEAD
[openldap] / doc / rfc / rfc2255.txt
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 \f
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 \f
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 \f
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 \f
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 \f
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 \f
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 \f
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 \f
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 \f
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 \f