INTERNET-DRAFT Kurt D. Zeilenga
Intended Category: Informational OpenLDAP Foundation
Expires in six months 15 February 2004
Considerations for LDAP Extensions
<draft-zeilenga-ldap-ext-05.txt>
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 an Informational RFC.
Distribution of this memo is unlimited. Technical discussion of this
document will take place on the IETF LDAP Extensions mailing list
<ldapext@ietf.org>. 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 (C) The Internet Society (2004). All Rights Reserved.
Please see the Full 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 expanding user and system schema. This document
discusses considerations for designers of LDAP extensions.
Zeilenga LDAP Extensions [Page 1]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
Terminology
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]. In
this case, "the specification" as used by BCP 14 refers to the
engineering of LDAP extensions.
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.
DSA stands for Directory System Agent.
DSE stands for DSA-Specific Entry.
DUA stands for Directory User Agent.
1. Background and Intended Use
The Lightweight Directory Access Protocol (LDAP) [RFC3377] is an
extensible protocol.
LDAP allows for new operations to be added and existing operations to
be enhanced [RFC2251].
LDAP allows additional 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 establishment of Transport Layer Security (TLS)
[RFC2830]. TLS [RFC2246] is extensible.
LDAP provides an ability to extend attribute types with options
[RFC2251]. LDAP defines one option, ;binary). Other options can be
defined in other documents.
LDAP has an extensible URL format [RFC2255].
Lastly, LDAP 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
Zeilenga LDAP Extensions [Page 2]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
designing extensions to LDAP.
2. General Considerations
2.1 Scope of Extension
Mutually agreeing peers may, within the confines of an extension,
agree to significant changes in protocol semantics. However,
designers MUST consider the impact of an extension upon protocol peers
which have not agreed to implement, or otherwise recognize and
support, the extension. That is, extensions SHOULD be "truely
optional" [RFC2119].
2.2. Discovery Mechanism
Extensions SHOULD provide an adequate discover mechanism.
Generally, a client discovers the capabilities of the server by
querying the root DSE and/or other DSEs containing operational
information (such as subschema subentries).
The 'supportedControl' attribute [RFC2252] is used to advertised
supported controls. The 'supportedExtension' attribute [RFC2252] is
used to advertised supported extended operations. The
'supportedFeatures' attribute [RFC3674] is used to advertise features.
Other root DSE attributes MAY be defined to advertise other
capabilities.
As LDAP design is based upon the client-request/server-response
paradigm, no mechanism is provided for a server to discover the
capabilities of a client.
2.3. Interaction between extensions
Designers SHOULD consider how extensions they engineer interaction
with other extensions.
Designers SHOULD consider extensibility of extensions they specify.
Extensions to LDAP SHOULD themselves be extensible.
2.4. Internationalization Considerations
LDAP is designed to support Unicode [Unicode]. Extensions SHOULD
avoid unnecessarily restricting applications to subsets of Unicode
Zeilenga LDAP Extensions [Page 3]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
(e.g., Basic Multilingual Plane, ISO 8859-1, ASCII, Printable String).
LDAP Language Tag Options [RFC2596] provides a mechanism for tagging
text (and other) values with language information. Extensions which
define attribute types SHOULD allow use of language tags with these
attributes.
2.5. IANA Considerations
Designers SHALL register protocol values of their LDAP extensions in
accordance with BCP 64 [RFC3383]. Specifications which create new
extensible protocol elements SHALL extended existing or establish new
registries for values of these elements in accordance with BCP 64
[RFC3383] and BCP 26 [RFC2434].
2.6. 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 [RFC3377], 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
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 (e.g., the operation is not searching for entries held in
Zeilenga LDAP Extensions [Page 4]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
the Directory Information Tree), it is likely more appropriate to
define a new operation using the extended operation mechanism.
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 [RFC2830], Password Modify
[RFC3062]), or an operation defined as an extension to a base or
extended operation.
Extensions SHOULD NOT return Response controls unless 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 IntermediateResponse
messages [LDAPIRM].
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
messages [LDAPIRM], and an ExtendedResponse message.
3.3. Intermediate Responses
Extensions SHALL use Intermediate Responses [LDAPIRM] 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
Zeilenga LDAP Extensions [Page 5]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
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 LDAP 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 the intended meaning [RFC2251][X.511] of
these codes. Extensions MAY introduce new result codes where no
existing result code provides an adequate indication of the nature of
the result.
Extensions SHALL NOT disallow nor otherwise restrict the return of
general service result codes, especially those reporting a protocol,
service, or security problem, or indicating server is unable or
unwilling 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, unsolicited notifications, and
intermediate responses) 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
Zeilenga LDAP Extensions [Page 6]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
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,
IMAP, SMTP). It is RECOMMENDED that new authentication processes be
defined as SASL mechanisms. New LDAP authentication 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
Section 4 of [RFC2251] 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. That is, designers SHOULD consider
other mechanisms before resorting inserting new elements in existing
SEQUENCE encodings.
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.
For definitions allow a NAME field, new schema elements SHOULD provide
one and only one name. The name SHOULD be short.
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 be different if all
DESC fields were removed.
The extension SHALL NOT mandate that implementations provide the same
DESC field in schema they publish. Implementors 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
Zeilenga LDAP Extensions [Page 7]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
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. A distinct LDAP syntax SHOULD be created
for each distinct ASN.1 data definition (including constraints).
Each LDAP syntax SHOULD have a string encoding defined for it. It is
RECOMMENDED that this string encoding be restricted to a UTF-8
[RFC3629] encoded Unicode [Unicode] characters. Use of Generic String
Encoding Rules (GSER) [RFC3641][RFC3642] or other generic string
encoding rules to provide 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
[RFC2234]). 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 (e.g., 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
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. That is, an attribute intended
to hold URIs, but which has directoryString syntax, is not restricted
to values which are URIs.
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.
Zeilenga LDAP Extensions [Page 8]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
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 each attributes of an
object class is required ("MUST") or allowed ("MAY").
Extensions specifying object classes which allow (or require)
operational attributes MUST specify how servers are to maintain and/or
utilize entries belonging to these object classes.
6. Other Extension Mechanisms
6.1. Attribute Description Options
Each option is identified by a string of letters, numbers, and hyphen.
This string SHOULD be short.
7. Other Considerations
7.1. Examples
Example DN strings SHOULD conform to the syntax defined in [RFC2253].
Example LDAP filter strings SHOULD conform to the syntax defined in
[RFC2254]. Example LDAP URLs SHOULD conform to the syntax defined in
[RFC2255]. 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 does not place undue restrictions on 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 MUST NOT the assume that the LDAP "core" technical
specification [RFC3377] adequately addresses the specific concerns
Zeilenga LDAP Extensions [Page 9]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
surrounding their extension nor assume that their extension has no
specific concerns.
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 this
protection 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.
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 this protection 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 thanks the IETF LDAP community for their thoughtful
comments.
This work builds upon "LDAP Extension Style Guide" [GUIDE] by Bruce
Greenblatt.
Zeilenga LDAP Extensions [Page 10]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
Some text was borrowed from "Guidelines for Writing an IANA
Considerations Section in RFCs" [RFC2434] by Thomas Narten and Harald
Alvestrand.
10. Author's Address
Kurt D. Zeilenga
OpenLDAP Foundation
Email: Kurt@OpenLDAP.org
11. References
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14 (also RFC 2119), March 1997.
[RFC2222] Myers, J., "Simple Authentication and Security Layer
(SASL)", RFC 2222, October 1997.
[RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[RFC2251] Wahl, M., T. Howes and S. Kille, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[RFC2252] Wahl, M., A. Coulbeck, T. Howes, and S. Kille,
"Lightweight Directory Access Protocol (v3): Attribute
Syntax Definitions", RFC 2252, December 1997.
[RFC2253] Wahl, M., S. Kille, and T. Howes, "Lightweight Directory
Access Protocol (v3): UTF-8 String Representation of
Distinguished Names", RFC 2253, December 1997.
[RFC2254] Howes, T., "A String Representation of LDAP Search
Filters", RFC 2254, December 1997.
[RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255,
December, 1997.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26 (also RFC
2434), October 1998.
[RFC2596] Wahl, M. and T. Howes, "Use of Language Codes in LDAP",
Zeilenga LDAP Extensions [Page 11]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
RFC 2596, May 1999.
[RFC2829] Wahl, M., H. Alvestrand, and J. Hodges, RL "Bob" Morgan,
"Authentication Methods for LDAP", RFC 2829, June 2000.
[RFC2830] Hodges, J., R. Morgan, and M. Wahl, "Lightweight
Directory Access Protocol (v3): Extension for Transport
Layer Security", RFC 2830, May 2000.
[RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) -
Technical Specification", RFC 2849, June 2000.
[RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
Protocol (v3): Technical Specification", RFC 3377,
September 2002.
[RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64
(also RFC 3383), September 2002.
[RFC3639] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 3639 (also STD 63), November 2003.
[RFC3641] Legg, S., "Generic String Encoding Rules for ASN.1
Types", RFC 3641, October 2003.
[Features] Zeilenga, K., "Feature Discovery in LDAP", RFC 3674,
December 2003.
[LDAPIRM] Harrison, R. and Zeilenga, K., "LDAP Intermediate
Response",
draft-rharrison-ldap-intermediate-resp-00.txt, a work in
progress.
[Unicode] The Unicode Consortium, "The Unicode Standard, Version
3.2.0" is defined by "The Unicode Standard, Version 3.0"
(Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
as amended by the "Unicode Standard Annex #27: Unicode
3.1" (http://www.unicode.org/reports/tr27/) and by the
"Unicode Standard Annex #28: Unicode 3.2"
(http://www.unicode.org/reports/tr28/).
[FORMAL] IESG, "Guidelines for the use of formal languages in
IETF specifications",
<http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt>,
2001.
[X.511] International Telecommunication Union -
Telecommunication Standardization Sector, "The
Zeilenga LDAP Extensions [Page 12]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
Directory: Abstract Service Definition", X.511(1993).
[X.680] International Telecommunication Union -
Telecommunication Standardization Sector, "Abstract
Syntax Notation One (ASN.1) - Specification of Basic
Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
[X.690] International Telecommunication Union -
Telecommunication Standardization Sector, "Specification
of ASN.1 encoding rules: Basic Encoding Rules (BER),
Canonical Encoding Rules (CER), and Distinguished
Encoding Rules (DER)", X.690(1997) (also ISO/IEC
8825-1:1998).
11.2. Informative References
[RFC2246] Dierks, T. and, C. Allen, "The TLS Protocol Version
1.0", RFC 2246, January 1999.
[RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation",
RFC 3062, February 2000.
[RFC3642] Legg, S., "Common Elements of GSER Encodings", RFC 3642,
October 2003.
[LOCATE] IETF LDAPext WG, "Discovering LDAP Services with DNS",
draft-ietf-ldapext-locate-xx.txt, a work in progress.
[GUIDE] Greenblatt, B., "LDAP Extension Style Guide",
draft-greenblatt-ldapext-style-xx.txt, an (expired) work
in progress.
Full Copyright
Copyright (C) The Internet Society (2004). 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
Zeilenga LDAP Extensions [Page 13]
INTERNET-DRAFT draft-zeilenga-ldap-ext-05 15 February 2004
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.
Zeilenga LDAP Extensions [Page 14]
