INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track OpenLDAP Foundation Expires: 19 April 2001 19 October 2000 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 http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright 2000, The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. 1. Abstract This document provides a general mechanism for grouping related LDAP operations. Grouping of operations may be used to support replication, proxies, and higher level operations such as transactions. This document describes a set of LDAP [RFC2251] 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 [LDAPT]). Zeilenga [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 2. Overview A group of operations is defined as a set of operations upon a common session identified by a unique cookie. All requests which are initiated with the same cookie belong to same grouping. The cookie is obtained using the create group operation and is normally valid until the end group operation is issued. A group may be ended by a server prematurely as described below. Operations may be intermixed regardless of their grouping (or lack of grouping). Groups may 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. 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 [RFC2119]. 3. 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: 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: OID which appear in this document are fictious. Actual OIDs will be assigned before this document is progressed. Zeilenga [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 3.1 Common Protocol Elements groupCookie :== OCTET STRING A groupCookie is an octet string uniquely identify a grouping of related operations within the session. A groupCookie is a notational convenience. 3.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 OID 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" 3.2.1 createGroupingRequest The client initiates this operation by sending a createGroupingRequest. This request is an ExtendedRequest where the requestName is the value createGroupOID and requestValue is BER encoded createGroupingRequestValue createGroupingRequestValue ::= SEQUENCE { createGroupType [0] LDAPOID, createGroupValue [1] OCTET STRING OPTIONAL } where createGroupType is an OID that describes the specific type of grouping and createGroupValue contains a type specific payload. 3.2.1 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 request and the response is a BER encoded createGroupingResponseValue. createGroupingResponseValue ::= SEQUENCE { createGroupCookie [0] groupCookie, Zeilenga [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 createGroupValue [1] OCTET STRING OPTIONAL } where createGroupCookie is a cookie uniquely identifying the grouping and createGroupValue is a type specific payload. 3.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 OID 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" 3.3.1 endGroupingRequest The client initiates this operation by sending an endGroupingRequest. This request is an ExtendedRequest where the requestName is the value endGroupOID and requestValue is BER encoded endGroupingRequestValue endGroupingRequestValue ::= SEQUENCE { endGroupCookie [0] groupCookie, endGroupValue [1] OCTET STRING OPTIONAL } where endGroupCookie is an cookie identifying the grouping and endGroupValue contains a type specific payload. 3.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. Zeilenga [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 3.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 OID endGroupingNoticeOID and the response is a BER encoded endGroupingNoticeValue endGroupingNoticeOID ::= "1.1.3" endGroupingNoticeValue ::= SEQUENCE { endGroupingCookie [0] groupCookie, groupValue [1] OCTET STRING OPTIONAL } where endGroupingCookie is a cookie uniquely identifying the grouping and groupingValue contains a type specific payload. 3.5 groupingControl The groupingControl is used to identify requests and responses as belonging to grouping of operations. The groupingControl is a Control where the controlType is the OID 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 critical is TRUE, and groupingValue contains a type specific payload. The value groupingControlOID MAY be listed as a value of supportedControls 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 MUST be treated as a protocol error. 4. Schema Elements Zeilenga [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 The document describes one attribute type. 4.1. supportedGroupingTypes Servers SHOULD publish grouping types they support listing their OID as values of the supportedGrouping attribute type in the root DSE. The supportedGrouping attribute type is defined as: ( 1.1.5 NAME 'supportedGroupingTypes' DESC 'supported types of groupings of operations' EQUALITY objectIdentifierMatch SYNTAX ObjectIdentifierSyntax ) 5. 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. 5.1 Grouping Semantics This subsection details semantics of the protocol elements introduced in section 4. 5.1.1 createGrouping To group related operations, the client MUST request a groupCookie from the server by sending a createGroupingRequest as described in 3.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 3.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 and provide no groupCookie, but MAY, if appropriate, provide a type specific payload. 5.1.2 endGrouping When the client wishes to end the grouping, the client SHALL send a endGroupingRequest as described in 3.3.1. The client SHALL provide Zeilenga [Page 6] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 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 ended as well. The server SHALL respond with an endGroupingResponse as described in 3.3.2. 5.1.3 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. 5.1.3 endGroupNotice The server MAY end a group without solicitation for any reason but MUST send a endGrouping Notice, as described in 3.4, indicating this action. 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 ended as well. 5.2 Grouped operations Introgration (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 3.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. 5.3 Other Operations Upon issuing of any grouping operation, semantics of following Zeilenga [Page 7] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 operations listed is modified as described below. 5.3.1 abandon The abandon operation MAY be used to cancel grouped operations but SHOULD NOT contain a groupingControl control. 5.3.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. Bind operation cannot be related to other operations using this grouping mechanism and Bind PDU SHALL NOT contain a groupingControl control. 5.3.2 unbind The server SHALL, in addition to the LDAPv3 behavior [RFC2251], abandon all outstanding groups. No endGroupingNotice is sent upon such abandonment. Unbind operation cannot be related to other operations using this grouping mechanism. The unbind request SHOULD NOT contain groupingControl control and, if present, SHALL be ignored. 5.3.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. 6. Security Considerations This mechanism may 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. Zeilenga [Page 8] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 7. References [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Levels", Harvard University, 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. [LDAPT] K. Zeilenga, "LDAP Transactions" (a work in progress), draft-zeilenga-ldap-txn-xx.txt. 8. Acknowledgments The author gratefully acknowledge the contributions of the IETF LDUP and LDAPext working group. 9. Additional Information Discussions regarding these suggestions may directed to the author: Kurt D. Zeilenga OpenLDAP Foundation or the LDAPext Working Group mailing list: Copyright 2000, 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 Zeilenga [Page 9] INTERNET-DRAFT draft-zeilenga-ldap-grouping-01 19 October 2000 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 [Page 10]