RFC 2830

Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security

📅 published May 2000, from ietf

RFC 2830 📜 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security 🎀

The title block, bestie:

  • Status: Standards Track, so this is an official Internet standards track protocol 🔥
  • Date: May 2000 📅
  • Authors: J. Hodges (Oblix Inc.), R. Morgan (Univ of Washington), and M. Wahl (Sun Microsystems, Inc.) 👯‍♀️
  • Obsoletes and updates: the header doesn't list anything it obsoletes or updates, so there's nothing to report here 🫶

Also, the Status of this Memo says it asks for discussion and suggestions for improvements, and that distribution is unlimited. 🦋

Status of this Memo ✨

This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. 💅

Copyright (C) The Internet Society (2000). All Rights Reserved.

Abstract 🔮

Okay so this doc defines the "Start Transport Layer Security (TLS) Operation" for LDAP [LDAPv3, TLS]. It's the thing that sets up TLS inside an LDAP association, and it's built on top of an LDAP extended request. Main character energy 👑

1. Conventions Used in this Document 🎀

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

2. The Start TLS Request 💖

This section is the tea on the Start TLS extended request and extended response: how to form the request, what the response looks like, and the result codes the client MUST be prepared to handle. Lowkey the most important bit. 😭

The section after this one walks through how to sequence a whole Start TLS Operation. 🦋

2.1. Requesting TLS Establishment 🌈

A client may perform a Start TLS operation by sending an LDAP PDU that contains an ExtendedRequest [LDAPv3], with the OID for the Start TLS operation in it:

1.3.6.1.4.1.1466.20037

Here's how an LDAP ExtendedRequest is defined:

ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
        requestName             [0] LDAPOID,
        requestValue            [1] OCTET STRING OPTIONAL }

To make a Start TLS extended request, you set the requestName field to the OID string above. The requestValue field is absent. Then the client MUST NOT send any PDUs on this connection after that request until it gets a Start TLS extended response. Hold up, that's a hard rule. 🙈

When a Start TLS extended request comes in, the server MUST return an LDAP PDU that has a Start TLS extended response. Here's the ExtendedResponse definition:

ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
        COMPONENTS OF LDAPResult,
        responseName     [10] LDAPOID OPTIONAL,
        response         [11] OCTET STRING OPTIONAL }

A Start TLS extended response MUST contain a responseName field, and that field MUST be set to the same string as the responseName field in the Start TLS extended request. The response field is absent. The server MUST set the resultCode field to either success or one of the other values outlined in section 2.3. 💅

2.2. "Success" Response ✨

If the ExtendedResponse has a resultCode of success, that means the server is willing and able to negotiate TLS. Go to section 3, below, for the details. 🫶

2.3. Response other than "success" 💀

If the ExtendedResponse has a resultCode other than success, the server is unwilling or unable to negotiate TLS. Not the vibe. 😔

If the Start TLS extended request didn't work out, the resultCode will be one of these:

operationsError  (operations sequencing incorrect; e.g. TLS already
                 established)

protocolError    (TLS not supported or incorrect PDU structure)

referral         (this server doesn't do TLS, try this one)

unavailable      (e.g. some major problem with TLS, or server is
                 shutting down)

The server MUST return operationsError if the client breaks any of the Start TLS extended operation sequencing requirements in section 3, below. Rule-breakers get caught 🙅‍♀️

If the server doesn't support TLS (whether that's by design or by its current configuration), it MUST set the resultCode to protocolError (see section 4.1.1 of [LDAPv3]), or to referral. If it picks referral, the server MUST include an actual referral value in the LDAP Result. The client's current session is unaffected when the server doesn't support TLS, so the client MAY proceed with any LDAP operation, or it MAY close the connection. Still in the group chat, babe. 🌷

The server MUST return unavailable if it supports TLS but can't establish a TLS connection for some reason. Examples: the certificate server isn't responding, it can't contact its TLS implementation, or the server is in the middle of shutting down. In that case the client MAY retry the StartTLS operation, or it MAY proceed with any other LDAP operation, or it MAY close the connection. 🥺

3. Sequencing of the Start TLS Operation 🧚‍♀️

