1 LDAPEXT Working Group Jeff Hodges, Stanford
2 INTERNET-DRAFT RL "Bob" Morgan, Univ of Washington
3 Intended Category: Mark Wahl, Innosoft
4 Standards Track June, 1999
7 Lightweight Directory Access Protocol (v3):
8 Extension for Transport Layer Security
9 <draft-ietf-ldapext-ldapv3-tls-05.txt>
13 Status of this Document
15 This document is an Internet-Draft and is in full conformance with all
16 provisions of Section 10 of RFC2026.
18 Internet-Drafts are working documents of the Internet Engineering Task
19 Force (IETF), its areas, and its working groups. Note that other groups
20 may also distribute working documents as Internet-Drafts.
22 Internet-Drafts are draft documents valid for a maximum of six months
23 and may be updated, replaced, or obsoleted by other documents at any
24 time. It is inappropriate to use Internet- Drafts as reference material
25 or to cite them other than as "work in progress."
27 The list of current Internet-Drafts can be accessed at
28 http://www.ietf.org/ietf/1id-abstracts.txt
30 The list of Internet-Draft Shadow Directories can be accessed at
31 http://www.ietf.org/shadow.html.
33 Comments and suggestions on this document are encouraged. Comments on
34 this document should be sent to the LDAPEXT working group discussion
36 ietf-ldapext@netscape.com
38 This document expires in December 1999.
43 This document defines the "Start Transport Layer Security (TLS) Opera-
44 tion" for LDAP [LDAPv3, TLS]. This operation provides for TLS establish-
45 ment in an LDAP association and is defined in terms of an LDAP extended
52 Hodges, Morgan, Wahl [Page 1]
54 I-D LDAPv3: Extension for Transport Layer Security June 1999
57 2. Conventions Used in this Document
59 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
60 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
61 document are to be interpreted as described in [ReqsKeywords].
63 3. The Start TLS Request
65 This section describes the Start TLS extended request and extended
66 response themselves: how to form the request, the form of the response,
67 and enumerates the various result codes the client MUST be prepared to
70 The section following this one then describes how to sequence an overall
73 3.1. Requesting TLS Establishment
75 A client may perform a Start TLS operation by transmitting an LDAP PDU
76 containing an ExtendedRequest [LDAPv3] specifying the OID for the Start
79 1.3.6.1.4.1.1466.20037
81 An LDAP ExtendedRequest is defined as follows:
83 ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
84 requestName [0] LDAPOID,
85 requestValue [1] OCTET STRING OPTIONAL }
87 A Start TLS extended request is formed by setting the requestName field
88 to the OID string given above. The requestValue field is absent. The
89 client MUST NOT send any PDUs on this connection following this request
90 until it receives a Start TLS extended response.
92 When a Start TLS extended request is made, the server MUST return an
93 LDAP PDU containing a Start TLS extended response. An LDAP Exten-
94 dedResponse is defined as follows:
96 ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
97 COMPONENTS OF LDAPResult,
98 responseName [10] LDAPOID OPTIONAL,
99 response [11] OCTET STRING OPTIONAL }
101 A Start TLS extended response MUST contain a responseName field which
102 MUST be set to the same string as that in the responseName field present
103 in the Start TLS extended request. The response field is absent. The
104 server MUST set the resultCode field to either success or one of the
108 Hodges, Morgan, Wahl [Page 2]
110 I-D LDAPv3: Extension for Transport Layer Security June 1999
113 other values outlined in section 3.3.
115 3.2. "Success" Response
117 If the ExtendedResponse contains a resultCode of success, this indicates
118 that the server is willing and able to negotiate TLS. Refer to section
119 4, below, for details.
121 3.3. Response other than "success"
123 If the ExtendedResponse contains a resultCode other than success, this
124 indicates that the server is unwilling or unable to negotiate TLS.
126 If the Start TLS extended request was not successful, the resultCode
129 operationsError (operations sequencing incorrect; e.g. TLS already
132 protocolError (TLS not supported or incorrect PDU structure)
134 referral (this server doesn't do TLS, try this one)
136 unavailable (e.g. some major problem with TLS, or server is
139 The server MUST return operationsError if the client violates any of the
140 Start TLS extended operation sequencing requirements described in sec-
143 If the server does not support TLS (whether by design or by current con-
144 figuration), it MUST set the resultCode to protocolError (see section
145 4.1.1 of [LDAPv3]), or to referral. The server MUST include an actual
146 referral value in the LDAP Result if it returns a resultCode of refer-
147 ral. The client's current session is unaffected if the server does not
148 support TLS. The client MAY proceed with any LDAP operation, or it MAY
149 close the connection.
151 The server MUST return unavailable if it supports TLS but cannot estab-
152 lish a TLS connection for some reason, e.g. the certificate server not
153 responding, it cannot contact its TLS implementation, or if the server
154 is in process of shutting down. The client MAY retry the StartTLS opera-
155 tion, or it MAY proceed with any other LDAP operation, or it MAY close
158 4. Sequencing of the Start TLS Operation
160 This section describes the overall procedures clients and servers MUST
164 Hodges, Morgan, Wahl [Page 3]
166 I-D LDAPv3: Extension for Transport Layer Security June 1999
169 follow for TLS establishment. These procedures take into consideration
170 various aspects of the overall security of the LDAP association includ-
171 ing discovery of resultant security level and assertion of the client's
172 authorization identity.
174 Note that the precise effects, on a client's authorzation identity, of
175 establishing TLS on an LDAP association are described in detail in sec-
178 4.1. Requesting to Start TLS on an LDAP Association
180 The client MAY send the Start TLS extended request at any time after
181 establishing an LDAP association, except that in the following cases the
182 client MUST NOT send a Start TLS extended request:
184 - if TLS is currently established on the connection, or
185 - during a multi-stage SASL negotiation, or
186 - if there are any LDAP operations outstanding on the connection.
188 The result of violating any of these requirements is a resultCode of
189 operationsError, as described above in section 3.3.
191 The client MAY have already perfomed a Bind operation when it sends a
192 Start TLS request, or the client might have not yet bound.
194 If the client did not establish a TLS connection before sending any
195 other requests, and the server requires the client to establish a TLS
196 connection before performing a particular request, the server MUST
197 reject that request with a confidentialityRequired or strongAuthRequired
198 result. The client MAY send a Start TLS extended request, or it MAY
199 choose to close the connection.
203 The server will return an extended response with the resultCode of suc-
204 cess if it is willing and able to negotiate TLS. It will return other
205 resultCodes, documented above, if it is unable.
207 In the successful case, the client, which has ceased to transfer LDAP
208 requests on the connection, MUST either begin a TLS negotiation or close
209 the connection. The client will send PDUs in the TLS Record Protocol
210 directly over the underlying transport connection to the server to ini-
211 tiate TLS negotiation [TLS].
213 4.3. TLS Version Negotiation
215 Negotiating the version of TLS or SSL to be used is a part of the TLS
216 Handshake Protocol, as documented in [TLS]. Please refer to that
220 Hodges, Morgan, Wahl [Page 4]
222 I-D LDAPv3: Extension for Transport Layer Security June 1999
225 document for details.
227 4.4. Discovery of Resultant Security Level
229 After a TLS connection is established on an LDAP association, both par-
230 ties MUST individually decide whether or not to continue based on the
231 privacy level achieved. Ascertaining the TLS connection's privacy level
232 is implementation dependent, and accomplished by communicating with
233 one's respective local TLS implementation.
235 If the client or server decides that the level of authentication or
236 privacy is not high enough for it to continue, it SHOULD gracefully
237 close the TLS connection immediately after the TLS negotiation has com-
238 pleted (see sections 5 and 7.2, below).
240 The client MAY attempt to Start TLS again, or MAY send an unbind
241 request, or send any other LDAP request.
243 4.5. Assertion of Client's Authorization Identity
245 The client MAY, upon receipt of a Start TLS extended response indicating
246 success, assert that a specific authorization identity be utilized in
247 determining the client's authorization status. The client accomplishes
248 this via an LDAP Bind request specifying a SASL mechanism of "EXTERNAL"
249 [SASL]. See section 7, below.
251 4.6. Server Identity Check
253 The client MUST check its understanding of the server's hostname against
254 the server's identity as presented in the server's Certificate message,
255 in order to prevent man-in-the-middle attacks.
257 If a subjectAltName extension of type dNSName is present, it SHOULD be
258 used as the source of the server's identity.
260 Matching is performed according to these rules:
262 - The client MUST use the server hostname it used to open
263 the LDAP connection as the value to compare against the
264 server name as expressed in the server's certificate.
265 The client MUST NOT use the server's canonical DNS name or
266 any other derived form of name.
268 - If a subjectAltName extension of type dNSName is present
269 in the certificate, it SHOULD be used as the source of the
272 - Matching is case-insensitive.
276 Hodges, Morgan, Wahl [Page 5]
278 I-D LDAPv3: Extension for Transport Layer Security June 1999
281 - The "*" wildcard character is allowed.
282 - If present, it applies only to the left-most name component.
284 E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com.
285 If more than one identity of a given type is present in the certificate
286 (e.g. more than one dNSName name), a match in any one of the set is con-
289 If the hostname does not match the dNSName-based identity in the certi-
290 ficate per the above check, user-oriented clients SHOULD either notify
291 the user (clients MAY give the user the opportunity to continue with the
292 connection in any case) or terminate the connection and indicate that
293 the server's identity is suspect. Automated clients SHOULD close the
294 connection, returning and/or logging an error indicating hat the
295 server's identity is suspect.
297 4.7. Refresh of Server Capabilities Information
299 The client MUST refresh any cached server capabilities information (e.g.
300 from the server's root DSE; see section 3.4 of [LDAPv3]) upon TLS ses-
301 sion establishment. This is necessary to protect against active-
302 intermediary attacks which may have altered any server capabilities
303 information retrieved prior to TLS establishment. The server MAY adver-
304 tise different capabilities after TLS establishment.
306 5. Closing a TLS Connection
308 5.1. Graceful Closure
310 Either the client or server MAY terminate the TLS connection on an LDAP
311 association by sending a TLS closure alert. This will leave the LDAP
314 Before closing a TLS connection, the client MUST either wait for any
315 outstanding LDAP operations to complete, or explicitly abandon them
318 After the initiator of a close has sent a closure alert, it MUST discard
319 any TLS messages until it has received an alert from the other party.
320 It will cease to send TLS Record Protocol PDUs, and following the
321 reciept of the alert, MAY send and receive LDAP PDUs.
323 The other party, if it receives a closure alert, MUST immediately
324 transmit a TLS closure alert. It will subequently cease to send TLS
325 Record Protocol PDUs, and MAY send and receive LDAP PDUs.
332 Hodges, Morgan, Wahl [Page 6]
334 I-D LDAPv3: Extension for Transport Layer Security June 1999
339 Either the client or server MAY abruptly close the entire LDAP associa-
340 tion and any TLS connection established on it by dropping the underlying
341 TCP connection. A server MAY beforehand send the client a Notice of
342 Disconnection [LDAPv3] in this case.
344 6. Authentication and Authorization: Definitions and Concepts
346 This section defines basic terms, concepts, and interrelationships
347 regarding authentication, authorization, credentials, and identity.
348 These concepts are used in describing how various security approaches
349 are utilized in client authentication and authorization.
351 6.1. Access Control Policy
353 An access control policy is a set of rules defining the protection of
354 resources, generally in terms of the capabilities of persons or other
355 entities accessing those resources. A common expression of an access
356 control policy is an access control list. Security objects and mechan-
357 isms, such as those described here, enable the expression of access con-
358 trol policies and their enforcement. Access control policies are typi-
359 cally expressed in terms of access control attributes as described
362 7. Effects of TLS on a Client's Authorization Identity
364 This section describes the effects on a client's authorization identity
365 brought about by establishing TLS on an LDAP association. The default
366 effects are described first, and next the facilities for client asser-
367 tion of authorization identity are discussed including error conditions.
368 Lastly, the effects of closing the TLS connection are described.
370 Authorization identities and related concepts are defined in [AuthMeth].
372 7.1. TLS Connection Establishment Effects
374 7.1.1. Default Effects
376 Upon establishment of the TLS connection onto the LDAP association, any
377 previously established authentication and authorization identities MUST
378 remain in force, including anonymous state. This holds even in the case
379 where the server requests client authentication via TLS -- e.g. requests
380 the client to supply its certificate during TLS negotiation (see [TLS]).
382 7.1.2. Client Assertion of Authorization Identity
384 A client MAY either implicitly request that its LDAP authorization
388 Hodges, Morgan, Wahl [Page 7]
390 I-D LDAPv3: Extension for Transport Layer Security June 1999
393 identity be derived from its authenticated TLS credentials or it MAY
394 explicitly provide an authorization identity and assert that it be used
395 in combination with its authenticated TLS credentials. The former is
396 known as an implicit assertion, and the latter as an explicit assertion.
398 7.1.2.1. Implicit Assertion
400 An implicit authorization identity assertion is accomplished after TLS
401 establishment by invoking a Bind request of the SASL form using the
402 "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL NOT include the
403 optional credentials octet string (found within the SaslCredentials
404 sequence in the Bind Request). The server will derive the client's
405 authorization identity from the authentication identity supplied in the
406 client's TLS credentials (typically a public key certificate) according
407 to local policy. The underlying mechanics of how this is accomplished
408 are implementation specific.
410 7.1.2.2. Explicit Assertion
412 An explicit authorization identity assertion is accomplished after TLS
413 establishment by invoking a Bind request of the SASL form using the
414 "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL include the creden-
415 tials octet string. This string MUST be constructed as documented in
416 section 11 of [AuthMeth].
418 7.1.2.3. Error Conditions
420 For either form of assertion, the server MUST verify that the client's
421 authentication identity as supplied in its TLS credentials is permitted
422 to be mapped to the asserted authorization identity. The server MUST
423 reject the Bind operation with an invalidCredentials resultCode in the
424 Bind response if the client is not so authorized. The LDAP association's
425 authentication identity and authorization identity (if any) which were
426 in effect after TLS establishment but prior to making the Bind request,
427 MUST remain in force.
429 Additionally, with either form of assertion, if a TLS session has not
430 been established between the client and server prior to making the SASL
431 EXTERNAL Bind request and there is no other external source of authenti-
432 cation credentials (e.g. IP-level security RFC 1825), or if, during the
433 process of establishing the TLS session, the server did not request the
434 client's authentication credentials, the SASL EXTERNAL bind MUST fail
435 with a result code of inappropriateAuthentication. Any authentication
436 identity and authorization identity, as well as TLS connection, which
437 were in effect prior to making the Bind request, MUST remain in force.
444 Hodges, Morgan, Wahl [Page 8]
446 I-D LDAPv3: Extension for Transport Layer Security June 1999
449 7.2. TLS Connection Closure Effects
451 Closure of the TLS connection MUST cause the LDAP association to move to
452 an anonymous authentication and authorization state regardless of the
453 state established over TLS and regardless of the authentication and
454 authorization state prior to TLS connection establishment.
456 8. Security Considerations
458 The goals of using the TLS protocol with LDAP are to ensure connection
459 confidentiality and integrity, and to optionally provide for authentica-
460 tion. TLS expressly provides these capabilities, as described in [TLS].
462 All security gained via use of the Start TLS operation is gained by the
463 use of TLS itself. The Start TLS operation, on its own, does not provide
464 any additional security.
466 The use of TLS does not provide or ensure for confidentiality and/or
467 non-repudiation of the data housed by an LDAP-based directory server.
468 Nor does it secure the data from inspection by the server administra-
469 tors. Once established, TLS only provides for and ensures confidential-
470 ity and integrity of the operations and data in transit over the LDAP
471 association, and only if the implementations on the client and server
472 support and negotiate it.
474 The level of security provided though the use of TLS depends directly on
475 both the quality of the TLS implementation used and the style of usage
476 of that implementation. Additionally, an active-intermediary attacker
477 can remove the Start TLS extended operation from the supportedExtension
478 attribute of the root DSE. Therefore, both parties SHOULD independently
479 ascertain and consent to the security level achieved once TLS is esta-
480 blished and before begining use of the TLS connection. For example, the
481 security level of the TLS connection might have been negotiated down to
484 Clients SHOULD either warn the user when the security level achieved
485 does not provide confidentiality and/or integrity protection, or be con-
486 figurable to refuse to proceed without an acceptable level of security.
488 Client and server implementors SHOULD take measures to ensure proper
489 protection of credentials and other confidential data where such meas-
490 ures are not otherwise provided by the TLS implementation.
492 Server implementors SHOULD allow for server administrators to elect
493 whether and when connection confidentiality and/or integrity is
494 required, as well as elect whether and when client authentication via
500 Hodges, Morgan, Wahl [Page 9]
502 I-D LDAPv3: Extension for Transport Layer Security June 1999
507 The authors thank Tim Howes, Paul Hoffman, John Kristian, Shirish Rai,
508 Jonathan Trostle, and Harald Alvestrand for their contributions to this
513 [AuthMeth] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan. "Authenti-
514 cation Methods for LDAP". INTERNET-DRAFT, Work In Pro-
515 gress. draft-ietf-ldapext-authmeth-04.txt
517 [LDAPv3] M. Wahl, S. Kille and T. Howes. "Lightweight Directory
518 Access Protocol (v3)". RFC 2251.
520 [ReqsKeywords] Scott Bradner. "Key Words for use in RFCs to Indicate
521 Requirement Levels". RFC 2119.
523 [SASL] J. Myers. "Simple Authentication and Security Layer
526 [TLS] Tim Dierks, C. Allen. "The TLS Protocol Version 1.0". RFC
529 11. Authors' Addresses
532 Computing & Communication Services
536 Stanford, CA 94305-4122
539 Phone: +1-650-723-2452
540 EMail: Jeff.Hodges@Stanford.edu
544 Networks and Distributed Computing
545 University of Washington
549 Phone: +1-206-221-3307
550 EMail: rlmorgan@cac.washington.edu
556 Hodges, Morgan, Wahl [Page 10]
558 I-D LDAPv3: Extension for Transport Layer Security June 1999
562 Innosoft International, Inc.
563 8911 Capital of Texas Hwy, Suite 4140
567 Phone: +1 626 919 3600
568 EMail: Mark.Wahl@innosoft.com
569 -----------------------------------
571 12. Intellectual Property Rights Notices
573 The IETF takes no position regarding the validity or scope of any intel-
574 lectual property or other rights that might be claimed to pertain to
575 the implementation or use of the technology described in this document
576 or the extent to which any license under such rights might or might not
577 be available; neither does it represent that it has made any effort to
578 identify any such rights. Information on the IETF's procedures with
579 respect to rights in standards-track and standards-related documentation
580 can be found in BCP-11. Copies of claims of rights made available for
581 publication and any assurances of licenses to be made available, or the
582 result of an attempt made to obtain a general license or permission for
583 the use of such proprietary rights by implementors or users of this
584 specification can be obtained from the IETF Secretariat.
586 The IETF invites any interested party to bring to its attention any
587 copyrights, patents or patent applications, or other proprietary rights
588 which may cover technology that may be required to practice this stan-
589 dard. Please address the information to the IETF Executive Director.
591 13. Copyright Notice and Disclaimer
593 Copyright (C) The Internet Society (1998). All Rights Reserved.
595 This document and translations of it may be copied and furnished to
596 others, and derivative works that comment on or otherwise explain it
597 or assist in its implementation may be prepared, copied, published
598 and distributed, in whole or in part, without restriction of any
599 kind, provided that the above copyright notice and this paragraph are
600 included on all such copies and derivative works. However, this
601 document itself may not be modified in any way, such as by removing
602 the copyright notice or references to the Internet Society or other
603 Internet organizations, except as needed for the purpose of develop-
604 ing Internet standards in which case the procedures for copyrights
605 defined in the Internet Standards process must be followed, or as
606 required to translate it into languages other than English.
608 The limited permissions granted above are perpetual and will not be
612 Hodges, Morgan, Wahl [Page 11]
614 I-D LDAPv3: Extension for Transport Layer Security June 1999
617 revoked by the Internet Society or its successors or assigns.
619 This document and the information contained herein is provided on an
620 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
621 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
622 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
623 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MER-
624 CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
668 Hodges, Morgan, Wahl [Page 12]