INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track OpenLDAP Foundation Expires: 20 May 2002 20 November 2001 LDAPv3: 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 2001, 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 LDAP operations. Grouping of operations can be used to support replication, proxies, and high level operations such as transactions. Zeilenga LDAP Grouping [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 Conventions Schema definitions are provided using LDAPv3 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 "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be interpreted as described in BCP 14 [RFC2119]. 1. Introduction This document provides a general mechanism for grouping related LDAP [RFC2251] operations. Grouping of operations can be used to support replication, proxies, and high level operations such as transactions. This document describes a set of LDAP extended operations and other protocol and schema elements to support grouping of related operations. Uses of this grouping mechanism will be detailed in separate documents (e.g. LDAP Transactions [TRANSGRP], LDAP Proxy Group [PROXYGRP). 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 be ended by a server 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. This type defines the semantics of the group and is specified when the group is created. 2. Protocol Elements This document describes two extended operations, one unsolicited notification, and one control. Extended operations and controls are described by LDAP [RFC2251] as follows: Zeilenga LDAP Grouping [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 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 } Editor's Note: The object identifiers appearing in this document are fictious. Actual OIDs will be assigned before this document is progressed. 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 createGrouping Operation The createGrouping 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 ::= "1.1.1" 2.2.1 createGroupingRequest The client initiates this operation by sending a createGroupingRequest. This request is an ExtendedRequest where the Zeilenga LDAP Grouping [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 requestName is the object identifier createGroupOID and requestValue is BER-encoded createGroupingRequestValue: createGroupingRequestValue ::= SEQUENCE { createGroupType [0] LDAPOID, 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 endGrouping Operation The endGrouping 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 ::= "1.1.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 Zeilenga LDAP Grouping [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 endGroupingRequestValue: endGroupingRequestValue ::= SEQUENCE { endGroupCookie [0] groupCookie, endGroupValue [1] OCTET STRING OPTIONAL } 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 ::= "1.1.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 groupingControl The groupingControl is used to identify requests and responses as Zeilenga LDAP Grouping [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 belonging to a grouping of operations. The groupingControl is a Control where the controlType is the object identifier groupingControlOID and the criticalValue is a BER-encoded groupingControlValue: groupingControlOID ::= "1.1.4" groupingControlValue ::= SEQUENCE { groupingCookie [0] groupCookie, groupValue [1] OCTET STRING OPTIONAL } where groupingCookie is a cookie uniquely identifying the grouping, the criticality field is TRUE, 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 supportedGroupingType attribute type in the root DSE. The supportedGroupingTypes attribute type is defined as: ( 1.1.5 NAME 'supportedGroupingTypes' DESC 'supported types of groupings of operations' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 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 Zeilenga LDAP Grouping [Page 6] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 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 3. 4.1.1 createGrouping 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 endGrouping 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 be ended and MAY provided a type specific payload. If the grouping to be ended contained 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. 4.1.3 endGroupNotice 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. Zeilenga LDAP Grouping [Page 7] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 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 specifically designed to allow clients to perform unrelated tasks concurrently. Likewise, operations which unrelated to the grouping are generally allowed be intermixed with grouped operations. (See Section 4.3 for specific exceptions to this general rule). It also 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 from being intermixed with grouped operation 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.5. 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. Zeilenga LDAP Grouping [Page 8] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 4.5.1 abandon The abandon operation 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 abandon request SHALL be ignored. 4.5.1 bind The client SHOULD end all outstanding groupings before issuing a bind request. The server SHALL, in addition to the LDAPv3 behavior [RFC2251][RFC2829], abandon all outstanding groups. No endGroupingNotice notification is sent upon such abandonment. 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.2 unbind The server SHALL, in addition to the LDAPv3 behavior [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. 4.5.3 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. 5. Profiling Requirements Documents detailing extensions using the grouping mechanism MUST provide a profile of its use of the mechanism. Zeilenga LDAP Grouping [Page 9] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 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 [LDAPIANA]. The profile SHALL state which protocol elements of the mechanism it uses. Each of the grouping protocol elements defined in this document allow transfer of type specific payloads. For each protocol element, the profile SHALL state whether the element is to carry a type specific payload or not and MUST fully specify 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/access-control issues should be addressed in documents detailing uses of this grouping mechanism. 7. Acknowledgments The author gratefully acknowledges the contributions of the IETF LDAPext and LDUP working groups, in particular Roger Harrison who provided many useful suggestions. Also, the author notes that this document builds upon the early work "Extended Operations for Framing LDAP Operations" by Ellen Stokes, Roger Harrison, and Gordon Good. 8. Author's Address Kurt D. Zeilenga OpenLDAP Foundation 9. References 9.1 Normative References Zeilenga LDAP Grouping [Page 10] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 [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. [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. [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. [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf- ldapbis-xx.txt, a work in progress. 9.2. Informative References [PROXYGRP] K. Zeilenga, "LDAP Proxy Group" (a work in progress), draft-zeilenga-ldap-proxy-grp-xx.txt. [TRANSGRP] K. Zeilenga, "LDAP Transactions" (a work in progress) draft-zeilenga-ldap-txn-xx.txt. Copyright 2001, 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 Zeilenga LDAP Grouping [Page 11] INTERNET-DRAFT draft-zeilenga-ldap-grouping-03 20 November 2001 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 12]