RFC 4527

Lightweight Directory Access Protocol (LDAP) Read Entry Controls 🎀

okay bestie, meet RFC 4527 ✨ It was written by K. Zeilenga of the OpenLDAP Foundation, it's a Standards Track document (so it's a real protocol spec, not just vibes), and it's dated June 2006. The title block doesn't list anything it obsoletes or updates, so no drama there 💅

Status of This Memo 📮

This doc is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🫶 For the current standardization state and status of this protocol, check the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌈

Copyright Notice ©️

Copyright (C) The Internet Society (2006).

Abstract 🦋

This doc adds an extension to LDAP so a client can read the target entry of an update operation. The client can ask for the entry before and/or after the changes get applied, and both reads happen as an atomic part of the update. Main character energy for the entry, honestly 👑

Table of Contents 🧚

   1. Background and Intent of Use ....................................2
   2. Terminology .....................................................2
   3. Read Entry Controls .............................................3
      3.1. The Pre-Read Controls ......................................3
      3.2. The Post-Read Controls .....................................3
   4. Interaction with Other Controls .................................4
   5. Security Considerations .........................................4
   6. IANA Considerations .............................................5
      6.1. Object Identifier ..........................................5
      6.2. LDAP Protocol Mechanisms ...................................5
   7. Acknowledgement .................................................5
   8. References ......................................................6
      8.1. Normative References .......................................6
      8.2. Informative References .....................................7

1. Background and Intent of Use 🌸

okay so this doc extends LDAP [RFC4510] so the client can read the target entry of an update operation (for example Add, Delete, Modify, or ModifyDN) 💖 The extension uses controls [RFC4511] attached to update requests to ask for copies of the target entry and to get those copies back.

There are two request controls. The Pre-Read request control says a copy of the entry from before the update should come back. The Post-Read request control says a copy of the entry from after the update should come back. Each request control has a matching response control, and that's the thing that actually carries the entry back to you 🎀

To keep things properly isolated, the controls are processed as an atomic part of the update operation. No half-finished vibes allowed ✨

The whole functionality is based on similar stuff in the X.500 Directory Access Protocol (DAP) [X.511], so this isn't a brand-new idea, it's a glow-up of something proven 🌈

The Pre-Read controls can get you replaced or deleted values of modified attributes, or a copy of the entry being deleted 🍓

The Post-Read controls can get you values of operational attributes, like 'entryUUID' [RFC4530] and 'modifyTimestamp' [RFC4512], that the server updated as part of the update operation 🔥

2. Terminology 💜

Protocol elements get described using ASN.1 [X.680] with implicit tags. "BER-encoded" means the element gets encoded using the Basic Encoding Rules [X.690], under the restrictions in Section 5.1 of [RFC4511] 🫶

DN stands for Distinguished Name. DSA stands for Directory System Agent (aka a directory server). DSE stands for DSA-specific Entry 🧚

In this doc, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. Those are the official vibes-check words, so they hit different ✨

3. Read Entry Controls 🦋

3.1. The Pre-Read Controls

The Pre-Read request and response controls are identified by the 1.3.6.1.1.13.1 object identifier. Servers that implement these controls SHOULD publish 1.3.6.1.1.13.1 as a value of the supportedControl [RFC4512] in their root DSE 💅

The Pre-Read request control is an LDAP Control [RFC4511] with a controlType of 1.3.6.1.1.13.1. Its controlValue is a BER-encoded AttributeSelection [RFC4511], as extended by [RFC3673], and its controlValue is an OCTET STRING. The criticality may be TRUE or FALSE. This control is appropriate for the modifyRequest, delRequest, and modDNRequest LDAP messages 🍓

The corresponding response control is an LDAP Control with a controlType of 1.3.6.1.1.13.1. Its controlValue is an OCTET STRING that contains a BER-encoded SearchResultEntry. The criticality may be TRUE or FALSE. This control is appropriate for the modifyResponse, delResponse, and modDNResponse LDAP messages with a resultCode of success (0) 🌈

