RFC 3771

The Lightweight Directory Access Protocol (LDAP) Intermediate Response Message

📅 published April 2004, from ietf

The Lightweight Directory Access Protocol (LDAP) Intermediate Response Message 🎀

okay bestie, this one is an Internet standards track spec (so it's official, not a vibe), written by R. Harrison of Novell, Inc. and K. Zeilenga of the OpenLDAP Foundation, dated April 2004 💅. It's RFC 3771, and it updates RFC 2251 🦋. It's about giving LDAP a brand new message type for sending intermediate results, and that's a whole mood ✨.

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 Notice 💜

Abstract 🦋

okay so this doc defines and describes the IntermediateResponse message, which is a general way to build single-request/multiple-response operations in LDAP (Lightweight Directory Access Protocol) 🔥. The big slay is that it's built so the behaviour of existing LDAP operations stays exactly the same 🫶. This message is meant to be used with the LDAP ExtendedRequest and ExtendedResponse to make brand new single-request/multiple-response operations, or with a control when you're extending an existing LDAP operation that needs to hand back intermediate response info 🎀.

1. Introduction ✨

LDAP, version 3 [RFC3377], is an extensible protocol, and it's giving main character energy 👑. Extended operations ([RFC2251] Section 4.12) let you add brand new operations to LDAP without needing a full protocol revision 💖. Controls ([RFC2251] Section 4.1.12) do a similar job, but they're for extending or modifying how existing LDAP operations behave 🧚.

LDAP is a client-request/server-response based protocol 🍓. Except for the search operation, the entire response to an operation request comes back in a single protocol data unit (i.e., LDAP message). Honestly, this single-request/single-response paradigm is good enough for lots of operations (including all but one of those currently defined by [RFC3377]). But both intuition and practical experience show it isn't enough for others 😭.

For example, the LDAP delete operation could be extended with a subtree control so that a whole subtree gets deleted 🌳. A subtree delete needs to return continuation references based on subordinate knowledge information stored in the server, so the client can finish the operation 💅. If the references come back as they're found, instead of with the final result, the client can work more efficiently, because it doesn't have to wait for the final result to get that continuation reference info 🔥.

Same tea, different cup: an engineer might decide to build the subtree delete as its own extended operation instead of using a subtree control with the delete operation 🦋. Either way, the client still needs those same continuation references to finish, and sending them as they're found would still let the client work more efficiently 💜.

Some operations get completed in stages, or move through different states as they go, and they might want to send intermediate responses to the client so it knows how things are going 🫶. For example, an LDAP implementation might define an extended operation to create a new replica of an administrative area on a server. That operation is completed in three stages: (1) begin creation of replica, (2) send replica data to server, (3) replica creation complete. Intermediate messages might be sent from the server to the client at the beginning of each stage, with the final response for the extended operation sent after stage (3) is complete 🌈.

Right now, as LDAP [RFC3377] is defined, there's no general LDAP message type for returning intermediate results 💀. A single, reusable LDAP message for carrying intermediate response information is what we want, so the protocol doesn't have to keep getting modified over and over 🎀. ExtendedResponse is already defined in LDAP, but it's defined to be the one and only response message to an ExtendedRequest message ([RFC2251] Section 4.12), for unsolicited notifications ([RFC2251] Section 4.4), and to return intermediate responses for the search operation ([RFC3377] Section 4.5.2, also see Section 5 below). Turning ExtendedResponse into a general intermediate response mechanism would be problematic 🙈. In particular, existing APIs would likely have to be redesigned. It is believed (based upon operational experience) that adding a new message to carry intermediate result information is easier to implement, and less likely to cause interoperability problems with existing deployed implementations ✨.

This document defines and describes the LDAP IntermediateResponse message 💖. It's meant to be used with ExtendedRequest and ExtendedResponse to define new single-request/multiple-response operations, or with a control when you're extending existing LDAP operations in a way that requires them to return intermediate response information 🦋.

The definitions and descriptions of extended operations and controls that use the IntermediateResponse message will define the circumstances in which a server can send an IntermediateResponse message, plus what that message means in each particular circumstance 📝. Clients, meanwhile, will explicitly ask for IntermediateResponse messages by issuing operations that specifically call for their return 🫶.

The LDAP Content Sync Operation [ZEILENGA] is one example of LDAP Intermediate Response messages in action 🔥.

2. 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 [RFC2119] 🎀.

The term "request control" is used to describe a control that is included in an LDAP request message sent from an LDAP client to an LDAP server 🌸.

3. The IntermediateResponse Message 🧚

This document extends the protocolOp CHOICE of LDAPMessage ([RFC2251] Section 4.1.1) to include the field:

           intermediateResponse  IntermediateResponse

where IntermediateResponse is defined as:

           IntermediateResponse ::= [APPLICATION 25] SEQUENCE {
                   responseName     [0] LDAPOID OPTIONAL,
                   responseValue    [1] OCTET STRING OPTIONAL }

IntermediateResponse messages SHALL NOT be returned to the client unless the client issues a request that specifically solicits their return 🙅‍♀️. This document defines two forms of solicitation: extended operation and request control ✨.

Even though responseName and responseValue are optional in some circumstances, IntermediateResponse messages usually have a predefined responseName and a responseValue 💜. The value of the responseName (if present), the syntax of the responseValue (if present), and the semantics associated with a particular IntermediateResponse message MUST be specified in documents describing the extended operation or request control that uses them 📚. Sections 3.1 and 3.2 describe additional requirements for including responseName and responseValue in IntermediateResponse messages 🦋.

3.1. Usage with LDAP ExtendedRequest and ExtendedResponse 🌈

A single-request/multiple-response operation may be defined using a single ExtendedRequest message to solicit zero or more IntermediateResponse messages, of one or more kinds, followed by an ExtendedResponse message 🫶.

An extended operation that defines the return of multiple kinds of IntermediateResponse messages MUST provide and document a mechanism for the client to distinguish the kind of IntermediateResponse message being sent. This SHALL be accomplished by using different responseName values for each type of IntermediateResponse message associated with the extended operation, or by including identifying information in the responseValue of each type of IntermediateResponse message associated with the extended operation 🔥.

3.2. Usage with LDAP Request Controls 💖

Any LDAP operation may be extended by adding one or more controls ([RFC2251] Section 4.1.12) 🎀. A control's semantics may include the return of zero or more IntermediateResponse messages before the final result code for the operation is returned 🧚. One or more kinds of IntermediateResponse messages may be sent in response to a request control 🍓.

All IntermediateResponse messages associated with request controls SHALL include a responseName 💅. This requirement makes sure the client can correctly identify where IntermediateResponse messages came from when:

a) two or more controls using IntermediateResponse messages are included in a request for any LDAP operation, or

