INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track OpenLDAP Foundation Expires in six months 3 May 2003 LDAP: Grouping of Related Operations Status of Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. This document is intended to be, after appropriate review and revision, submitted to the RFC Editor as a Standard Track document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extension Working Group mailing list . Please send editorial comments directly to the author . Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' The list of current Internet-Drafts can be accessed at . The list of Internet-Draft Shadow Directories can be accessed at . Copyright 2003, The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. Abstract This document provides a general mechanism for grouping related Lightweight Directory Access Protocol (LDAP) operations. Grouping of operations can be used to support replication, proxies, and transactions. Zeilenga LDAP Grouping [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 Conventions Schema definitions are provided using LDAP description formats [RFC2252]. Definitions provided here are formatted (line wrapped) for readability. Protocol elements are described using ASN.1 [X.680]. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC2251]. 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 BCP 14 [RFC2119]. 1. Introduction This document provides a general mechanism for grouping related Lightweight Directory Access Protocol (LDAP) [RFC3377] operations. Grouping of operations can be used to support replication, proxies, and high level operations such as transactions [TXNGRP]. This document describes a set of LDAP extended operations [RFC2251] and other protocol and schema elements to support grouping of related operations. Uses of this grouping mechanism will be detailed in separate documents. A group of operations is defined as a set of operations within a common session identified by a unique cookie. All requests which are initiated with the same cookie belong to the same grouping. The cookie is obtained using the create group operation and is normally valid until the end group operation is completed. A group can end prematurely as described below. Operations can be intermixed regardless of their grouping (or lack of grouping). Groups can be nested. Each group is of a particular type specified when the group is created. This type defines the semantics of the group. 2. Protocol Elements This document describes three extended operations, two unsolicited notification, and one control. Extended operations and controls are described by LDAP [RFC2251] and provide here for convenience: Zeilenga LDAP Grouping [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS of LDAPResult, responseName [10] LDAPOID OPTIONAL, response [11] OCTET STRING OPTIONAL } Control ::= SEQUENCE { controlType LDAPOID, criticality BOOLEAN DEFAULT FALSE, controlValue OCTET STRING OPTIONAL } 2.1 Common Protocol Elements groupCookie ::= OCTET STRING A groupCookie is an octet string used to uniquely identify a grouping of related operations within the session. A groupCookie is a notational convenience. 2.2 Create Grouping Operation The Create Grouping extended operation is used to create or start a grouping of related operations. The operation consists of the createGroupingRequest and the createGroupingResponse. The object identifier createGroupingOID identifies this operation and SHOULD be listed as a value of supportedExtension in the root DSE of servers which support this operation. createGroupingOID ::= "IANA-ASSIGNED-OID.1" 2.2.1 createGroupingRequest The client initiates this operation by sending a createGroupingRequest. This request is an ExtendedRequest where the requestName is the object identifier createGroupOID and requestValue is BER-encoded createGroupingRequestValue: createGroupingRequestValue ::= SEQUENCE { createGroupType [0] LDAPOID, Zeilenga LDAP Grouping [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 createGroupValue [1] OCTET STRING OPTIONAL } where createGroupType is an object identifier that describes the specific type of grouping and createGroupValue contains a type specific payload. 2.2.2 createGroupingResponse The createGroupingResponse is sent in response to a createGroupingRequest. This response is an ExtendedResponse where the responseName MUST be the value of the requestName provided in the request and the response is a BER-encoded createGroupingResponseValue: createGroupingResponseValue ::= SEQUENCE { createGroupCookie [0] groupCookie OPTIONAL, createGroupValue [1] OCTET STRING OPTIONAL } where createGroupCookie, if present, is a cookie uniquely identifying the new grouping and createGroupValue is a type specific payload. The createGroupCookie only when the operation results in the creation of a group. Otherwise, it is absent. 2.3 End Grouping Operation The End Grouping extended operation is used to end or stop a grouping of related operations. The operation consists of the endGroupingRequest and the endGroupingResponse. The object identifier endGroupingOID identifies this operation and SHOULD be listed as a value of supportedExtension in the root DSE of servers which support this operation. endGroupingOID ::= "IANA-ASSIGNED-OID.2" 2.3.1 endGroupingRequest The client initiates this operation by sending an endGroupingRequest. This request is an ExtendedRequest where the requestName is the object identifier endGroupOID and requestValue is BER-encoded endGroupingRequestValue: endGroupingRequestValue ::= SEQUENCE { endGroupCookie [0] groupCookie, endGroupValue [1] OCTET STRING OPTIONAL Zeilenga LDAP Grouping [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 } where endGroupCookie is a cookie identifying the grouping and endGroupValue contains a type specific payload. 2.3.2 endGroupingResponse The endGroupingResponse is sent in response to a endGroupingRequest. This response is an ExtendedResponse where the responseName MUST be the value of the requestName provided in request and the response is a BER-encoded endGroupingResponseValue: endGroupingResponseValue ::= SEQUENCE { endGroupValue [1] OCTET STRING OPTIONAL } where endGroupValue is a type specific payload. 2.4 endGroupingNotice The endGroupingNotice is an LDAP unsolicited notification. The notification may be sent to the client to end a grouping which the server is unable or unwilling to continue to process. The notice is an extendedResponse where the responseName is the object identifier endGroupingNoticeOID and the response is a BER-encoded endGroupingNoticeValue: endGroupingNoticeOID ::= "IANA-ASSIGNED-OID.3" endGroupingNoticeValue ::= SEQUENCE { endGroupingCookie [0] groupCookie, endGroupValue [1] OCTET STRING OPTIONAL } where endGroupingCookie is a cookie uniquely identifying the grouping and endGroupValue contains a type specific payload. 2.5 Action Grouping Operation The Action Grouping extended operation is used to take an action affecting a grouping of related operations. The operation consists of the actionGroupingRequest and the actionGroupingResponse. The object identifier actionGroupingOID identifies this operation and SHOULD be listed as a value of supportedExtension in the root DSE of servers which support this operation. Zeilenga LDAP Grouping [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 actionGroupingOID ::= "IANA-ASSIGNED-OID.4" 2.5.1 actionGroupingRequest The client initiates this operation by sending an actionGroupingRequest. This request is an ExtendedRequest where the requestName is the object identifier actionGroupOID and requestValue is BER-encoded actionGroupingRequestValue: actionGroupingRequestValue ::= SEQUENCE { actionGroupCookie [0] groupCookie, actionGroupValue [1] OCTET STRING OPTIONAL } where actionGroupCookie is a cookie identifying the grouping and actionGroupValue contains a type specific payload. 2.5.2 actionGroupingResponse The actionGroupingResponse is sent in response to a actionGroupingRequest. This response is an ExtendedResponse where the responseName MUST be the value of the requestName provided in request and the response is a BER-encoded actionGroupingResponseValue: actionGroupingResponseValue ::= SEQUENCE { actionGroupValue [1] OCTET STRING OPTIONAL } where actionGroupValue is a type specific payload. 2.6 infoGroupingNotice The infoGroupingNotice is an LDAP unsolicited notification. The notice may be sent to the client to provide additional grouping type specific information. The notice is an extendedResponse where the responseName is the object identifier infoGroupingNoticeOID and the response is a BER-encoded infoGroupingNoticeValue: infoGroupingNoticeOID ::= "IANA-ASSIGNED-OID.5" infoGroupingNoticeValue ::= SEQUENCE { infoGroupingCookie [0] groupCookie, infoGroupValue [1] OCTET STRING OPTIONAL } Zeilenga LDAP Grouping [Page 6] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 where infoGroupingCookie is a cookie uniquely identifying the grouping and infoGroupValue contains a type specific payload. 2.7 groupingControl The groupingControl is used to identify requests and responses as belonging to a grouping of operations. The groupingControl is a Control where the controlType is the object identifier groupingControlOID, the criticality is TRUE, and the controlValue is a BER-encoded groupingControlValue: groupingControlOID ::= "IANA-ASSIGNED-OID.6" groupingControlValue ::= SEQUENCE { groupingCookie [0] groupCookie, groupValue [1] OCTET STRING OPTIONAL } where groupingCookie is a cookie uniquely identifying the grouping and groupingValue contains a type specific payload. The value groupingControlOID SHOULD be listed as a value of supportedControl in the root DSE by servers which support this control. The control SHALL NOT appear multiple times in the same LDAP PDU. If multiple occurrences of the control are detected, the PDU SHALL be treated as a protocol error. 3. Schema Elements The document describes one attribute type. 3.1. supportedGroupingTypes Servers SHOULD publish grouping types they support listing group type object identifiers as values of the supportedGroupingTypes attribute type in the root DSE. The supportedGroupingTypes attribute type is defined as: ( IANA-ASSIGNED-OID.7 NAME 'supportedGroupingTypes' DESC 'supported types of groupings of operations' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) Zeilenga LDAP Grouping [Page 7] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 The objectIdentifierMatch and OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) are defined in [RFC2252]. Servers MUST be capable of recognizing this attribute type by the name 'supportedGroupingTypes'. Servers MAY recognize the attribute type by other names. 4. Operational Semantics This section details the common semantics of groups of related operations. Additional semantics may be associated with each grouping type as described by other documents. 4.1 Grouping Semantics This subsection details semantics of the protocol elements introduced in Section 2. 4.1.1 Create Grouping To group related operations, the client MUST request a groupCookie from the server by sending a createGroupingRequest as described in Section 2.2.1. The client SHALL provide type specific payload in createGroupValue if so required by the grouping type. The server SHALL respond with a createGroupingResponse as described in Section 2.2.2. If the server is willing and able to create the grouping as requested (and per type requirements), it SHALL respond with success, provide a session-unique groupCookie and, if appropriate, a type specific payload. Otherwise the server SHALL respond with a non-successful response containing no groupCookie, but MAY, if appropriate, provide a type specific payload. 4.1.2 End Grouping When the client wishes to end the grouping, the client SHALL send a endGroupingRequest as described in Section 2.3.1. The client SHALL provide the groupCookie of the grouping to end and MAY provided a type specific payload. If the grouping to end contains active nested groupings, these are implicitly ended as well without notice. The server SHALL respond with an endGroupingResponse as described in Section 2.3.2. Zeilenga LDAP Grouping [Page 8] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 4.1.3 End Group Notice The server MAY end a group without solicitation for any reason. The server SHALL notify the client of this action by sending a endGrouping Notice, as described in Section 2.4. The server SHALL provide the groupCookie of the group it terminated and MAY provide a type specific payload. The notice SHALL have a non-success resultCode. If the group contains nested groups, the nested groups are implicitly ended as well without additional notice. 4.1.4 Action Grouping To perform an action within a group of related operations, the client sends to the server actionGroupingRequest as described in Section 2.5.1. The client SHALL provide the groupCookie of the group the operation is requested upon and, if required by the grouping type, a type specific payload. The server SHALL respond with a actionGroupingResponse as described in Section 2.5.2. The server SHALL, if required by the grouping type, provide type specific payload. 4.1.5 Info Grouping Notice As allowed by the grouping type, the server MAY provide to the client a notice regarding the grouping of related operations in an infoGroupingNotice as described in Section 2.6. The server SHALL, if required by the grouping type, provide type specific payload. 4.2 Nested groupings Groups of the same or different types MAY be nested. A nested group is instantiated by providing a groupingControl containing the parent group's cookie with the createGroupingRequest. Group type specifications MAY restrict the types of groupings which may be nested. Servers MAY also place additional restrictions upon nesting. Clients SHOULD NOT assume support for arbitrary nesting. 4.3 Intermixing of unrelated operations LDAP is designed to allow clients to perform unrelated tasks concurrently. In keeping with this design, operations which unrelated Zeilenga LDAP Grouping [Page 9] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 to the grouping are generally allowed be intermixed with grouped operations. (See Section 4.5 for specific exceptions to this general rule.) It is noted that undue restrictions often unrelated operation cause unnecessary serialization of independent tasks, place unnecessary burden upon implementors, and can limit extensibility. Group type specifications SHOULD NOT disallow unrelated operations from being intermixed with grouped operations. Note: a grouping which disallows unrelated operatoins from being intermixed with grouped operations can be viewed as providing "framing" semantics. 4.4 Grouped operations Interrogation (compare, search) and update (add, delete, modify, rename) MAY be grouped. Certain extended operations MAY also be grouped, but those which affect the session as a whole, such as Start TLS, MUST NOT be grouped. Requests and Responses associated with grouped operations contain a groupingControl control as described in Section 2.7. Group type specifications MAY restrict the kind and/or number of operations which may be related. Servers MAY place additional restrictions upon groupings. Clients SHOULD NOT assume support for arbitrary grouping. 4.5 Other Operations Upon issuing any grouping operation, the semantics of following operations listed is modified as described below. 4.5.1 abandon The abandon operation SHOULD NOT be used to cancel grouped operations. The Cancel operation is to be used instead (as discussed in 4.5.3). 4.5.2 bind The client SHOULD end all outstanding groupings before issuing a bind request. The server SHALL, in addition to the behavior described in [RFC2251] and [RFC2829], abandon all outstanding groups. No endGroupingNotice notification is sent upon such abandonment. Zeilenga LDAP Grouping [Page 10] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 A Bind operation cannot be related to other operations using this grouping mechanism. The bind messages SHOULD NOT contain groupingControl controls and, if present, SHALL be treated as a a protocol error. 4.5.3 cancel The cancel operation [CANCEL] MAY be used to cancel grouped operations but SHOULD NOT contain a groupingControl control unless the group type calls for a type specific payload to be provided. The groupingCookie in the provided groupingControl control MUST be the same associated with the operation to be canceled, otherwise the cancel request SHALL be treated as an error. 4.5.4 Start TLS The client SHOULD end all outstanding groupings before issuing a Start TLS [RFC2930] request. If there are any outstanding groupings, the server MUST return operationsError in response to a StartTLS request. Start TLS operation cannot be related to other operations using this grouping mechanism and the Start TLS request and response PDUs SHALL NOT contain a groupingControl control. 4.5.5 unbind The server SHALL, in addition to the behavior described in [RFC2251], abandon all outstanding groups. No endGroupingNotice is sent upon such abandonment. An unbind operation cannot be related to other operations using this grouping mechanism. The unbind request SHOULD NOT contain a groupingControl control and, if present, SHALL be ignored. 5. Profiling Requirements Documents detailing extensions using the grouping mechanism MUST provide a profile of its use of the mechanism. The profile SHALL specify the object identifier to be used to uniquely identify each grouping type it defines. Object identifiers used to identity group types, like other protocol elements, SHALL be delegated in accordance with BCP 64 [RFC3383] and registered as LDAP Protocol Mechanisms [RFC3383] as detailed in Section 7.1 of this document. The profile SHALL state which protocol elements of the mechanism it Zeilenga LDAP Grouping [Page 11] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 uses. Each of the grouping protocol elements defined in this document allow transfer of type specific payloads. For each protocol element used, the profile SHALL state whether the element is to carry a type specific payload or not and SHALL fully describe the syntax and semantics associated with each type specific payload. The profile MAY define grouping type specific semantics which place further restrictions upon the grouping related operations. 6. Security Considerations This mechanism can be used to support complex groupings of related operations. With such complexity comes inherit risk. Specifications of uses of this mechanism should take special care to address security issues. In particular, denial of service and authentication, authorization, and access-control issues should be addressed in documents detailing uses of this grouping mechanism. 7. IANA Considerations 7.1. Future Registration of Grouping Types Future specifications which detail LDAP grouping types are to register each grouping type as a LDAP Protocol Mechanism per guidance given in BCP 64 [RFC3383]. A usage of "Grouping Type" in a Protocol Mechanism registration template indicates that the value to be registered is associated with an LDAP Grouping Type. 7.2. Object Identifier Registration It is requested that IANA register upon Standards Action an LDAP Object Identifier to identify protocol elements defined in this technical specification. The following registration template is suggested: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Kurt Zeilenga Specification: RFCXXXX Author/Change Controller: IESG Comments: Identifies elements of the LDAP Grouping Operation Zeilenga LDAP Grouping [Page 12] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 7.3. LDAP Protocol Mechanism It is requested that IANA register upon Standards Action the LDAP protocol mechanism described in this document. The following registration template is suggested: Subject: Request for LDAP Protocol Mechansism Registration Object Identifier: IANA-ASSIGNED-OID Description: See comments Person & email address to contact for further information: Kurt Zeilenga Usage: Extended Operation Specification: RFCXXXX Author/Change Controller: IESG Comments: none Object Identifier Type Description ------------------- ---- ------------------------- IANA-ASSIGNED-OID.1 E Create Grouping Operation IANA-ASSIGNED-OID.2 E End Grouping Operation IANA-ASSIGNED-OID.4 E Action Grouping Operation in 2 7.4. supportedGroupingTypes Registration It is requested that IANA register upon Standards Action the LDAP 'supportedGroupingTypes' descriptor. The following registration template is suggested: Subject: Request for LDAP Descriptor Registration Descriptor (short name): supportedGroupingTypes Object Identifier: IANA-ASSIGNED-OID.7 Person & email address to contact for further information: Kurt Zeilenga Usage: Attribute Type Specification: RFCXXXX Author/Change Controller: IESG 8. Acknowledgments The author gratefully acknowledges the contributions of the IETF LDAPext and LDUP working groups. In particular, Roger Harrison provided many useful suggestions. Also, the author notes that this document builds upon the early works "Extended Operations for Framing LDAP Operations" by Ellen Stokes, Roger Harrison, and Gordon Good and Zeilenga LDAP Grouping [Page 13] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 "Profile for Framing LDAPv3 Operations" by Roger Harrison. 9. Author's Address Kurt D. Zeilenga OpenLDAP Foundation 10. References 10.1 Normative References [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14 (also RFC 2119), March 1997. [RFC2251] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [RFC2829] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [RFC3377] J. Hodges, R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 (also RFC 3383), September 2002. [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680, 1994. [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules", X.690, 1994. 10.2. Informative References [TXNGRP] K. Zeilenga, "LDAP Transactions" (a work in progress), Zeilenga LDAP Grouping [Page 14] INTERNET-DRAFT draft-zeilenga-ldap-grouping-06 3 May 2003 draft-zeilenga-ldap-txn-xx.txt. Copyright 2003, The Internet Society. 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 AUTHORS, 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. Zeilenga LDAP Grouping [Page 15]