INTERNET-DRAFT Kurt D. Zeilenga
Intended Category: BCP OpenLDAP Foundation
Expires: 15 May 2002 15 November 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 <ietf-ldapext@netscape.com>.
Please send editorial comments directly to the author
<Kurt@OpenLDAP.org>.
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 2001, The Internet Society. All Rights Reserved.
Please see the Copyright section near the end of this document for
more information.
Abstract
LDAP [RFC2251] is an extensible protocol. This document details
considerations for engineers designing LDAP extensions. This draft is
quite rough....
Zeilenga LDAP Extensions [Page 1]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
Conventions
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].
The term "Request Control" refers to a control attached to client
generated message to a server. The term "Response Control" refers to
a control attached to server generated message 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. LDAP Operation Extensions
Extensions SHOULD be use controls to define extensions which
complement existing operations. Where the extension to be defined
does not complement the existing operation, designers SHOULD consider
Zeilenga LDAP Extensions [Page 2]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
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 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 information in the Domain Name System), use of the extended
operation mechanism is likely more appropriate.
2.1. Controls
Controls [RFC2251, Section 4.1.12] is the RECOMMENDED protocol
mechanism for extending existing operations. An existing operation
can be base operation defined in RFC 2251 (e.g., search, modify, etc.)
or an extended operation (e.g. Start TLS, Password Modify), or an
existing 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.
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.
2.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
messages [LDAPIMR], and an ExtendedResponse message.
2.3. Intermediate Responses
Zeilenga LDAP Extensions [Page 3]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
Extensions SHALL use Intermediate Responses [LDAPIMR] instead of
ExtendedResponse [RFC2251] messages to return partial results.
2.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).
2.5. Use of Formal Languages in describing Protocol Elements
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 "core" protocol, it is generally RECOMMENDED that protocol
elements (e.g. extension specific contains of controlValue,
requestValue, and response fields) specified by extensions be
described and encoded similarly.
3. Extending LDAPv3 ASN.1 definition
LDAP allows limited extension of the LDAPv3 ASN.1 definition [RFC2251,
Appendix A] to made.
3.1. Result Codes
Extensions which specify new operations or enhance existing operations
often need to define new result codes.
3.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
Zeilenga LDAP Extensions [Page 4]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
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.
3.3. LDAP Authentication Methods
LDAP supports two authentication methods, simple and SASL. SASL 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.
4. Schema Extensions
Extensions defining LDAP schema elements SHALL provide schema
definitions conformant with syntaxes defined in [RFC2252].
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.
For definitions contain a NAME field, extensions defining new schema
elements SHOULD provide one and only one name. 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.
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.
4.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. It is
Zeilenga LDAP Extensions [Page 5]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
RECOMMENDED that UTF-8 string encoding be defined. Where the string
encoding has a particular format, it is RECOMMENDED that this format
be described a formal language (e.g., [ABNF], [GSER]) in accordance
with IESG guidelines [FORMAL].
If no LDAP syntax is provided, the extension MUST mandate that an
attribute description option indicating the transfer encoding (e.g.
;binary) to be used.
4.2. Matching Rules
4.3. Attribute Types
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.
4.4. Object Classes
5. Other Extension Mechanisms
5.1. Attribute Type Options
5.1.1. Tag Options
5.1.2. Other Options
5.2. LDAP URL Extensions
6. Other Considerations
6.1. Interaction between extensions
Designers SHOULD consider how extensions they engineer interaction
with other extensions and detail how the extension behaves when used
in conjunction with these extensions.
6.2. Examples
Example DN strings SHOULD conform to the syntax defined in [RFC2253].
Example LDAP filter strings SHOULD conform to the syntax defined in
Zeilenga LDAP Extensions [Page 6]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
[RFC2254]. Example LDAP URLs SHOULD conform to the syntax defined in
[RFC2255]. LDAP entries SHOULD be represented using LDIF [RFC2849].
6.3. Authorization Identities
Extensions interacting with authorization identities SHALL support the
LDAP authzId format [RFC2829, Section 9].
6.4. Internationalization
LDAP is designed to support the full ISO 10646-1 (a superset of
Unicode) character set [ISOUCS]. Extensions SHOULD avoid
unnecessarily restricting users to subsets of ISO 10646-1 (e.g.,
UCS-2, ISO 8859-1, US-ASCII).
6.5. IANA Considerations
Designers SHALL appropriately register their LDAP extensions as
detailed in [LDAPIANA].
7. 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 in
compassing. Designers MUST do their own evaluation of the security
considerations applicable to their extension.
Designers SHOULD NOT the assume that the "core" specification adequate
addresses the specific concerns surrounding their extension or that
their extension has no specific concerns in this area.
7.1 Extending Bind Operation with Controls
Controls attached to the request and response messages of a Bind
Operation 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 are not needed.
Zeilenga LDAP Extensions [Page 7]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
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.
7.2 Extending the Start TLS Operation with Controls
Controls attached to the request and response messages of a Start TLS
Operation are not protected by the security layers established by the
Start TLS operation.
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 are 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.
8. Acknowledgment
The author would like thank the thoughtful comments of members of the
IETF LDAPbis, and LDAPext working groups.
This work builds from the prior work of "LDAP Extension Style Guide"
by Bruce Greenblatt.
9. Author's Address
Kurt D. Zeilenga
OpenLDAP Foundation
<Kurt@OpenLDAP.org>
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
Zeilenga LDAP Extensions [Page 8]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
(SASL)", RFC 2222, October 1997.
[RFC2234] D. Crocker, P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[RFC2246] T. Dierks, C. Allen, "The TLS Protocol Version 1.0", RFC
2246, January 1999.
[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.
[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-00.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
Zeilenga LDAP Extensions [Page 9]
INTERNET-DRAFT draft-zeilenga-ldap-ext-00 15 November 2001
progress).
[FORMAL] IESG, "Guidelines for the use of formal languages in IETF
specifications",
<http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-
specs.txt>, 2001.
[LOCATE] IETF LDAPext WG, "Discovering LDAP Services with DNS",
draft-ietf-ldapext-locate-xx.txt (work in progress).
[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.
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 10]
