git.sur5r.net Git - openldap/blob - doc/drafts/draft-zeilenga-ldap-grouping-xx.txt

   1
   2
   3
   4
   5
   6
   7 INTERNET-DRAFT                                      Kurt D. Zeilenga
   8 Intended Category: Standard Track                   OpenLDAP Foundation
   9 Expires: 4 January 2001                             4 July 2000
  10
  11
  12                   LDAPv3: Grouping of Related Operations
  13                   <draft-zeilenga-ldap-grouping-00.txt>
  14
  15
  16 Status of Memo
  17
  18   This document is an Internet-Draft and is in full conformance with all
  19   provisions of Section 10 of RFC2026.
  20
  21   This document is intended to be, after appropriate review and
  22   revision, submitted to the RFC Editor as a Standard Track document.
  23   Distribution of this memo is unlimited.  Technical discussion of this
  24   document will take place on the IETF LDAP Extension Working Group
  25   mailing list <ietf-ldapext@netscape.com>.  Please send editorial
  26   comments directly to the author <Kurt@OpenLDAP.org>.
  27
  28   Internet-Drafts are working documents of the Internet Engineering Task
  29   Force (IETF), its areas, and its working groups.  Note that other
  30   groups may also distribute working documents as Internet-Drafts.
  31   Internet-Drafts are draft documents valid for a maximum of six months
  32   and may be updated, replaced, or obsoleted by other documents at any
  33   time.  It is inappropriate to use Internet-Drafts as reference
  34   material or to cite them other than as ``work in progress.''
  35
  36   The list of current Internet-Drafts can be accessed at
  37   http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft
  38   Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
  39
  40   Copyright 2000, The Internet Society.  All Rights Reserved.
  41
  42   Please see the Copyright section near the end of this document for
  43   more information.
  44
  45
  46 1. Abstract
  47
  48   This document provides a general mechanisms for grouping related LDAP
  49   operations.  Grouping of operations may be used to support
  50   replication, proxies, and higher level operations such as
  51   transactions.  This document describes a set of LDAP [RFC2251]
  52   extended operations and other protocol and schema elements to support
  53   grouping of related operations.
  54
  55
  56
  57
  58 Zeilenga                                                        [Page 1]
  59 \f
  60 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
  61
  62
  63 2. Overview
  64
  65   This document provides a mechanism to allow clients to group
  66   operations.
  67
  68   A group of operations is defined as a set of operations upon a common
  69   session identified by a unique cookie.  All requests which are
  70   initiated with the same cookie belong to same grouping.  The cookie is
  71   obtained using the create group operation and is normally valid until
  72   the end group operation is issued.  A group may be ended by a server
  73   prematurely as noted described below.
  74
  75   Operations regardless of their grouping (or lack of grouping) may be
  76   intermixed.  Groups may be nested.
  77
  78   Each group is of a particular type.  This type defines the semantics
  79   of the group and is specified when the group is created.
  80
  81   The key words "SHALL", "SHALL NOT", "MUST", "MUST NOT", "SHOULD",
  82   "SHOULD NOT", "MAY" and "MAY NOT" used in this document are to be
  83   interpreted as described in [RFC2119].
  84
  85
  86 3. Protocol Elements
  87
  88   This document describes two extended operations, one unsolicited
  89   notification, and one control.  Extended operations and controls are
  90   described by LDAP [RFC2251] as follows:
  91
  92     ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
  93       requestName    [0] LDAPOID,
  94       requestValue   [1] OCTET STRING OPTIONAL
  95     }
  96
  97     ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
  98       COMPONENTS of LDAPResult,
  99       responseName   [10] LDAPOID OPTIONAL,
 100       response       [11] OCTET STRING OPTIONAL
 101     }
 102
 103     Control ::= SEQUENCE {
 104       controlType    LDAPOID,
 105       criticality    BOOLEAN DEFAULT FALSE,
 106       controlValue   OCTET STRING OPTIONAL
 107     }
 108
 109
 110   Editor's Note:
 111
 112
 113
 114 Zeilenga                                                        [Page 2]
 115 \f
 116 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 117
 118
 119     OID which appear in this document are fictious.  Actual OIDs will be
 120     assigned before this document is progressed.
 121
 122 3.1 Common Protocol Elements
 123
 124     groupCookie :== OCTET STRING
 125
 126   A groupCookie is an arbitrary octet string uniquely identify a
 127   grouping of related operations within the session.
 128
 129   A groupCookie is a notational convenience.
 130
 131
 132
 133 3.2 createGrouping Operation
 134
 135   The createGrouping extended operation is used to create or start a
 136   grouping of related operations.  The operation consists of the
 137   createGroupingRequest and the createGroupingResponse.  The OID
 138   createGroupingOID identifies this operation and SHOULD be listed as a
 139   value of supportedExtensions in the root DSE of servers which support
 140   this operation.
 141
 142     createGroupingOID ::= "1.1.1"
 143
 144
 145 3.2.1 createGroupingRequest
 146
 147   The client initiates this operation by sending a
 148   createGroupingRequest.  This request is an ExtendedRequest where the
 149   requestName is the value createGroupOID and requestValue is BER
 150   encoded createGroupingRequestValue
 151
 152     createGroupingRequestValue ::= SEQUENCE {
 153       createGroupType     [0] LDAPOID,
 154       createGroupValue    [1] OCTET STRING OPTIONAL
 155     }
 156
 157   where createGroupType is an OID that describes the specific type of
 158   grouping and createGroupValue contains a type specific payload.
 159
 160
 161 3.2.1 createGroupingResponse
 162
 163   The createGroupingResponse is sent in response to a
 164   createGroupingRequest.  This response is an ExtendedResponse where the
 165   responseName MUST be the value of the requestName provided in request
 166   and the response is a BER encoded createGroupingResponseValue.
 167
 168
 169
 170 Zeilenga                                                        [Page 3]
 171 \f
 172 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 173
 174
 175     createGroupingResponseValue ::= SEQUENCE {
 176       createGroupCookie [0] groupCookie,
 177       createGroupValue  [1] OCTET STRING OPTIONAL
 178     }
 179
 180   where createGroupCookie is a cookie uniquely identifying the grouping
 181   and createGroupValue is a type specific payload.
 182
 183
 184 3.3 endGrouping Operation
 185
 186   The endGrouping extended operation is used to end or stop a grouping
 187   of related operations.  The operation consists of the
 188   endGroupingRequest and the endGroupingResponse.  The OID
 189   endGroupingOID identifies this operation and SHOULD be listed as a
 190   value of supportedExtensions in the root DSE of servers which support
 191   this operation.
 192
 193     endGroupingOID ::= "1.1.2"
 194
 195
 196 3.3.1 endGroupingRequest
 197
 198   The client initiates this operation by sending an endGroupingRequest.
 199   This request is an ExtendedRequest where the requestName is the value
 200   endGroupOID and requestValue is BER encoded endGroupingRequestValue
 201
 202     endGroupingRequestValue ::= SEQUENCE {
 203       endGroupCookie  [0] groupCookie,
 204       groupValue [1] OCTET STRING OPTIONAL
 205     }
 206
 207   where endGroupCookie is an cookie identifying the grouping and
 208   groupValue contains a type specific payload.
 209
 210
 211 3.3.2 endGroupingResponse
 212
 213   The endGroupingResponse is sent in response to a endGroupingRequest.
 214   This response is an ExtendedResponse where the responseName MUST be
 215   the value of the requestName provided in request and the response is a
 216   BER encoded endGroupingResponseValue
 217
 218     endGroupingResponseValue ::= SEQUENCE {
 219       groupValue  [1] OCTET STRING OPTIONAL
 220     }
 221
 222   where groupValue is a type specific payload.
 223
 224
 225
 226 Zeilenga                                                        [Page 4]
 227 \f
 228 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 229
 230
 231 3.4 endGroupingNotice
 232
 233   The endGroupingNotice is an LDAP unsolicited notification.  The
 234   notification may be sent to the client to end a grouping which the
 235   server is unable or unwilling to continue to process.  The notice is
 236   an extendedResponse where the responseName is the OID
 237   endGroupingNoticeOID and the response is a BER encoded
 238   endGroupingNoticeValue
 239
 240     endGroupingNoticeOID ::= "1.1.3"
 241
 242     endGroupingNoticeValue ::= SEQUENCE {
 243       endGroupingCookie [0] groupCookie,
 244       groupValue        [1] OCTET STRING OPTIONAL
 245     }
 246
 247   where endGroupingCookie is a cookie uniquely identifying the grouping
 248   and groupingValue contains a type specific payload.
 249
 250
 251 3.5 groupingControl
 252
 253   The groupingControl is used to identify requests and responses as
 254   belonging to grouping of operations.  The groupingControl is a Control
 255   where the controlType is the OID groupingControlOID and the
 256   criticalValue is a BER encoded groupingControlValue
 257
 258     groupingControlOID ::= "1.1.4"
 259
 260     groupingControlValue ::= SEQUENCE {
 261       groupingCookie   [0] groupCookie,
 262       groupValue       [1] OCTET STRING OPTIONAL
 263     }
 264
 265   where groupingCookie is a cookie uniquely identifying the grouping,
 266   the critical is TRUE, and groupingValue contains a type specific
 267   payload.
 268
 269   The value groupingControlOID SHOULD be listed as a value of
 270   supportedControls in the root DSE by servers which support this
 271   control.
 272
 273   The control MAY be present on add, compare, delete, moddn, modify, and
 274   search requests and responses.  The control SHALL NOT be present on a
 275   abandon, bind, unbind.  The control SHALL NOT be present on any
 276   extended operation which affects the behavior of the session such as
 277   the Start TLS [RFC2830] operation.  The control SHALL NOT be present
 278   if the operation includes any control which likewise causes the
 279
 280
 281
 282 Zeilenga                                                        [Page 5]
 283 \f
 284 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 285
 286
 287   operation to affects the behavior of the session.
 288
 289   The control SHALL NOT appear multiple times in the same LDAP PDU and.
 290   If multiple occurrences of the control are detected, the PDU MUST be
 291   treated as a protocol error.
 292
 293 4. Schema Elements
 294
 295 4.1. supportedGroupingTypes
 296
 297   Servers SHOULD publish grouping types they support listing their OID
 298   as values of the supportedGrouping attribute type in the root DSE.
 299   The supportedGrouping attribute type is defined as:
 300
 301     ( 1.1.5 NAME 'supportedGroupingTypes'
 302       DESC 'supported types of groupings of operations'
 303       EQUALITY objectIdentifierMatch
 304       SYNTAX ObjectIdentifierSyntax )
 305
 306
 307 5. Operational Semantics
 308
 309   This section needs work.
 310
 311
 312 5.1 Grouping Operations
 313
 314
 315 5.1.1 createGrouping
 316
 317   To group related operations, the client MUST request a groupCookie
 318   from the server by sending a createGroupingRequest as described in
 319   3.2.1.  The client SHALL provide type specific payload in
 320   createGroupValue if so required by the grouping type.
 321
 322   The server SHALL respond with a createGroupingResponse as described in
 323   3.2.2.  If the server is willing and able to create the grouping as
 324   requested (and per type requirements), it SHALL respond with success,
 325   provide a session-unique groupCookie and, if appropriate, a type
 326   specific payload.  Otherwise the server SHALL respond with a non-
 327   successful response and provide no groupCookie, but MAY, if
 328   appropriate, provide a type specific payload.
 329
 330
 331 5.1.2 endGrouping
 332
 333   When the client wishes to end the grouping, the client SHALL send a
 334   endGroupingRequest as described in 3.3.1.  The client SHALL provide
 335
 336
 337
 338 Zeilenga                                                        [Page 6]
 339 \f
 340 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 341
 342
 343   the groupCookie of the grouping to be ended and MAY provided a type
 344   specific payload.
 345
 346   The server SHALL respond with an endGroupingResponse as described in
 347   3.3.2.
 348
 349
 350 5.1.3 endGroupNotice
 351
 352   The server MAY end a group without solicitation for any reason but
 353   MUST send a endGrouping Notice, as described in 3.4, indicating this
 354   action.  The server SHALL provide the groupCookie of the group it
 355   terminated and MAY provide a type specific payload.  The notice SHALL
 356   have a non-success resultCode.
 357
 358
 359 5.1.4 grouped operations
 360
 361   Operations with a group are carry a groupingControl as described in
 362   3.5.
 363
 364   Group type specifications MAY restrict the types and/or number of
 365   operations which may be related.  Servers MAY also place restrictions
 366   upon groupings.  Clients SHOULD NOT assume arbitrary support for
 367   grouping.
 368
 369
 370 5.1.5 nested groupings
 371
 372   Groups of the same or different types may be nested.  A nested group
 373   is instantiated by providing a groupingControl containing the parent
 374   group with the createGroupingRequest.
 375
 376   Group type specifications MAY restrict the types of groupings which
 377   may be nested.  Servers MAY also place restrictions upon nesting.
 378   Clients SHOULD NOT assume arbitrary support for nesting.
 379
 380
 381 5.3 Other Operations
 382
 383   Upon issuing of any grouping operation, semantics of non-grouping
 384   operations listed is modified as described below.
 385
 386 5.3.1 bind
 387
 388   The client SHOULD end all outstanding groupings before issuing a bind
 389   request.
 390
 391
 392
 393
 394 Zeilenga                                                        [Page 7]
 395 \f
 396 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 397
 398
 399   The bind operation MUST, in addition to the behavior described in RFC
 400   2251, must abandon all outstanding groups.
 401
 402
 403 5.3.2 unbind
 404
 405   The unbind operation MUST, in addition to the behavior described in
 406   RFC 2251, must abandon all outstanding groups.
 407
 408
 409 5.3.3 Start TLS
 410
 411   The client SHALL end all outstanding groupings before issuing a Start
 412   TLS request.
 413
 414   The Start TLS operation MUST, in addition to the behavior described in
 415   RFC 2830, return operationsError if there are any outstanding
 416   groupings.
 417
 418
 419 7. Security Considerations
 420
 421   This mechanism may be used to support complex groupings of related
 422   operations for arbitrary purposes.  This document places no
 423   restrictions on how the grouped operations relate to each other.
 424
 425   It is conceived that different groups of operations may have different
 426   authorization and/or access controls associated with them (when used
 427   to multiplex proxied directory sessions).  Authors of specifications
 428   for such groupings take special care in addressing security issues.
 429
 430   It is conceived that different groups of operations may form complex
 431   super-operations such as transactions.  Authors of specifications for
 432   such groupings should take special care to address denial of service
 433   issues.
 434
 435
 436 8. References
 437
 438   [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate
 439             Requirement Levels", Harvard University, RFC 2119, March
 440             1997.
 441
 442   [RFC2251] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
 443             Protocol (v3)", RFC 2251, December 1997.
 444
 445
 446 9. Acknowledgments
 447
 448
 449
 450 Zeilenga                                                        [Page 8]
 451 \f
 452 INTERNET-DRAFT       draft-zeilenga-ldap-grouping-00         4 July 2000
 453
 454
 455   The author gratefully acknowledge the contributions of the IETF LDUP
 456   and LDAPext working group.
 457
 458
 459 10. Additional Information
 460
 461   Discussions regarding these suggestions may directed to the author:
 462
 463   Kurt D. Zeilenga
 464   OpenLDAP Foundation
 465   <Kurt@OpenLDAP.org>
 466
 467   or the LDAPext Working Group mailing list:
 468
 469   <ietf-ldapext@netscape.com>
 470
 471
 472 Copyright 2000, The Internet Society.  All Rights Reserved.
 473
 474   This document and translations of it may be copied and furnished
 475   to others, and derivative works that comment on or otherwise explain
 476   it or assist in its implementation may be prepared, copied, published
 477   and distributed, in whole or in part, without restriction of any
 478   kind, provided that the above copyright notice and this paragraph
 479   are included on all such copies and derivative works.  However,
 480   this document itself may not be modified in any way, such as by
 481   removing the copyright notice or references to the Internet Society
 482   or other Internet organizations, except as needed for the  purpose
 483   of developing Internet standards in which case the procedures for
 484   copyrights defined in the Internet Standards process must be
 485   followed, or as required to translate it into languages other than
 486   English.
 487
 488   The limited permissions granted above are perpetual and will not
 489   be revoked by the Internet Society or its successors or assigns.
 490
 491   This document and the information contained herein is provided on
 492   an "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE
 493   INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS
 494   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE
 495   OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
 496   IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
 497   PURPOSE.
 498
 499
 500
 501
 502
 503
 504
 505
 506 Zeilenga                                                        [Page 9]
 507 \f