This section describes the overall procedures that clients and servers MUST follow to establish TLS. These procedures take into account the overall security of the LDAP association, including discovering the resulting security level and asserting the client's authorization identity. It's giving security-core. 🔐

Note that the exact effects that establishing TLS on an LDAP association has on a client's authorization identity are described in detail in section 5. 🍓

3.1. Requesting to Start TLS on an LDAP Association 🌸

The client MAY send the Start TLS extended request at any time after establishing an LDAP association. The exception is these cases, where the client MUST NOT send a Start TLS extended request:

  • if TLS is currently established on the connection, or
  • during a multi-stage SASL negotiation, or
  • if there are any LDAP operations outstanding on the connection.

If you break any of these requirements, you get a resultCode of operationsError, as described above in section 2.3. Oops. 💀

The client MAY have already performed a Bind operation when it sends a Start TLS request. Or the client might not have bound yet. Both are valid, no cap. 🦋

If the client hasn't established a TLS connection before sending any other requests, and the server requires one before it performs a particular request, the server MUST reject that request with a confidentialityRequired or strongAuthRequired result. Then the client MAY send a Start TLS extended request, or it MAY choose to close the connection. 🫶

3.2. Starting TLS 💫

The server returns an extended response with a resultCode of success if it's willing and able to negotiate TLS. If it can't, it returns one of the other resultCodes documented above. ✨

In the successful case, the client has stopped transferring LDAP requests on the connection, and it MUST either begin a TLS negotiation or close the connection. The client sends PDUs in the TLS Record Protocol directly over the underlying transport connection to the server to start the TLS negotiation [TLS]. 🔥

3.3. TLS Version Negotiation 🌈

Negotiating which version of TLS or SSL to use is part of the TLS Handshake Protocol, as documented in [TLS]. Check that doc for the details. 📚

3.4. Discovery of Resultant Security Level 🔐

After a TLS connection is established on an LDAP association, both parties MUST individually decide whether to continue based on the privacy level that was achieved. Figuring out the TLS connection's privacy level is implementation dependent, and you do it by talking to your own local TLS implementation. 🧠

If the client or server decides the level of authentication or privacy isn't high enough to continue, it SHOULD gracefully close the TLS connection right after the TLS negotiation completes (see sections 4.1 and 5.2, below). 🙅‍♀️

The client MAY attempt to Start TLS again, or it MAY send an unbind request, or it can send any other LDAP request. Options, options. 🎀

3.5. Assertion of Client's Authorization Identity 👑

When it gets a Start TLS extended response that says success, the client MAY assert that a specific authorization identity be used in working out the client's authorization status. To do that, the client sends an LDAP Bind request with a SASL mechanism of "EXTERNAL" [SASL]. See section 5.1.2, below. 💖

3.6. Server Identity Check 🕵️‍♀️

The client MUST check its understanding of the server's hostname against the server's identity as presented in the server's Certificate message. This is how you prevent man-in-the-middle attacks, so it's non-negotiable 😤

Matching works like this:

  • The client MUST use the server hostname it used to open the LDAP connection as the value to compare against the server name in the server's certificate. The client MUST NOT use the server's canonical DNS name or any other derived form of name. 🚫
  • If a subjectAltName extension of type dNSName is present in the certificate, it SHOULD be used as the source of the server's identity. 🌷
  • Matching is case-insensitive. 🍓
  • The "*" wildcard character is allowed. If it's present, it only applies to the left-most name component.

E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com. If more than one identity of a given type is in the certificate (like more than one dNSName), a match against any one of them is acceptable. 🧚

If the hostname doesn't match the dNSName-based identity in the certificate under the check above, user-oriented clients SHOULD either notify the user (clients MAY give the user the chance to continue with the connection anyway) or terminate the connection and indicate that the server's identity is suspect. Automated clients SHOULD close the connection, and return and/or log an error saying the server's identity is suspect. 🚨

Beyond the server identity checks in this section, clients SHOULD be ready to do further checking to make sure the server is authorized to provide the service it appears to provide. The client MAY need to use local policy information. 🫶

3.7. Refresh of Server Capabilities Information 🔄

