Personal Submission J. Sermersheim Internet Draft R. Harrison Document: draft-sermersheim-ldap-chaining-01.txt Novell, Inc Intended Category: Standard Track July 2001 LDAP Control to Specify Chaining Behavior 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. Discussion of this document should take place on the LDAP Extensions Working Group mailing list . Editorial comments may be sent to the author 2. Abstract This document describes an LDAP request and response control that allows specification of chaining behavior for LDAP operations. By using the control with various LDAP operations, a client specifies whether or not the LDAP server chains operations to other LDAP servers (or any other DSA for that matter) or returns referrals and search references to the client. 3. Overview Many directory servers have the ability through the use of various mechanisms to participate in a distributed directory model. A distributed directory is one where the DIB and/or the DIT is distributed over multiple DSAs. One mechanism used by DSAs in a distributed directory is chaining. Chaining is defined in [X.518], and is the act of one DSA communicating a directory operation that originated from a client to another DSA in a distributed directory. Contrast this with the act of passing referrals (4.1.11 of [RFC2251]) and SearchResultReferences (4.5.2 of [RFC2251]) back to the client. Chaining may happen during the name resolution part of Sermersheim, Harrison Internet-Draft - Exp. Jan 2002 Page 1 LDAP Control to Specify Chaining Behavior an operation, or during other operations like search that apply to a number of entries in a subtree. This document does not attempt to define the distributed directory model, nor does it attempt to define the manner in which DSAs chain requests. As such, the term chaining may apply to uni-chaining as well as multi-chaining (see [X.518]) depending on the capabilities and configuration of the DSAs. This document simply defines a request control that the client can use to specify whether an operation should or should not be chained. It also defines an associated response control. The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" used in this document carry the meanings described in [RFC2119]. 4. The Controls Support for the controls is advertised by the presence of their OIDs in the supportedControl attribute of a server's root DSE. The OID for the request control is and the OID for the response control is . 4.1 Request Control This control MAY be included in any LDAP request operation except abandon and unbind, as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [RFC2251]: The controlType is set to . The criticality MAY be set to either TRUE or FALSE. The controlValue is an OCTET STRING, whose value is the BER encoding of the following type: ChainingRequest ::= SEQUENCE { chainingOption ENUMERATED { chainingPreferred (0), chainingProhibited (1), chainingRequired (2), referralsPreferred (3) }, timeLimit INTEGER (0 .. maxInt) OPTIONAL } chainingPreferred indicates that the preference is that chaining, rather than referrals, be used to provide the service. When this value is set, the server SHOULD chain the request but is not required to do so. chainingProhibited indicates that chaining is prohibited. When this value is set, the server MUST NOT chain the request to other DSAs. Instead it returns referrals as necessary. Sermersheim, Harrison Internet-Draft - Exp. Jan 2002 Page 2 LDAP Control to Specify Chaining Behavior chainingRequired indicates that chaining is to be used rather than referrals to service the request. When this value is set, the server MUST chain the request rather than return referrals. referralsPreferred indicates that the client wishes to receive referrals rather than allow the server to chain the operation. When this value is set, the server SHOULD return referrals and search references when possible, but MAY chain the operation. timeLimit, if present, indicates the maximum time (in seconds) allowed for the operation. A value of zero in this field indicates that no client-requested time limit restrictions are in effect for the operation. 4.2 Response Control A response control is defined to convey operation completion information. This control is included in the final response message corresponding to the request operation that held the ChainingRequest control as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. The controlType is set to . The criticality is ignored. The controlValue is an OCTET STRING whose value is the BER encoding of the following SEQUENCE: ChainingResponse ::= SEQUENCE { chainingControlResult ENUMERATED { success (0), unwillingToPerform (53), chainingRequired (91), cannotChain (92) }, errorMessage [0] LDAPString OPTIONAL } A result field is provided here to allow the server to convey to the client that an error resulted due to the control being serviced. The following list explains the meanings of the result codes that may be returned in this control: - success The control was successful. - unwillingToPerform Server cannot process control. - chainingRequired Unable to process without chaining. - cannotChain Unable to chain the request. errorMessage MAY be populated with a human-readable string in the event of an erroneous result code. 5. Notes to Implementors Sermersheim, Harrison Internet-Draft - Exp. Jan 2002 Page 3 LDAP Control to Specify Chaining Behavior This control introduces the ability to specify a time limit for any operation other than Bind and Abandon. Clients MUST be aware that the use of this control could result in a timeLimitExceeded error to be returned on operations other than Search. 5.1 Unbind and Abandon Clients MUST NOT include the ChainingRequest control with an abandon operation or an unbind operation. Server implementors MUST ensure that the following scenarios will be properly handled regardless of the presence of a chaining control on the operations discussed: - Abandoned operations. If an operation that has been chained to another server is abandoned, the abandon operation MUST be chained to the proper server(s). - Unbind operation. If an unbind request is unbinding a previously chained bind, the server servicing the unbind request MUST ensure that the unbind is properly chained. Because there is no abandon or unbind response, thus no way to signal an error condition for the corresponding request, servers MUST ignore any chaining control on the abandon and unbind requests. 6. Relationship with other Extensions This control MAY be used with other controls or with extended operations. When it is used with other controls or with extended operations, server behavior is undefined unless otherwise specified. 7. Security Considerations Because this control directs a DSA to chain requests to other DSAs, it may be used in a denial of service attack. Implementers should be cognizant of this possibility. 8. References [X.518] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 1993. [RFC2119] Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement Levels", Internet Draft, March 1997. Available as RFC2119. [RFC2251] Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Protocol (v3)", Internet Standard, December, 1997. Available as RFC2251. Sermersheim, Harrison Internet-Draft - Exp. Jan 2002 Page 4 LDAP Control to Specify Chaining Behavior 9. Authors' Addresses Jim Sermersheim Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA jimse@novell.com +1 801 861-3088 Roger Harrison Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA rharrison@novell.com +1 801 861-2642 Sermersheim, Harrison Internet-Draft - Exp. Jan 2002 Page 5