]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2830.txt
Sync with HEAD
[openldap] / doc / rfc / rfc2830.txt
1
2
3
4
5
6
7 Network Working Group                                          J. Hodges
8 Request for Comments: 2830                                    Oblix Inc.
9 Category: Standards Track                                      R. Morgan
10                                                       Univ of Washington
11                                                                  M. Wahl
12                                                   Sun Microsystems, Inc.
13                                                                 May 2000
14
15
16               Lightweight Directory Access Protocol (v3):
17                  Extension for Transport Layer Security
18
19 Status of this Memo
20
21    This document specifies an Internet standards track protocol for the
22    Internet community, and requests discussion and suggestions for
23    improvements.  Please refer to the current edition of the "Internet
24    Official Protocol Standards" (STD 1) for the standardization state
25    and status of this protocol.  Distribution of this memo is unlimited.
26
27 Copyright Notice
28
29    Copyright (C) The Internet Society (2000).  All Rights Reserved.
30
31 Abstract
32
33    This document defines the "Start Transport Layer Security (TLS)
34    Operation" for LDAP [LDAPv3, TLS]. This operation provides for TLS
35    establishment in an LDAP association and is defined in terms of an
36    LDAP extended request.
37
38 1.  Conventions Used in this Document
39
40    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
41    "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
42    document are to be interpreted as described in [ReqsKeywords].
43
44 2.  The Start TLS Request
45
46    This section describes the Start TLS extended request and extended
47    response themselves: how to form the request, the form of the
48    response, and enumerates the various result codes the client MUST be
49    prepared to handle.
50
51    The section following this one then describes how to sequence an
52    overall Start TLS Operation.
53
54
55
56
57
58 Hodges, et al.              Standards Track                     [Page 1]
59 \f
60 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
61
62
63 2.1.  Requesting TLS Establishment
64
65    A client may perform a Start TLS operation by transmitting an LDAP
66    PDU containing an ExtendedRequest [LDAPv3] specifying the OID for the
67    Start TLS operation:
68
69      1.3.6.1.4.1.1466.20037
70
71    An LDAP ExtendedRequest is defined as follows:
72
73      ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
74              requestName             [0] LDAPOID,
75              requestValue            [1] OCTET STRING OPTIONAL }
76
77    A Start TLS extended request is formed by setting the requestName
78    field to the OID string given above.  The requestValue field is
79    absent.  The client MUST NOT send any PDUs on this connection
80    following this request until it receives a Start TLS extended
81    response.
82
83    When a Start TLS extended request is made, the server MUST return an
84    LDAP PDU containing a Start TLS extended response.  An LDAP
85    ExtendedResponse is defined as follows:
86
87      ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
88              COMPONENTS OF LDAPResult,
89              responseName     [10] LDAPOID OPTIONAL,
90              response         [11] OCTET STRING OPTIONAL }
91
92    A Start TLS extended response MUST contain a responseName field which
93    MUST be set to the same string as that in the responseName field
94    present in the Start TLS extended request. The response field is
95    absent. The server MUST set the resultCode field to either success or
96    one of the other values outlined in section 2.3.
97
98 2.2.  "Success" Response
99
100    If the ExtendedResponse contains a resultCode of success, this
101    indicates that the server is willing and able to negotiate TLS. Refer
102    to section 3, below, for details.
103
104 2.3.  Response other than "success"
105
106    If the ExtendedResponse contains a resultCode other than success,
107    this indicates that the server is unwilling or unable to negotiate
108    TLS.
109
110
111
112
113
114 Hodges, et al.              Standards Track                     [Page 2]
115 \f
116 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
117
118
119    If the Start TLS extended request was not successful, the resultCode
120    will be one of:
121
122    operationsError  (operations sequencing incorrect; e.g. TLS already
123                     established)
124
125    protocolError    (TLS not supported or incorrect PDU structure)
126
127    referral         (this server doesn't do TLS, try this one)
128
129    unavailable      (e.g. some major problem with TLS, or server is
130                     shutting down)
131
132    The server MUST return operationsError if the client violates any of
133    the Start TLS extended operation sequencing requirements described in
134    section 3, below.
135
136    If the server does not support TLS (whether by design or by current
137    configuration), it MUST set the resultCode to protocolError (see
138    section 4.1.1 of [LDAPv3]), or to referral. The server MUST include
139    an actual referral value in the LDAP Result if it returns a
140    resultCode of referral. The client's current session is unaffected if
141    the server does not support TLS. The client MAY proceed with any LDAP
142    operation, or it MAY close the connection.
143
144    The server MUST return unavailable if it supports TLS but cannot
145    establish a TLS connection for some reason, e.g. the certificate
146    server not responding, it cannot contact its TLS implementation, or
147    if the server is in process of shutting down. The client MAY retry
148    the StartTLS operation, or it MAY proceed with any other LDAP
149    operation, or it MAY close the connection.
150
151 3.  Sequencing of the Start TLS Operation
152
153    This section describes the overall procedures clients and servers
154    MUST follow for TLS establishment. These procedures take into
155    consideration various aspects of the overall security of the LDAP
156    association including discovery of resultant security level and
157    assertion of the client's authorization identity.
158
159    Note that the precise effects, on a client's authorization identity,
160    of establishing TLS on an LDAP association are described in detail in
161    section 5.
162
163
164
165
166
167
168
169
170 Hodges, et al.              Standards Track                     [Page 3]
171 \f
172 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
173
174
175 3.1.  Requesting to Start TLS on an LDAP Association
176
177    The client MAY send the Start TLS extended request at any time after
178    establishing an LDAP association, except that in the following cases
179    the client MUST NOT send a Start TLS extended request:
180
181      - if TLS is currently established on the connection, or
182      - during a multi-stage SASL negotiation, or
183      - if there are any LDAP operations outstanding on the connection.
184
185    The result of violating any of these requirements is a resultCode of
186    operationsError, as described above in section 2.3.
187
188    The client MAY have already performed a Bind operation when it sends
189    a Start TLS request, or the client might have not yet bound.
190
191    If the client did not establish a TLS connection before sending any
192    other requests, and the server requires the client to establish a TLS
193    connection before performing a particular request, the server MUST
194    reject that request with a confidentialityRequired or
195    strongAuthRequired result. The client MAY send a Start TLS extended
196    request, or it MAY choose to close the connection.
197
198 3.2.  Starting TLS
199
200    The server will return an extended response with the resultCode of
201    success if it is willing and able to negotiate TLS.  It will return
202    other resultCodes, documented above, if it is unable.
203
204    In the successful case, the client, which has ceased to transfer LDAP
205    requests on the connection, MUST either begin a TLS negotiation or
206    close the connection. The client will send PDUs in the TLS Record
207    Protocol directly over the underlying transport connection to the
208    server to initiate TLS negotiation [TLS].
209
210 3.3.  TLS Version Negotiation
211
212    Negotiating the version of TLS or SSL to be used is a part of the TLS
213    Handshake Protocol, as documented in [TLS]. Please refer to that
214    document for details.
215
216 3.4.  Discovery of Resultant Security Level
217
218    After a TLS connection is established on an LDAP association, both
219    parties MUST individually decide whether or not to continue based on
220    the privacy level achieved. Ascertaining the TLS connection's privacy
221    level is implementation dependent, and accomplished by communicating
222    with one's respective local TLS implementation.
223
224
225
226 Hodges, et al.              Standards Track                     [Page 4]
227 \f
228 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
229
230
231    If the client or server decides that the level of authentication or
232    privacy is not high enough for it to continue, it SHOULD gracefully
233    close the TLS connection immediately after the TLS negotiation has
234    completed (see sections 4.1 and 5.2, below).
235
236    The client MAY attempt to Start TLS again, or MAY send an unbind
237    request, or send any other LDAP request.
238
239 3.5.  Assertion of Client's Authorization Identity
240
241    The client MAY, upon receipt of a Start TLS extended response
242    indicating success, assert that a specific authorization identity be
243    utilized in determining the client's authorization status. The client
244    accomplishes this via an LDAP Bind request specifying a SASL
245    mechanism of "EXTERNAL" [SASL]. See section 5.1.2, below.
246
247 3.6.  Server Identity Check
248
249    The client MUST check its understanding of the server's hostname
250    against the server's identity as presented in the server's
251    Certificate message, in order to prevent man-in-the-middle attacks.
252
253    Matching is performed according to these rules:
254
255    - The client MUST use the server hostname it used to open the LDAP
256      connection as the value to compare against the server name as
257      expressed in the server's certificate.  The client MUST NOT use the
258      server's canonical DNS name or any other derived form of name.
259
260    - If a subjectAltName extension of type dNSName is present in the
261      certificate, it SHOULD be used as the source of the server's
262      identity.
263
264    - Matching is case-insensitive.
265
266    - The "*" wildcard character is allowed.  If present, it applies only
267      to the left-most name component.
268
269    E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not
270    bar.com.  If more than one identity of a given type is present in the
271    certificate (e.g. more than one dNSName name), a match in any one of
272    the set is considered acceptable.
273
274    If the hostname does not match the dNSName-based identity in the
275    certificate per the above check, user-oriented clients SHOULD either
276    notify the user (clients MAY give the user the opportunity to
277
278
279
280
281
282 Hodges, et al.              Standards Track                     [Page 5]
283 \f
284 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
285
286
287    continue with the connection in any case) or terminate the connection
288    and indicate that the server's identity is suspect. Automated clients
289    SHOULD close the connection, returning and/or logging an error
290    indicating that the server's identity is suspect.
291
292    Beyond the server identity checks described in this section, clients
293    SHOULD be prepared to do further checking to ensure that the server
294    is authorized to provide the service it is observed to provide. The
295    client MAY need to make use of local policy information.
296
297 3.7.  Refresh of Server Capabilities Information
298
299    The client MUST refresh any cached server capabilities information
300    (e.g. from the server's root DSE; see section 3.4 of [LDAPv3]) upon
301    TLS session establishment. This is necessary to protect against
302    active-intermediary attacks which may have altered any server
303    capabilities information retrieved prior to TLS establishment. The
304    server MAY advertise different capabilities after TLS establishment.
305
306 4.  Closing a TLS Connection
307
308 4.1.  Graceful Closure
309
310    Either the client or server MAY terminate the TLS connection on an
311    LDAP association by sending a TLS closure alert. This will leave the
312    LDAP association intact.
313
314    Before closing a TLS connection, the client MUST either wait for any
315    outstanding LDAP operations to complete, or explicitly abandon them
316    [LDAPv3].
317
318    After the initiator of a close has sent a closure alert, it MUST
319    discard any TLS messages until it has received an alert from the
320    other party.  It will cease to send TLS Record Protocol PDUs, and
321    following the receipt of the alert, MAY send and receive LDAP PDUs.
322
323    The other party, if it receives a closure alert, MUST immediately
324    transmit a TLS closure alert.  It will subsequently cease to send TLS
325    Record Protocol PDUs, and MAY send and receive LDAP PDUs.
326
327 4.2.  Abrupt Closure
328
329    Either the client or server MAY abruptly close the entire LDAP
330    association and any TLS connection established on it by dropping the
331    underlying TCP connection. A server MAY beforehand send the client a
332    Notice of Disconnection [LDAPv3] in this case.
333
334
335
336
337
338 Hodges, et al.              Standards Track                     [Page 6]
339 \f
340 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
341
342
343 5.  Effects of TLS on a Client's Authorization Identity
344
345    This section describes the effects on a client's authorization
346    identity brought about by establishing TLS on an LDAP association.
347    The default effects are described first, and next the facilities for
348    client assertion of authorization identity are discussed including
349    error conditions. Lastly, the effects of closing the TLS connection
350    are described.
351
352    Authorization identities and related concepts are defined in
353    [AuthMeth].
354
355 5.1.  TLS Connection Establishment Effects
356
357 5.1.1.  Default Effects
358
359    Upon establishment of the TLS connection onto the LDAP association,
360    any previously established authentication and authorization
361    identities MUST remain in force, including anonymous state. This
362    holds even in the case where the server requests client
363    authentication via TLS -- e.g. requests the client to supply its
364    certificate during TLS negotiation (see [TLS]).
365
366 5.1.2.  Client Assertion of Authorization Identity
367
368    A client MAY either implicitly request that its LDAP authorization
369    identity be derived from its authenticated TLS credentials or it MAY
370    explicitly provide an authorization identity and assert that it be
371    used in combination with its authenticated TLS credentials. The
372    former is known as an implicit assertion, and the latter as an
373    explicit assertion.
374
375 5.1.2.1.  Implicit Assertion
376
377    An implicit authorization identity assertion is accomplished after
378    TLS establishment by invoking a Bind request of the SASL form using
379    the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL NOT include
380    the optional credentials octet string (found within the
381    SaslCredentials sequence in the Bind Request). The server will derive
382    the client's authorization identity from the authentication identity
383    supplied in the client's TLS credentials (typically a public key
384    certificate) according to local policy. The underlying mechanics of
385    how this is accomplished are implementation specific.
386
387
388
389
390
391
392
393
394 Hodges, et al.              Standards Track                     [Page 7]
395 \f
396 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
397
398
399 5.1.2.2.  Explicit Assertion
400
401    An explicit authorization identity assertion is accomplished after
402    TLS establishment by invoking a Bind request of the SASL form using
403    the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL include the
404    credentials octet string. This string MUST be constructed as
405    documented in section 9 of [AuthMeth].
406
407 5.1.2.3.  Error Conditions
408
409    For either form of assertion, the server MUST verify that the
410    client's authentication identity as supplied in its TLS credentials
411    is permitted to be mapped to the asserted authorization identity. The
412    server MUST reject the Bind operation with an invalidCredentials
413    resultCode in the Bind response if the client is not so authorized.
414
415    Additionally, with either form of assertion, if a TLS session has not
416    been established between the client and server prior to making the
417    SASL EXTERNAL Bind request and there is no other external source of
418    authentication credentials (e.g.  IP-level security [IPSEC]), or if,
419    during the process of establishing the TLS session, the server did
420    not request the client's authentication credentials, the SASL
421    EXTERNAL bind MUST fail with a result code of
422    inappropriateAuthentication.
423
424    After the above Bind operation failures, any client authentication
425    and authorization state of the LDAP association is lost, so the LDAP
426    association is in an anonymous state after the failure.  TLS
427    connection state is unaffected, though a server MAY end the TLS
428    connection, via a TLS close_notify message, based on the Bind failure
429    (as it MAY at any time).
430
431 5.2.  TLS Connection Closure Effects
432
433    Closure of the TLS connection MUST cause the LDAP association to move
434    to an anonymous authentication and authorization state regardless of
435    the state established over TLS and regardless of the authentication
436    and authorization state prior to TLS connection establishment.
437
438 6.  Security Considerations
439
440    The goals of using the TLS protocol with LDAP are to ensure
441    connection confidentiality and integrity, and to optionally provide
442    for authentication. TLS expressly provides these capabilities, as
443    described in [TLS].
444
445
446
447
448
449
450 Hodges, et al.              Standards Track                     [Page 8]
451 \f
452 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
453
454
455    All security gained via use of the Start TLS operation is gained by
456    the use of TLS itself. The Start TLS operation, on its own, does not
457    provide any additional security.
458
459    The use of TLS does not provide or ensure for confidentiality and/or
460    non-repudiation of the data housed by an LDAP-based directory server.
461    Nor does it secure the data from inspection by the server
462    administrators.  Once established, TLS only provides for and ensures
463    confidentiality and integrity of the operations and data in transit
464    over the LDAP association, and only if the implementations on the
465    client and server support and negotiate it.
466
467    The level of security provided though the use of TLS depends directly
468    on both the quality of the TLS implementation used and the style of
469    usage of that implementation. Additionally, an active-intermediary
470    attacker can remove the Start TLS extended operation from the
471    supportedExtension attribute of the root DSE. Therefore, both parties
472    SHOULD independently ascertain and consent to the security level
473    achieved once TLS is established and before beginning use of the TLS
474    connection. For example, the security level of the TLS connection
475    might have been negotiated down to plaintext.
476
477    Clients SHOULD either warn the user when the security level achieved
478    does not provide confidentiality and/or integrity protection, or be
479    configurable to refuse to proceed without an acceptable level of
480    security.
481
482    Client and server implementors SHOULD take measures to ensure proper
483    protection of credentials and other confidential data where such
484    measures are not otherwise provided by the TLS implementation.
485
486    Server implementors SHOULD allow for server administrators to elect
487    whether and when connection confidentiality and/or integrity is
488    required, as well as elect whether and when client authentication via
489    TLS is required.
490
491 7.  Acknowledgements
492
493    The authors thank Tim Howes, Paul Hoffman, John Kristian, Shirish
494    Rai, Jonathan Trostle, Harald Alvestrand, and Marcus Leech for their
495    contributions to this document.
496
497
498
499
500
501
502
503
504
505
506 Hodges, et al.              Standards Track                     [Page 9]
507 \f
508 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
509
510
511 8.  References
512
513    [AuthMeth]     Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
514                   "Authentication Methods for LDAP", RFC 2829, May 2000.
515
516    [IPSEC]        Kent, S. and R. Atkinson, "Security Architecture for
517                   the Internet Protocol", RFC 2401, November 1998.
518
519    [LDAPv3]       Wahl, M., Kille S. and T. Howes, "Lightweight
520                   Directory Access Protocol (v3)", RFC 2251, December
521                   1997.
522
523    [ReqsKeywords] Bradner, S., "Key Words for use in RFCs to Indicate
524                   Requirement Levels", BCP 14, RFC 2119, March 1997.
525
526    [SASL]         Myers, J., "Simple Authentication and Security Layer
527                   (SASL)", RFC 2222, October 1997.
528
529    [TLS]          Dierks, T. and C. Allen. "The TLS Protocol Version
530                   1.0", RFC 2246, January 1999.
531
532 9.  Authors' Addresses
533
534    Jeff Hodges
535    Oblix, Inc.
536    18922 Forge Drive
537    Cupertino, CA 95014
538    USA
539
540    Phone: +1-408-861-6656
541    EMail: JHodges@oblix.com
542
543    RL "Bob" Morgan
544    Computing and Communications
545    University of Washington
546    Seattle, WA
547    USA
548
549    Phone: +1-206-221-3307
550    EMail: rlmorgan@washington.edu
551
552    Mark Wahl
553    Sun Microsystems, Inc.
554    8911 Capital of Texas Hwy #4140
555    Austin TX 78759
556    USA
557
558    EMail: M.Wahl@innosoft.com
559
560
561
562 Hodges, et al.              Standards Track                    [Page 10]
563 \f
564 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
565
566
567 10.  Intellectual Property Rights Notices
568
569    The IETF takes no position regarding the validity or scope of any
570    intellectual property or other rights that might be claimed to
571    pertain to the implementation or use of the technology described in
572    this document or the extent to which any license under such rights
573    might or might not be available; neither does it represent that it
574    has made any effort to identify any such rights.  Information on the
575    IETF's procedures with respect to rights in standards-track and
576    standards-related documentation can be found in BCP-11.  Copies of
577    claims of rights made available for publication and any assurances of
578    licenses to be made available, or the result of an attempt made to
579    obtain a general license or permission for the use of such
580    proprietary rights by implementors or users of this specification can
581    be obtained from the IETF Secretariat.
582
583    The IETF invites any interested party to bring to its attention any
584    copyrights, patents or patent applications, or other proprietary
585    rights which may cover technology that may be required to practice
586    this standard.  Please address the information to the IETF Executive
587    Director.
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618 Hodges, et al.              Standards Track                    [Page 11]
619 \f
620 RFC 2830     LDAPv3: Extension for Transport Layer Security     May 2000
621
622
623 11.  Full Copyright Statement
624
625    Copyright (C) The Internet Society (2000).  All Rights Reserved.
626
627    This document and translations of it may be copied and furnished to
628    others, and derivative works that comment on or otherwise explain it
629    or assist in its implementation may be prepared, copied, published
630    and distributed, in whole or in part, without restriction of any
631    kind, provided that the above copyright notice and this paragraph are
632    included on all such copies and derivative works.  However, this
633    document itself may not be modified in any way, such as by removing
634    the copyright notice or references to the Internet Society or other
635    Internet organizations, except as needed for the purpose of
636    developing Internet standards in which case the procedures for
637    copyrights defined in the Internet Standards process must be
638    followed, or as required to translate it into languages other than
639    English.
640
641    The limited permissions granted above are perpetual and will not be
642    revoked by the Internet Society or its successors or assigns.
643
644    This document and the information contained herein is provided on an
645    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
646    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
647    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
648    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
649    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
650
651 Acknowledgement
652
653    Funding for the RFC Editor function is currently provided by the
654    Internet Society.
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674 Hodges, et al.              Standards Track                    [Page 12]
675 \f