The client MUST refresh any cached server capabilities information (e.g. from the server's root DSE; see section 3.4 of [LDAPv3]) once the TLS session is established. This matters because it protects against active-intermediary attacks that may have altered server capabilities information retrieved before TLS was established. The server MAY advertise different capabilities after TLS establishment. Plot twist. 😳

4. Closing a TLS Connection 🚪

4.1. Graceful Closure 🌙

Either the client or the server MAY end the TLS connection on an LDAP association by sending a TLS closure alert. The LDAP association itself stays intact. 💜

Before closing a TLS connection, the client MUST either wait for any outstanding LDAP operations to finish, or explicitly abandon them [LDAPv3]. ✨

After the initiator of a close has sent a closure alert, it MUST discard any TLS messages until it has received an alert from the other party. It stops sending TLS Record Protocol PDUs, and once the alert arrives, it MAY send and receive LDAP PDUs. 🎀

The other party, if it receives a closure alert, MUST immediately send a TLS closure alert back. It then stops sending TLS Record Protocol PDUs, and MAY send and receive LDAP PDUs. 🦋

4.2. Abrupt Closure 💥

okay so either the client or the server MAY just yeet the whole LDAP association 🫠 and any TLS connection on it by dropping the underlying TCP connection. no warning needed. if the server wants to be nice about it, it MAY send the client a Notice of Disconnection [LDAPv3] first 🫶

5. Effects of TLS on a Client's Authorization Identity 🪞

this section is all about how turning on TLS over an LDAP association changes a client's authorization identity 👑 we start with the default effects, then get into client assertion of authorization identity (including the error conditions), and finally look at what happens when the TLS connection closes 🎀

Authorization identities and related concepts are defined in [AuthMeth] 📖

5.1. TLS Connection Establishment Effects 🌸

5.1.1. Default Effects 🧸

when a TLS connection gets established onto the LDAP association, any authentication and authorization identities that were already set up MUST stay in force 🔒 that includes the anonymous state too. and this still holds if the server asks for client authentication over TLS, like when it asks the client for its certificate during the TLS negotiation (see [TLS]) 🪪

5.1.2. Client Assertion of Authorization Identity 💌

a client MAY either implicitly ask for its LDAP authorization identity to be derived from its authenticated TLS credentials, OR it MAY explicitly give an authorization identity and assert that it should be used together with its authenticated TLS credentials ✨ the first one is called an implicit assertion, and the second one is an explicit assertion. two flavours, same vibe 🍓

5.1.2.1. Implicit Assertion 🦋

an implicit authorization identity assertion happens after TLS is established. the client invokes a Bind request of the SASL form using the EXTERNAL mechanism name [SASL, LDAPv3], and this request SHALL NOT include the optional credentials octet string (the one found inside the SaslCredentials sequence in the Bind Request) 🚫 the server then derives the client's authorization identity from the authentication identity in the client's TLS credentials (typically a public key certificate), following local policy 🕵️‍♀️ how exactly that works under the hood is implementation specific, so every server does its own thing 🤷‍♀️

5.1.2.2. Explicit Assertion 🎯

an explicit authorization identity assertion also happens after TLS is established, using a Bind request of the SASL form with the EXTERNAL mechanism name [SASL, LDAPv3]. this time the request SHALL include the credentials octet string. that string MUST be constructed as documented in section 9 of [AuthMeth] 📝

5.1.2.3. Error Conditions 🚨

no matter which form of assertion you use, the server MUST check that the client's authentication identity (as given in its TLS credentials) is allowed to be mapped to the asserted authorization identity 🔍 if the client isn't authorized like that, the server MUST reject the Bind operation with an invalidCredentials resultCode in the Bind response 🙅‍♀️

also, with either form of assertion, the SASL EXTERNAL bind MUST fail with a result code of inappropriateAuthentication if either of these is true 💀

  • a TLS session was NOT established between the client and server before the SASL EXTERNAL Bind request, AND there's no other external source of authentication credentials (for example, IP-level security [IPSEC]), OR
  • during the process of setting up the TLS session, the server did not ask the client for its authentication credentials

wait, the server MAY... no, let me say it properly 🙈 after any of the Bind operation failures above, all of the client's authentication and authorization state on the LDAP association is lost, so the association is in an anonymous state after the failure 🫥 the TLS connection state is unaffected, though a server MAY end the TLS connection via a TLS close_notify message based on the Bind failure (it MAY do that at any time, honestly) 🔚

5.2. TLS Connection Closure Effects 🌙

closing the TLS connection MUST move the LDAP association into an anonymous authentication and authorization state 🫥 this happens no matter what state was established over TLS, and no matter what the authentication and authorization state was before the TLS connection got set up 🧹

6. Security Considerations 🛡️💖

the whole point of using the TLS protocol with LDAP is to keep the connection confidential and intact, and to optionally add authentication 🔐 TLS clearly provides these capabilities, as described in [TLS] ✨

all of the security you get from the Start TLS operation comes from TLS itself 💅 the Start TLS operation on its own doesn't add any extra security. just vibes 🫠

the use of TLS does NOT provide or ensure confidentiality and/or non-repudiation for the data stored by an LDAP-based directory server 😱 it also doesn't stop the server administrators from looking at that data. once TLS is up, it only protects the confidentiality and integrity of the operations and data in transit over the LDAP association, and only if both the client and server support it and negotiate it 🚧

the security level you actually get from TLS depends directly on both the quality of the TLS implementation and how that implementation is used 🔧 on top of that, an active-intermediary attacker can remove the Start TLS extended operation from the supportedExtension attribute of the root DSE 👀 so both parties SHOULD independently check and agree to the security level achieved once TLS is established, before they start using the TLS connection 🤝 for example, the security level of the TLS connection might have been negotiated down to plaintext 😭

Clients SHOULD either warn the user when the security level achieved doesn't provide confidentiality and/or integrity protection, or be configurable so they refuse to proceed without an acceptable level of security 🚨

Client and server implementors SHOULD take measures to properly protect credentials and other confidential data, wherever the TLS implementation doesn't already do that 🔏

Server implementors SHOULD let server administrators choose whether and when connection confidentiality and/or integrity is required, and also choose whether and when client authentication via TLS is required ⚙️

7. Acknowledgements 💜

the authors thank Tim Howes, Paul Hoffman, John Kristian, Shirish Rai, Jonathan Trostle, Harald Alvestrand, and Marcus Leech for their contributions to this document 🫶

8. References 📚

  • [AuthMeth] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000.
  • [IPSEC] Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.
  • [LDAPv3] Wahl, M., Kille S. and T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
  • [ReqsKeywords] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997.
  • [TLS] Dierks, T. and C. Allen. "The TLS Protocol Version 1.0", RFC 2246, January 1999.

9. Authors' Addresses 🗺️

Jeff Hodges
Oblix, Inc.
18922 Forge Drive
Cupertino, CA 95014
USA

Phone: +1-408-861-6656
EMail: JHodges@oblix.com
RL "Bob" Morgan
Computing and Communications
University of Washington
Seattle, WA
USA

Phone: +1-206-221-3307
EMail: rlmorgan@washington.edu
Mark Wahl
Sun Microsystems, Inc.
8911 Capital of Texas Hwy #4140
Austin TX 78759
USA

EMail: M.Wahl@innosoft.com

10. Intellectual Property Rights Notices 🎀

the IETF takes no position on the validity or scope of any intellectual property or other rights that might be claimed to apply to the implementation or use of the technology described in this document, or on whether any license under those rights might or might not be available. it also doesn't say it has tried to identify any such rights 🤐 info about the IETF's procedures for rights in standards-track and standards-related documentation can be found in BCP-11. copies of claims of rights made available for publication, any assurances of licenses to be made available, or the result of an attempt to get a general license or permission for implementors or users to use those proprietary rights, can be obtained from the IETF Secretariat 📬

the IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology required to practice this standard. please send that info to the IETF Executive Director 💌

Copyright (C) The Internet Society (2000). All Rights Reserved. 🌈

this document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. however, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards (in which case the procedures for copyrights defined in the Internet Standards process must be followed), or as required to translate it into languages other than English 🌍

the limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns ♾️

this document and the information contained herein is provided on an "AS IS" basis, and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 🫡

Acknowledgement 🌷

funding for the RFC Editor function is currently provided by the Internet Society 💸

📦 where this page comes from