b) one or more controls using IntermediateResponse messages are included in a request with an LDAP extended operation that uses IntermediateResponse messages.

A request control that defines the return of multiple kinds of IntermediateResponse messages MUST provide and document a mechanism for the client to distinguish the kind of IntermediateResponse message being sent. This SHALL be accomplished by using different responseName values for each type of IntermediateResponse message associated with the request control, or by including identifying information in the responseValue of each type of IntermediateResponse message associated with the request control 🫶.

7.1. LDAP Message Type 🎀

Okay so, IANA already did the paperwork ✨ They registered LDAP Message Type (25) for the LDAP IntermediateResponse message from section 3 of this document. Iconic. 💅

The registration template is below, so you can see exactly what they filed:

   Subject: Request for LDAP Message Type Registration
   Person & email address to contact for further information:
      Roger Harrison <roger_harrison@novell.com>
      Specification: RFC3771
      Author/Change Controller: IESG
      Comments: Identifies the LDAP IntermediateResponse Message

8. Acknowledgments 🫶

The authors gave a big shoutout to the members of the IETF LDAP Extensions (ldapext) working group mailing list. They were the ones who responded when someone suggested that a multiple-response paradigm might be useful for LDAP extended requests. 💖 Two people get special thanks: David Wilbur, who first brought the idea up on the working group list, and Thomas Salter, who summed up the group's discussion so well. Main character energy for both of them. 🌸

9. References 📚

9.1. Normative References 💜

[RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
[RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997.
[RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002.
[RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002.

9.2. Informative References 🦋

[ZEILENGA] Zeilenga, K., "LDAP Content Synchronization Operation", Work in Progress, February 2004.

10. Authors' Addresses 🧚

   Roger Harrison
   Novell, Inc.
   1800 S. Novell Place
   Provo, UT 84606

   Phone: +1 801 861 2642
   EMail: roger_harrison@novell.com


   Kurt D. Zeilenga
   OpenLDAP Foundation

   EMail: Kurt@OpenLDAP.org

11. Full Copyright Statement ⭐

Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.

Intellectual Property 🔥

The IETF takes no position on whether any Intellectual Property Rights or other rights that might be claimed to cover the implementation or use of the technology in this document are valid or in scope. It also doesn't say whether any license under those rights might be available. It hasn't made any independent effort to find out either. 🙈 If you want to learn how rights work for RFC documents, check out BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat, any assurances of licenses to be made available, and the results of any attempt to get a general license or permission to use those proprietary rights can be found in the IETF online IPR repository at http://www.ietf.org/ipr. Implementers and users can check there.

The IETF invites anyone interested to tell it about any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard. Send that information to the IETF at ietf-ipr@ietf.org. 💌

Acknowledgement 🌈

Funding for the RFC Editor function is currently provided by the Internet Society. 💖

📦 where this page comes from

ietf: rfc3771 2004-04
💖 girlified by claude-haiku-5-5 on 2026-10-16: a language model's rewrite of the original, under its terms