INTERNET-DRAFT Kurt D. Zeilenga Intended Category: BCP OpenLDAP Foundation Expires: 20 June 2002 20 December 2001 Considerations for LDAP Extensions Status of this 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 Best Current Practices document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extensions 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 The Lightweight Directory Access Protocol (LDAP) is extensible. It provides mechanisms for adding new operations, extending existing operations, and defining operational and user applications schema. This document discusses considerations for designers of LDAP extensions. Zeilenga LDAP Extensions [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 Conventions 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]. The term "Request Control" refers to a control attached to client generated message sent to a server. The term "Response Control" refers to a control attached to server generated message sent to a client. 1. Background and Intended Use The Lightweight Directory Access Protocol (LDAP) [LDAPTS] is an extensible protocol. LDAP allows for new operations to be added and existing operations to be enhanced [RFC2251]. LDAP allows application schema to be defined [RFC2252]. This can include additional object classes, attribute types, matching rules, additional syntaxes, and other elements of schema. LDAP supports a Simple Authentication and Security Layer (SASL) authentication method [RFC2829]. SASL [RFC2222] is extensible. LDAP supports use of Transport Layer Security (TLS) [RFC2830]. TLS [RFC2246] is extensible. LDAP provides an ability to tag attribute types with options [RFC2251]. LDAP defines one option (";binary"), others can be defined other documents. LDAP has an extensible URL format [RFC2255]. Lastly, the protocol allows for certain extensions to the protocol's ASN.1 [X.680] definition to be made. This allows a wide range of changes. For example, new result codes needed to support extensions to be added. This document describes practices which engineers MUST consider when designing future extensions to LDAP. 2. General Considerations 2.1 Scope of Extension Zeilenga LDAP Extensions [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 Mutually agreeing peers MAY, within the confines of an extension, agree to significant changes in protocol semantics. Designers MUST consider the impact of the extension upon protocol peers which have not agreed to implement or otherwise recognize and support the extension. 2.2. Discovery Mechanism Extensions SHOULD provide an adequate discover mechanism. 2.3. Interaction between extensions Designers SHOULD consider how extensions they engineer interaction with other extensions. 2.4. Internationalization LDAP is designed to support the full ISO 10646-1 (a superset of Unicode) character set [ISOUCS]. Extensions SHOULD avoid unnecessarily restricting applications to subsets of ISO 10646-1 (e.g., Basic Multilingual Plane, ISO 8859-1, ASCII). 2.5. IANA Considerations Designers SHALL register protocol elements of their LDAP extensions in accordance with [LDAPIANA]. 2.5. Use of Formal Languages LDAP is described in terms of ASN.1 [X.680] and encoded using a particular subset [RFC2251, Section 5.1] of the Basic Encoding Rules [X.690]. To allow reuse of parsers/generators used in implementing the LDAP "core" technical specification [LDAPTS], it is generally RECOMMENDED that protocol elements (e.g. extension specific contains of controlValue, requestValue, response fields, and value syntax) specified by extensions be described and encoded similarly. Formal languages SHOULD be used in specifications in accordance with IESG guidelines [FORMAL]. 3. LDAP Operation Extensions Zeilenga LDAP Extensions [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 Extensions SHOULD use controls to define extensions which complement existing operations. Where the extension to be defined does not complement the existing operation, designers SHOULD consider defining an extended operation instead. For example, a subtree delete operation could be designed as either an extension of the delete operation or as a new operation. As the feature complements the existing delete operation, use of the control mechanism to extend the delete operation is likely more appropriate. As a counter (and contrived) example, a locate services [LOCATE] operation (an operation which would return for a DN a set of LDAP URLs which hold this DN) could be designed as either a search operation or a new operation. As the feature doesn't complement the search operation (the operation is not searching for information in the DIT but, say, information in the Domain Name System), use of the extended operation mechanism to define a new operation is likely more appropriate. 3.1. Controls Controls [RFC2251, Section 4.1.12] is the RECOMMENDED mechanism for extending existing operations. The existing operation can be a base operation defined in RFC 2251 (e.g., search, modify, etc.) or an extended operation (e.g. Start TLS, Password Modify), or a operation defined as an extension to a base or extended operation. Extensions SHOULD be designed such that Response controls are not provided to a client unless the server has specific knowledge that the client can make use of the control. Generally, the client requests the return of a particular response control by providing a related request control. An existing operation MAY be extended to return Intermediate Responses [LDAPIMR]. Specifications of controls SHALL NOT attach additional semantics to criticality of controls beyond those defined in RFC 2251, Section 4.1.12. A specification MAY mandate the criticality take on a particular value (e.g., TRUE or FALSE) where appropriate. 3.2. Extended Operations Extended Operations [RFC2251, Section 4.12] is the RECOMMENDED mechanism for defining new operations. An extended operation consists of an ExtendedRequest message, zero or more IntermediateResponse Zeilenga LDAP Extensions [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 messages [LDAPIMR], and an ExtendedResponse message. 3.3. Intermediate Responses Extensions SHALL use Intermediate Responses [LDAPIMR] instead of ExtendedResponse [RFC2251] messages to return partial results. 3.4. Unsolicited Notifications Unsolicited notifications [RFC2251, Section 4.4] offer a capability for the server to notify the client of events not associated with operation currently being processed. Extensions SHOULD be designed such that unsolicited notifications are not be returned unless the server has specific knowledge that the client can make use of the notification. Generally, the client requests the return of particular unsolicited notification by performing a related extended operation. For example, a time hack extension could be designed to return unsolicited notifications at regular intervals which were enabled by an extended operation (which possibly specified the desired interval). 4. Extending LDAPv3 ASN.1 definition LDAP allows limited extension of the LDAPv3 ASN.1 definition [RFC2251, Appendix A] to made. 4.1. Result Codes Extensions which specify new operations or enhance existing operations often need to define new result codes. The extension SHOULD be designed such that a client has a reasonably clear indication of the nature of the successful or non-successful result. Extensions SHOULD use existing result codes to indicate conditions which are consistent with each codes intended meaning [RFC2251][X.511]. Extensions MAY introduce new result codes where no existing result code provides an adequate indication of the nature of the result. Extersions SHALL NOT disallow nor otherwise restrict the return of general service result codes, especially those reporting a protocol, service, or security problem, indicating server is unable or unwilling Zeilenga LDAP Extensions [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 to complete the operation. 4.2. LDAP Message Types While extensions can specify new types of LDAP messages by extending the protocolOp CHOICE of the LDAPMessage SEQUENCE, this is generally unnecessary and inappropriate. Existing operation extension mechanisms (e.g., extended operations and unsolicited notifications) SHOULD be used instead. However, there may be cases where an extension does not fit well into these mechanisms. In such cases, a new extension mechanism SHOULD be defined which can be used by multiple extensions which have similar needs. 4.3. Authentication Methods The Bind operation currently supports two authentication methods, simple and SASL. SASL [RFC2222] is an extensible authentication framework used by multiple application level protocols (e.g. BEEP, SMTP, IMAP). It is RECOMMENDED that new authentication processes be defined as SASL mechanisms. New methods MAY be added to support new authentication frameworks. The Bind operation primary function is to establish the LDAP association [RFC2829]. No other operation SHALL be defined (or extended) to establish the LDAP association [RFC2829]. However, other operations MAY be defined to establish other security associations (e.g., IPSEC). 4.4. Elements of SEQUENCE extensions RFC 2251, Section 4 states: In order to support future extensions to this protocol, clients and servers MUST ignore elements of SEQUENCE encodings whose tags they do not recognize. This mechanism is NOT RECOMMENDED. 5. Schema Extensions Extensions defining LDAP schema elements SHALL provide schema definitions conformant with syntaxes defined in [RFC2252]. Definitions provided MAY be reformatted (line wrapped) for readability but this SHALL be noted in the extension specification. Zeilenga LDAP Extensions [Page 6] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 For definitions contain a NAME field, extensions defining new schema elements SHOULD provide one and only one name. The name SHOULD be short. For extensions which pre-exist, existing registered names [LDAPIANA] SHOULD be preserved. Unregistered names SHALL either be registered or not used in the definition of the extension. Each schema definition allows a DESC field. The DESC field, if provided, SHOULD contain a short descriptive phrase. The DESC field SHALL NOT contain information imperative to the implementor. That is, the interpretation of the specification SHALL NOT different if all DESC fields were removed from it. The extension SHALL NOT mandate that implementations provide the same DESC field in schema they publish. Implementators MAY replace or remove the DESC field. Published schema elements SHALL NOT be redefined. Replacement schema elements (new OIDs, new NAMEs) SHOULD be defined as needed. Schema designers SHOULD reuse existing schema elements where appropriate. 5.1. LDAP Syntaxes Each LDAP syntax is defined in terms of ASN.1 [X.680]. Each extension detailing an LDAP syntax MUST specify the ASN.1 data definition associated with the syntax. Each LDAP syntax SHOULD have a string encoding defined for it. It is RECOMMENDED that UTF-8 string encoding be defined. Use of string encoding rules (such as [GSER]) to provide UTF-8 string encodings for complex ASN.1 data definitions is RECOMMENDED. Otherwise, it is RECOMMENDED that the string encoding be described using a formal language (e.g., [ABNF]). Formal languages SHOULD be used in specifications in accordance with IESG guidelines [FORMAL]. If no string encoding is defined, the extension SHALL specify how the transfer encoding is to be indicated. Generally, the extension SHOULD mandate use of ;binary or other transfer encoding option. 5.2. Matching Rules Three basic kinds of matching rules (EQUALITY, ORDERING, and SUBSTRING) may be associated with an attribute type. In addition, LDAP provides an extensible matching rule mechanism. The matching rule specification SHOULD detail which kind of matching rule it is and SHOULD describe which kinds of values it can be used Zeilenga LDAP Extensions [Page 7] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 with. 5.3. Attribute Types Designers SHOULD carefully consider how the structure of values is to restricted. Designers SHOULD consider that servers will only enforce constraints of the attribute's syntax. Designers SHOULD carefully consider which matching rules, if any, are appropriate for the attribute type. Matching rules specified for an attribute type MUST be compatible with the attribute type's syntax. Extensions specifying operational attributes MUST detail how servers are to maintain and/or utilize values of each operational attribute. 5.4. Object Classes Designers SHOULD carefully consider whether attributes of an by the object class are required ("MUST") or allowed ("MAY"). 6. Other Extension Mechanisms 6.1. Attribute Description Options Each option is identified by a string of letters, numbers, and hypen. This string SHOULD be short. 6.1.1. Tag Options 6.1.2. Transfer Encoding Options 6.1.3. Other Options 6.2. LDAP URL Extensions URL extensions are identified by a short string, a descriptor. 7. Other Considerations 7.1. Examples Example DN strings SHOULD conform to the syntax defined in [RFC2253]. Zeilenga LDAP Extensions [Page 8] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 Example LDAP filter strings SHOULD conform to the syntax defined in [RFC2254]. Example LDAP URLs SHOULD conform to the syntax defined in [RFC2255]. LDAP entries SHOULD be represented using LDIF [RFC2849]. 7.2. Authorization Identities Extensions interacting with authorization identities SHALL support the LDAP authzId format [RFC2829, Section 9]. 8. Security Considerations LDAP is designed not to limit the kinds of extensions which can be implemented. This section attempts to outline some specific issues which designers need to consider, it is not (and cannot be) all encompassing. Designers MUST do their own evaluation of the security considerations applicable to their extension. Designers SHOULD NOT the assume that the LDAP "core" technical specification [LDAPTS] adequate addresses the specific concerns surrounding their extension or that their extension has no specific concerns in this area. 8.1 Extending Bind Operation with Controls Controls attached to the request and response messages of a Bind Operation [RFC2251][RFC2829] are not protected by the security layers established by the Bind operation. Specifications detailing controls extending the Bind operation SHALL detail that the Bind negotiated security layers do not protect the information contained in these controls and SHALL detail why protection of Bind negotiated security layers is not needed. It is RECOMMENDED that designers consider alternative mechanisms for providing the function. For example, an extended operation issued subsequent to the Bind operation, hence protected by the security layers negotiated by the Bind operation, might be used to provided the desired function. 8.2 Extending the Start TLS Operation with Controls Controls attached to the request and response messages of a Start TLS Operation [RFC2830] are not protected by the security layers established by the Start TLS operation. Zeilenga LDAP Extensions [Page 9] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 Specifications detailing controls extending the Start TLS operation SHALL detail that the Start TLS negotiated security layers do not protect the information contained in these controls and SHALL detail why protection of Start TLS negotiated security layers is not needed. It is RECOMMENDED that designers consider alternative mechanisms for providing the function. For example, an extended operation issued subsequent to the Start TLS operation, hence protected by the security layers negotiated by the Start TLS operation, might be used to provided the desired function. 9. Acknowledgment The author would like thank the thoughtful comments of members of the IETF LDAPbis, and LDAPext working groups. This work builds upon "LDAP Extension Style Guide" by Bruce Greenblatt. 10. Author's Address Kurt D. Zeilenga OpenLDAP Foundation 11. References 11.1. Normative References [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [RFC2222] J. Myers, "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [RFC2234] D. Crocker, P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC2251] M. Wahl, T. Howes, S. Kille, "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. Zeilenga LDAP Extensions [Page 10] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 [RFC2253] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [RFC2254] T. Howes, "A String Representation of LDAP Search Filters", RFC 2254, December 1997. [RFC2255] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December, 1997. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC2829] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] J. Hodges, R. Morgan, and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [ISOUCS] "Universal Multiple-Octet Coded Character Set (UCS) - Architecture and Basic Multilingual Plane", ISO/IEC 10646-1 : 1993. [LDAPTS] J. Hodges, R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", draft-ietf-ldapbis-ldapv3-ts-xx.txt (a work in progress). [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf-ldapbis-xx.txt (a work in progress). [LDAPIMR] R. Harrison, K. Zeilenga, "LDAP Intermediate Response", draft-rharrison-ldap-intermediate-resp-00.txt (a work in progress). [FORMAL] IESG, "Guidelines for the use of formal languages in IETF specifications", , 2001. [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. 11.2. Informative References Zeilenga LDAP Extensions [Page 11] INTERNET-DRAFT draft-zeilenga-ldap-ext-01 20 December 2001 [RFC2246] T. Dierks, C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [LOCATE] IETF LDAPext WG, "Discovering LDAP Services with DNS", draft-ietf-ldapext-locate-xx.txt (work in progress). 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 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 Extensions [Page 12]