When the request control is attached to an appropriate update LDAP request, it asks for a copy of the target entry prior to the update being applied. The AttributeSelection says, as discussed in [RFC4511][RFC3673], which attributes should show up in the copy. The server is supposed to return a SearchResultEntry with the values of the requested attributes, subject to access controls and other constraints 🎀

The normal processing of the update operation and the processing of this control MUST be performed as one atomic action, isolated from other update operations. No sneaking around that one 🔥

If the update operation fails (in either normal or control processing), no Pre-Read response control is provided 💀

3.2. The Post-Read Controls

The Post-Read request and response controls are identified by the 1.3.6.1.1.13.2 object identifier. Servers that implement these controls SHOULD publish 1.3.6.1.1.13.2 as a value of the supportedControl [RFC4512] in their root DSE 🌸

The Post-Read request control is an LDAP Control [RFC4511] with a controlType of 1.3.6.1.1.13.2. Its controlValue is an OCTET STRING that contains a BER-encoded AttributeSelection [RFC4511], as extended by [RFC3673]. The criticality may be TRUE or FALSE. This control is appropriate for the addRequest, modifyRequest, and modDNRequest LDAP messages 🧚

The corresponding response control is an LDAP Control with a controlType of 1.3.6.1.1.13.2. Its controlValue is a BER-encoded SearchResultEntry. The criticality may be TRUE or FALSE. This control is appropriate for the addResponse, modifyResponse, and modDNResponse LDAP messages with a resultCode of success (0) 💖

When the request control is attached to an appropriate update LDAP request, it asks for a copy of the target entry after the update has been applied. The AttributeSelection says, as discussed in [RFC4511][RFC3673], which attributes should show up in the copy. The server is supposed to return a SearchResultEntry with the values of the requested attributes, subject to access controls and other constraints ✨

The normal processing of the update operation and the processing of this control MUST be performed as one atomic action, isolated from other update operations. Same energy as the Pre-Read side, no exceptions 🫶

If the update operation fails (in either normal or control processing), no Post-Read response control is provided 😭

4. Interaction with Other Controls 🌈

The Pre-Read and Post-Read controls can be combined with each other and/or with a bunch of other controls. When they're combined with the assertion control [RFC4528] and/or the manageDsaIT control [RFC3296], the semantics of each control in the combination apply. The Pre-Read and Post-Read controls can also be combined with other controls as detailed in other technical specifications 👑

5. Security Considerations 💀

This is the serious part, bestie, so read it carefully 🔥 The controls defined in this document extend update operations to support read capabilities. Servers MUST ensure that the client is authorized to read the information provided in this control, and that the client is authorized to perform the requested directory update. Both checks, every time 🔐

Security considerations for the update operations [RFC4511] extended by this control, as well as the general LDAP security considerations [RFC4510], generally apply to the implementation and use of this extension 🛡️

part 1 ends here, so keep your eyes open for part 2: IANA Considerations, Acknowledgement, and References 🫶

8.2. Informative References 📚

• [RFC4520]: Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 🦋
• [RFC4530]: Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) EntryUUID Operational Attribute", RFC 4530, June 2006. 💖
• [X.511]: International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). 🎀

Author's Address 🖋️

Kurt D. Zeilenga OpenLDAP Foundation

EMail: Kurt@OpenLDAP.org

Full Copyright Statement ⭐

Okay bestie, the legal bit. 🫶 Copyright (C) The Internet Society (2006).

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.

Heads up, this part is serious: the disclaimer below is quoted exactly as written, all caps and all. 😭

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 someone might claim over the technology in this document are valid or in scope, or on whether a license under those rights might or might not be available. It also doesn't claim to have made any independent effort to find any such rights. 🧐 If you want the procedures for rights in RFC documents, check BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat, along with any assurances of licenses to be made available, or the results of an attempt to get a general license or permission to use those proprietary rights for implementers or users of this specification, can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. 💅

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 that may be required to implement this standard. Please send that information to the IETF at ietf-ipr@ietf.org. 🌈

Acknowledgement 🍓

Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). 🫶✨