4521
BEST CURRENT PRACTICE
Considerations for Lightweight Directory Access Protocol (LDAP) Extensions
Authors: K. Zeilenga
Date: June 2006
Working Group: NON WORKING GROUP
Stream: IETF
Abstract
The Lightweight Directory Access Protocol (LDAP) is extensible. It provides mechanisms for adding new operations, extending existing operations, and expanding user and system schemas. This document discusses considerations for designers of LDAP extensions. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
RFC 4521
BEST CURRENT PRACTICE
Errata Exist
Network Working Group K. Zeilenga
Request for Comments: 4521 OpenLDAP Foundation
BCP: 118 June 2006
Category: Best Current Practice
<span class="h1">Considerations for</span>
<span class="h1">Lightweight Directory Access Protocol (LDAP) Extensions</span>
Status of This Memo
This document specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
The Lightweight Directory Access Protocol (LDAP) is extensible. It
provides mechanisms for adding new operations, extending existing
operations, and expanding user and system schemas. This document
discusses considerations for designers of LDAP extensions.
<span class="grey">Zeilenga Best Current Practice [Page 1]</span><span id="page-2" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
Table of Contents
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-3">3</a>
<a href="#section-1.1">1.1</a>. Terminology ................................................<a href="#page-3">3</a>
<a href="#section-2">2</a>. General Considerations ..........................................<a href="#page-4">4</a>
<a href="#section-2.1">2.1</a>. Scope of Extension .........................................<a href="#page-4">4</a>
<a href="#section-2.2">2.2</a>. Interaction between extensions .............................<a href="#page-4">4</a>
<a href="#section-2.3">2.3</a>. Discovery Mechanism ........................................<a href="#page-4">4</a>
<a href="#section-2.4">2.4</a>. Internationalization Considerations ........................<a href="#page-5">5</a>
<a href="#section-2.5">2.5</a>. Use of the Basic Encoding Rules ............................<a href="#page-5">5</a>
<a href="#section-2.6">2.6</a>. Use of Formal Languages ....................................<a href="#page-5">5</a>
<a href="#section-2.7">2.7</a>. Examples ...................................................<a href="#page-5">5</a>
<a href="#section-2.8">2.8</a>. Registration of Protocol Values ............................<a href="#page-5">5</a>
<a href="#section-3">3</a>. LDAP Operation Extensions .......................................<a href="#page-6">6</a>
<a href="#section-3.1">3.1</a>. Controls ...................................................<a href="#page-6">6</a>
<a href="#section-3.1.1">3.1.1</a>. Extending Bind Operation with Controls ..............<a href="#page-6">6</a>
<a href="#section-3.1.2">3.1.2</a>. Extending the Start TLS Operation with Controls .....<a href="#page-7">7</a>
<a href="#section-3.1.3">3.1.3</a>. Extending the Search Operation with Controls ........<a href="#page-7">7</a>
<a href="#section-3.1.4">3.1.4</a>. Extending the Update Operations with Controls .......<a href="#page-8">8</a>
<a href="#section-3.1.5">3.1.5</a>. Extending the Responseless Operations with Controls..8
<a href="#section-3.2">3.2</a>. Extended Operations ........................................<a href="#page-8">8</a>
<a href="#section-3.3">3.3</a>. Intermediate Responses .....................................<a href="#page-8">8</a>
<a href="#section-3.4">3.4</a>. Unsolicited Notifications ..................................<a href="#page-9">9</a>
<a href="#section-4">4</a>. Extending the LDAP ASN.1 Definition .............................<a href="#page-9">9</a>
<a href="#section-4.1">4.1</a>. Result Codes ...............................................<a href="#page-9">9</a>
<a href="#section-4.2">4.2</a>. LDAP Message Types .........................................<a href="#page-9">9</a>
<a href="#section-4.3">4.3</a>. Authentication Methods ....................................<a href="#page-10">10</a>
<a href="#section-4.4">4.4</a>. General ASN.1 Extensibility ...............................<a href="#page-10">10</a>
<a href="#section-5">5</a>. Schema Extensions ..............................................<a href="#page-10">10</a>
<a href="#section-5.1">5.1</a>. LDAP Syntaxes .............................................<a href="#page-11">11</a>
<a href="#section-5.2">5.2</a>. Matching Rules ............................................<a href="#page-11">11</a>
<a href="#section-5.3">5.3</a>. Attribute Types ...........................................<a href="#page-12">12</a>
<a href="#section-5.4">5.4</a>. Object Classes ............................................<a href="#page-12">12</a>
<a href="#section-6">6</a>. Other Extension Mechanisms .....................................<a href="#page-12">12</a>
<a href="#section-6.1">6.1</a>. Attribute Description Options .............................<a href="#page-12">12</a>
<a href="#section-6.2">6.2</a>. Authorization Identities ..................................<a href="#page-12">12</a>
<a href="#section-6.3">6.3</a>. LDAP URL Extensions .......................................<a href="#page-12">12</a>
<a href="#section-7">7</a>. Security Considerations ........................................<a href="#page-12">12</a>
<a href="#section-8">8</a>. Acknowledgements ...............................................<a href="#page-13">13</a>
<a href="#section-9">9</a>. References .....................................................<a href="#page-13">13</a>
<a href="#section-9.1">9.1</a>. Normative References ......................................<a href="#page-13">13</a>
<a href="#section-9.2">9.2</a>. Informative References ....................................<a href="#page-15">15</a>
<span class="grey">Zeilenga Best Current Practice [Page 2]</span><span id="page-3" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
The Lightweight Directory Access Protocol (LDAP) [<a href="./rfc4510" title=""Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map"">RFC4510</a>] is an
extensible protocol.
LDAP allows for new operations to be added and for existing
operations to be enhanced [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>].
LDAP allows additional schema to be defined [<a href="./rfc4512" title=""Lightweight Directory Access Protocol (LDAP): Directory Information Models"">RFC4512</a>][RFC4517]. This
can include additional object classes, attribute types, matching
rules, additional syntaxes, and other elements of schema. LDAP
provides an ability to extend attribute types with options [<a href="./rfc4512" title=""Lightweight Directory Access Protocol (LDAP): Directory Information Models"">RFC4512</a>].
LDAP supports a Simple Authentication and Security Layer (SASL)
authentication method [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>][RFC4513]. SASL [<a href="./rfc4422" title=""Simple Authentication and Security Layer (SASL)"">RFC4422</a>] is
extensible. LDAP may be extended to support additional
authentication methods [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>].
LDAP supports establishment of Transport Layer Security (TLS)
[<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>][RFC4513]. TLS [<a href="./rfc4346" title=""The Transport Layer Security (TLS) Protocol Version 1.1"">RFC4346</a>] is extensible.
LDAP has an extensible Uniform Resource Locator (URL) format
[<a href="./rfc4516" title=""Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator"">RFC4516</a>].
Lastly, LDAP allows for certain extensions to the protocol's Abstract
Syntax Notation - One (ASN.1) [<a href="#ref-X.680" title=""Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation"">X.680</a>] definition to be made. This
facilitates a wide range of protocol enhancements, for example, new
result codes needed to support extensions to be added through
extension of the protocol's ASN.1 definition.
This document describes practices that engineers should consider when
designing extensions to LDAP.
<span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Terminology</span>
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 <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a> [<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>]. In
this document, "the specification", as used by <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>,
refers to the engineering of LDAP extensions.
The term "Request Control" refers to a control attached to a client-
generated message sent to a server. The term "Response Control"
refers to a control attached to a server-generated message sent to a
client.
<span class="grey">Zeilenga Best Current Practice [Page 3]</span><span id="page-4" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
DIT stands for Directory Information Tree.
DSA stands for Directory System Agent, a server.
DSE stands for DSA-Specific Entry.
DUA stands for Directory User Agent, a client.
DN stands for Distinguished Name.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. General Considerations</span>
<span class="h3"><a class="selflink" id="section-2.1" href="#section-2.1">2.1</a>. Scope of Extension</span>
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 that have not agreed to implement or otherwise recognize and
support the extension. Extensions MUST be "truly optional"
[<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>].
<span class="h3"><a class="selflink" id="section-2.2" href="#section-2.2">2.2</a>. Interaction between extensions</span>
Designers SHOULD consider how extensions they engineer interact with
other extensions.
Designers SHOULD consider the extensibility of extensions they
specify. Extensions to LDAP SHOULD themselves be extensible.
Except where it is stated otherwise, extensibility is implied.
<span class="h3"><a class="selflink" id="section-2.3" href="#section-2.3">2.3</a>. Discovery Mechanism</span>
Extensions SHOULD provide adequate discovery mechanisms.
As LDAP design is based upon the client-request/server-response
paradigm, the general discovery approach is for the client to
discover the capabilities of the server before utilizing a particular
extension. Commonly, this discovery involves querying the root DSE
and/or other DSEs for operational information associated with the
extension. LDAP provides no mechanism for a server to discover the
capabilities of a client.
The 'supportedControl' attribute [<a href="./rfc4512" title=""Lightweight Directory Access Protocol (LDAP): Directory Information Models"">RFC4512</a>] is used to advertise
supported controls. The 'supportedExtension' attribute [<a href="./rfc4512" title=""Lightweight Directory Access Protocol (LDAP): Directory Information Models"">RFC4512</a>] is
used to advertise supported extended operations. The
'supportedFeatures' attribute [<a href="./rfc4512" title=""Lightweight Directory Access Protocol (LDAP): Directory Information Models"">RFC4512</a>] is used to advertise
features. Other root DSE attributes MAY be defined to advertise
other capabilities.
<span class="grey">Zeilenga Best Current Practice [Page 4]</span><span id="page-5" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h3"><a class="selflink" id="section-2.4" href="#section-2.4">2.4</a>. Internationalization Considerations</span>
LDAP is designed to support the full Unicode [<a href="#ref-Unicode" title=""The Unicode Standard, Version 3.2.0"">Unicode</a>] repertory of
characters. Extensions SHOULD avoid unnecessarily restricting
applications to subsets of Unicode (e.g., Basic Multilingual Plane,
ISO 8859-1, ASCII, Printable String).
LDAP Language Tag options [<a href="./rfc3866" title=""Language Tags and Ranges in the Lightweight Directory Access Protocol (LDAP)"">RFC3866</a>] provide a mechanism for tagging
text (and other) values with language information. Extensions that
define attribute types SHOULD allow use of language tags with these
attributes.
<span class="h3"><a class="selflink" id="section-2.5" href="#section-2.5">2.5</a>. Use of the Basic Encoding Rules</span>
Numerous elements of LDAP are described using ASN.1 [<a href="#ref-X.680" title=""Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation"">X.680</a>] and are
encoded using a particular subset [Protocol, <a href="#section-5.2">Section 5.2</a>] of the
Basic Encoding Rules (BER) [<a href="#ref-X.690" title=""Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)"">X.690</a>]. To allow reuse of
parsers/generators used in implementing the LDAP "core" technical
specification [<a href="./rfc4510" title=""Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map"">RFC4510</a>], it is RECOMMENDED that extension elements
(e.g., extension specific contents of controlValue, requestValue,
responseValue fields) described by ASN.1 and encoded using BER be
subjected to the restrictions of [Protocol, <a href="#section-5.2">Section 5.2</a>].
<span class="h3"><a class="selflink" id="section-2.6" href="#section-2.6">2.6</a>. Use of Formal Languages</span>
Formal languages SHOULD be used in specifications in accordance with
IESG guidelines [<a href="#ref-FORMAL" title=""Guidelines for the use of formal languages in IETF specifications"">FORMAL</a>].
<span class="h3"><a class="selflink" id="section-2.7" href="#section-2.7">2.7</a>. Examples</span>
Example DN strings SHOULD conform to the syntax defined in [<a href="./rfc4518" title=""Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names"">RFC4518</a>].
Example LDAP filter strings SHOULD conform to the syntax defined in
[<a href="./rfc4515" title=""Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters"">RFC4515</a>]. Example LDAP URLs SHOULD conform to the syntax defined in
[<a href="./rfc4516" title=""Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator"">RFC4516</a>]. Entries SHOULD be represented using LDIF [<a href="./rfc2849" title=""The LDAP Data Interchange Format (LDIF) - Technical Specification"">RFC2849</a>].
<span class="h3"><a class="selflink" id="section-2.8" href="#section-2.8">2.8</a>. Registration of Protocol Values</span>
Designers SHALL register protocol values of their LDAP extensions in
accordance with <a href="https://www.rfc-editor.org/bcp/bcp64">BCP 64</a>, <a href="./rfc4520">RFC 4520</a> [<a href="./rfc4520" title=""Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)"">RFC4520</a>]. Specifications that
create new extensible protocol elements SHALL extend existing
registries or establish new registries for values of these elements
in accordance with <a href="https://www.rfc-editor.org/bcp/bcp64">BCP 64</a>, <a href="./rfc4520">RFC 4520</a> [<a href="./rfc4520" title=""Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)"">RFC4520</a>] and <a href="https://www.rfc-editor.org/bcp/bcp26">BCP 26</a>, <a href="./rfc2434">RFC 2434</a>
[<a href="./rfc2434" title="">RFC2434</a>].
<span class="grey">Zeilenga Best Current Practice [Page 5]</span><span id="page-6" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. LDAP Operation Extensions</span>
Extensions SHOULD use controls in defining extensions that complement
existing operations. Where the extension to be defined does not
complement an 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 operation (an
operation that would return for a DN a set of LDAP URLs to services
that may hold the entry named by 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 contrived
to search for entries held in the Directory Information Tree), it is
likely more appropriate to define a new operation using the extended
operation mechanism.
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Controls</span>
Controls [Protocol, <a href="#section-4.1.11">Section 4.1.11</a>] are the RECOMMENDED mechanism for
extending existing operations. The existing operation can be a base
operation defined in [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>] (e.g., search, modify) , an extended
operation (e.g., Start TLS [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>], Password Modify [<a href="./rfc3062" title=""LDAP Password Modify Extended Operation"">RFC3062</a>]), or
an operation defined as an extension to a base or extended operation.
Extensions SHOULD NOT return Response controls 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 [Protocol, <a href="#section-4.13">Section 4.13</a>].
Specifications of controls SHALL NOT attach additional semantics to
the criticality of controls beyond those defined in [Protocol,
<a href="#section-4.1.11">Section 4.1.11</a>]. A specification MAY mandate the criticality take on
a particular value (e.g., TRUE or FALSE), where appropriate.
<span class="h4"><a class="selflink" id="section-3.1.1" href="#section-3.1.1">3.1.1</a>. Extending Bind Operation with Controls</span>
Controls attached to the request and response messages of a Bind
Operation [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>] are not protected by any security layers
established by that Bind operation.
<span class="grey">Zeilenga Best Current Practice [Page 6]</span><span id="page-7" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
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 how the
information in these controls is protected or why the information
does not need protection.
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 provide the
desired function.
Additionally, designers of Bind control extensions MUST also consider
how the controls' semantics interact with individual steps of a
multi-step Bind operation. Note that some steps are optional and
thus may require special attention in the design.
<span class="h4"><a class="selflink" id="section-3.1.2" href="#section-3.1.2">3.1.2</a>. Extending the Start TLS Operation with Controls</span>
Controls attached to the request and response messages of a Start TLS
Operation [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>] 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
how the information in these controls is protected or why the
information does not need protection.
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.
<span class="h4"><a class="selflink" id="section-3.1.3" href="#section-3.1.3">3.1.3</a>. Extending the Search Operation with Controls</span>
The Search operation processing has two distinct phases:
- finding the base object; and
- searching for objects at or under that base object.
Specifications of controls extending the Search Operation should
clearly state in which phase(s) the control's semantics apply.
Semantics of controls that are not specific to the Search Operation
SHOULD apply in the finding phase.
<span class="grey">Zeilenga Best Current Practice [Page 7]</span><span id="page-8" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h4"><a class="selflink" id="section-3.1.4" href="#section-3.1.4">3.1.4</a>. Extending the Update Operations with Controls</span>
Update operations have properties of atomicity, consistency,
isolation, and durability ([<a href="#ref-ACID">ACID</a>]).
- atomicity: All or none of the DIT changes requested are made.
- consistency: The resulting DIT state must be conform to schema
and other constraints.
- isolation: Intermediate states are not exposed.
- durability: The resulting DIT state is preserved until
subsequently updated.
When defining a control that requests additional (or other) DIT
changes be made to the DIT, these additional changes SHOULD NOT be
treated as part of a separate transaction. The specification MUST be
clear as to whether the additional DIT changes are part of the same
or a separate transaction as the DIT changes expressed in the request
of the base operation.
When defining a control that requests additional (or other) DIT
changes be made to the DIT, the specification MUST be clear as to the
order in which these and the base changes are to be applied to the
DIT.
<span class="h4"><a class="selflink" id="section-3.1.5" href="#section-3.1.5">3.1.5</a>. Extending the Responseless Operations with Controls</span>
The Abandon and Unbind operations do not include a response message.
For this reason, specifications for controls designed to be attached
to Abandon and Unbind requests SHOULD mandate that the control's
criticality be FALSE.
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Extended Operations</span>
Extended Operations [Protocol, <a href="#section-4.12">Section 4.12</a>] are the RECOMMENDED
mechanism for defining new operations. An extended operation
consists of an ExtendedRequest message, zero or more
IntermediateResponse messages, and an ExtendedResponse message.
<span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Intermediate Responses</span>
Extensions SHALL use IntermediateResponse messages instead of
ExtendedResponse messages to return intermediate results.
<span class="grey">Zeilenga Best Current Practice [Page 8]</span><span id="page-9" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h3"><a class="selflink" id="section-3.4" href="#section-3.4">3.4</a>. Unsolicited Notifications</span>
Unsolicited notifications [Protocol, <a href="#section-4.4">Section 4.4</a>] offer a capability
for the server to notify the client of events not associated with the
operation currently being processed.
Extensions SHOULD be designed such that unsolicited notifications are
not returned unless the server has specific knowledge that the client
can make use of the notification. Generally, the client requests the
return of a 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 that were enabled by
an extended operation (which possibly specified the desired
interval).
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Extending the LDAP ASN.1 Definition</span>
LDAP allows limited extension [Protocol, <a href="#section-4">Section 4</a>] of the LDAP ASN.1
definition [Protocol, <a href="#appendix-B">Appendix B</a>] to be made.
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Result Codes</span>
Extensions that 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
that are consistent with the intended meaning [<a href="./rfc4511" title=""Lightweight Directory Access Protocol (LDAP): The Protocol"">RFC4511</a>][X.511] of
these codes. Extensions MAY introduce new result codes [<a href="./rfc4520" title=""Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)"">RFC4520</a>]
where no existing result code provides an adequate indication of the
nature of the result.
Extensions SHALL NOT disallow or otherwise restrict the return of
general service result codes, especially those reporting a protocol,
service, or security problem, or indicating that the server is unable
or unwilling to complete the operation.
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. LDAP Message Types</span>
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.
<span class="grey">Zeilenga Best Current Practice [Page 9]</span><span id="page-10" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
In such cases, a new extension mechanism SHOULD be defined that can
be used by multiple extensions that have similar needs.
<span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. Authentication Methods</span>
The Bind operation currently supports two authentication methods,
simple and SASL. SASL [<a href="./rfc4422" title=""Simple Authentication and Security Layer (SASL)"">RFC4422</a>] 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's primary function is to establish the LDAP
association [<a href="./rfc4513" title=""Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms"">RFC4513</a>]. No other operation SHALL be defined (or
extended) to establish the LDAP association. However, other
operations MAY be defined to establish other security associations
(e.g., IPsec).
<span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. General ASN.1 Extensibility</span>
<a href="./rfc4511#section-4">Section 4 of [RFC4511]</a> states the following:
In order to support future extensions to this protocol,
extensibility is implied where it is allowed per ASN.1 (i.e.,
sequence, set, choice, and enumerated types are extensible). In
addition, ellipses (...) have been supplied in ASN.1 types that
are explicitly extensible as discussed in [<a href="./rfc4520" title=""Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)"">RFC4520</a>]. Because of
the implied extensibility, clients and servers MUST (unless
otherwise specified) ignore trailing SEQUENCE components whose
tags they do not recognize.
Designers SHOULD avoid introducing extensions that rely on
unsuspecting implementations to ignore trailing components of
SEQUENCE whose tags they do not recognize.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Schema Extensions</span>
Extensions defining LDAP schema elements SHALL provide schema
definitions conforming with syntaxes defined in [Models, <a href="#section-4.1">Section</a>
<a href="#section-4.1">4.1</a>]. While provided definitions MAY be reformatted (line wrapped)
for readability, this SHALL be noted in the specification.
For definitions that 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
MUST be regarded as informational. That is, the specification MUST
<span class="grey">Zeilenga Best Current Practice [Page 10]</span><span id="page-11" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
be written such that its interpretation is the same with and without
the provided DESC fields.
The extension SHALL NOT mandate that implementations provide the same
DESC field in the 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 designers SHOULD reuse existing schema elements, where
appropriate. However, any reuse MUST not alter the semantics of the
element.
<span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. LDAP Syntaxes</span>
Each LDAP syntax [<a href="./rfc4517" title=""Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules"">RFC4517</a>] is defined in terms of ASN.1 [<a href="#ref-X.680" title=""Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation"">X.680</a>].
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 UTF-8
[<a href="./rfc3629" title=""UTF-8, a transformation format of ISO 10646"">RFC3629</a>] encoded Unicode [<a href="#ref-Unicode" title=""The Unicode Standard, Version 3.2.0"">Unicode</a>] characters. Use of Generic
String Encoding Rules (GSER) [<a href="./rfc3641" title=""Generic String Encoding Rules (GSER) for ASN.1 Types"">RFC3641</a>][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
[<a href="./rfc4234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC4234</a>]). Formal languages SHOULD be used in specifications in
accordance with IESG guidelines [<a href="#ref-FORMAL" title=""Guidelines for the use of formal languages in IETF specifications"">FORMAL</a>].
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.
<span class="h3"><a class="selflink" id="section-5.2" href="#section-5.2">5.2</a>. Matching Rules</span>
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.
In addition to requirements stated in the LDAP technical
specification, equality matching rules SHOULD be commutative.
<span class="grey">Zeilenga Best Current Practice [Page 11]</span><span id="page-12" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
<span class="h3"><a class="selflink" id="section-5.3" href="#section-5.3">5.3</a>. Attribute Types</span>
Designers SHOULD carefully consider how the structure of values is to
be restricted. Designers SHOULD consider that servers will only
enforce constraints of the attribute's syntax. That is, an attribute
intended to hold URIs, but that has directoryString syntax, is not
restricted to values that 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.
Extensions specifying operational attributes MUST detail how servers
are to maintain and/or utilize values of each operational attribute.
<span class="h3"><a class="selflink" id="section-5.4" href="#section-5.4">5.4</a>. Object Classes</span>
Designers SHOULD carefully consider whether each attribute of an
object class is required ("MUST") or allowed ("MAY").
Extensions specifying object classes that allow (or require)
operational attributes MUST specify how servers are to maintain
and/or utilize entries belonging to these object classes.
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Other Extension Mechanisms</span>
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Attribute Description Options</span>
Each option is identified by a string of letters, numbers, and
hyphens. This string SHOULD be short.
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Authorization Identities</span>
Extensions interacting with authorization identities SHALL support
the LDAP authzId format [<a href="./rfc4513" title=""Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms"">RFC4513</a>]. The authzId format is extensible.
<span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a>. LDAP URL Extensions</span>
LDAP URL extensions are identified by a short string, a descriptor.
Like other descriptors, the string SHOULD be short.
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Security Considerations</span>
LDAP does not place undue restrictions on the kinds of extensions
that can be implemented. While this document attempts to outline
some specific issues that designers need to consider, it is not (and
<span class="grey">Zeilenga Best Current Practice [Page 12]</span><span id="page-13" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
cannot be) all encompassing. Designers MUST do their own evaluations
of the security considerations applicable to their extensions.
Designers MUST NOT assume that the LDAP "core" technical
specification [<a href="./rfc4510" title=""Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map"">RFC4510</a>] adequately addresses the specific concerns
surrounding their extensions or assume that their extensions have no
specific concerns.
Extension specifications, however, SHOULD note whether security
considerations specific to the feature they are extending, as well as
general LDAP security considerations, apply to the extension.
<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Acknowledgements</span>
The author thanks the IETF LDAP community for their thoughtful
comments.
This work builds upon "LDAP Extension Style Guide" [<a href="#ref-GUIDE" title=""LDAP Extension Style Guide"">GUIDE</a>] by Bruce
Greenblatt.
<span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. References</span>
<span class="h3"><a class="selflink" id="section-9.1" href="#section-9.1">9.1</a>. Normative References</span>
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
[<a id="ref-RFC2434">RFC2434</a>] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", <a href="https://www.rfc-editor.org/bcp/bcp26">BCP 26</a>, <a href="./rfc2434">RFC 2434</a>,
October 1998.
[<a id="ref-RFC2849">RFC2849</a>] Good, G., "The LDAP Data Interchange Format (LDIF) -
Technical Specification", <a href="./rfc2849">RFC 2849</a>, June 2000.
[<a id="ref-RFC3629">RFC3629</a>] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, <a href="./rfc3629">RFC 3629</a>, November 2003.
[<a id="ref-RFC3641">RFC3641</a>] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1
Types", <a href="./rfc3641">RFC 3641</a>, October 2003.
[<a id="ref-RFC3642">RFC3642</a>] Legg, S., "Common Elements of Generic String Encoding
Rules (GSER) Encodings", <a href="./rfc3642">RFC 3642</a>, October 2003.
[<a id="ref-RFC4512">RFC4512</a>] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP): Directory Information Models", <a href="./rfc4512">RFC 4512</a>, June
2006.
<span class="grey">Zeilenga Best Current Practice [Page 13]</span><span id="page-14" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
[<a id="ref-RFC3866">RFC3866</a>] Zeilenga, K., Ed., "Language Tags and Ranges in the
Lightweight Directory Access Protocol (LDAP)", <a href="./rfc3866">RFC 3866</a>,
July 2004.
[<a id="ref-RFC4234">RFC4234</a>] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", <a href="./rfc4234">RFC 4234</a>, October 2005.
[<a id="ref-RFC4510">RFC4510</a>] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
(LDAP): Technical Specification Road Map", <a href="./rfc4510">RFC 4510</a>, June
2006.
[<a id="ref-RFC4511">RFC4511</a>] Sermersheim, J., Ed., "Lightweight Directory Access
Protocol (LDAP): The Protocol", <a href="./rfc4511">RFC 4511</a>, June 2006.
[<a id="ref-RFC4512">RFC4512</a>] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP): Directory Information Models", <a href="./rfc4512">RFC 4512</a>, June
2006.
[<a id="ref-RFC4513">RFC4513</a>] Harrison, R., Ed., "Lightweight Directory Access Protocol
(LDAP): Authentication Methods and Security Mechanisms",
<a href="./rfc4513">RFC 4513</a>, June 2006.
[<a id="ref-RFC4515">RFC4515</a>] Smith, M., Ed. and T. Howes, "Lightweight Directory Access
Protocol (LDAP): String Representation of Search Filters",
<a href="./rfc4515">RFC 4515</a>, June 2006.
[<a id="ref-RFC4516">RFC4516</a>] Smith, M., Ed. and T. Howes, "Lightweight Directory Access
Protocol (LDAP): Uniform Resource Locator", <a href="./rfc4516">RFC 4516</a>, June
2006.
[<a id="ref-RFC4517">RFC4517</a>] Legg, S., Ed., "Lightweight Directory Access Protocol
(LDAP): Syntaxes and Matching Rules", <a href="./rfc4517">RFC 4517</a>, June 2006.
[<a id="ref-RFC4518">RFC4518</a>] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP): String Representation of Distinguished Names", <a href="./rfc4518">RFC</a>
<a href="./rfc4518">4518</a>, June 2006.
[<a id="ref-RFC4520">RFC4520</a>] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
Considerations for the Lightweight Directory Access
Protocol (LDAP)", <a href="https://www.rfc-editor.org/bcp/bcp64">BCP 64</a>, <a href="./rfc4520">RFC 4520</a>, June 2006.
[<a id="ref-RFC4422">RFC4422</a>] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
Authentication and Security Layer (SASL)", <a href="./rfc4422">RFC 4422</a>, June
2006.
<span class="grey">Zeilenga Best Current Practice [Page 14]</span><span id="page-15" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
[<a id="ref-Unicode">Unicode</a>] 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" (<a href="http://www.unicode.org/reports/tr27/">http://www.unicode.org/reports/tr27/</a>) and by the
"Unicode Standard Annex #28: Unicode 3.2"
(<a href="http://www.unicode.org/reports/tr28/">http://www.unicode.org/reports/tr28/</a>).
[<a id="ref-FORMAL">FORMAL</a>] IESG, "Guidelines for the use of formal languages in IETF
specifications",
<<a href="http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt">http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-</a>
<a href="http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt">specs.txt</a>>, 2001.
[<a id="ref-X.511">X.511</a>] International Telecommunication Union - Telecommunication
Standardization Sector, "The Directory: Abstract Service
Definition", X.511(1993) (also ISO/IEC 9594-3:1993).
[<a id="ref-X.680">X.680</a>] International Telecommunication Union - Telecommunication
Standardization Sector, "Abstract Syntax Notation One
(ASN.1) - Specification of Basic Notation", X.680(2002)
(also ISO/IEC 8824-1:2002).
[<a id="ref-X.690">X.690</a>] 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(2002) (also ISO/IEC 8825-1:2002).
<span class="h3"><a class="selflink" id="section-9.2" href="#section-9.2">9.2</a>. Informative References</span>
[<a id="ref-ACID">ACID</a>] <a href="#section-4">Section 4</a> of ISO/IEC 10026-1:1992.
[<a id="ref-GUIDE">GUIDE</a>] Greenblatt, B., <a style="text-decoration: none" href='https://www.google.com/search?sitesearch=datatracker.ietf.org%2Fdoc%2Fhtml%2F&q=inurl:draft-+%22LDAP+Extension+Style+Guide%22'>"LDAP Extension Style Guide"</a>, Work in
Progress.
[<a id="ref-RFC3062">RFC3062</a>] Zeilenga, K., "LDAP Password Modify Extended Operation",
<a href="./rfc3062">RFC 3062</a>, February 2001.
[<a id="ref-RFC4346">RFC4346</a>] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.1", <a href="./rfc4346">RFC 4346</a>, April 2006.
Author's Address
Kurt D. Zeilenga
OpenLDAP Foundation
EMail: [email protected]
<span class="grey">Zeilenga Best Current Practice [Page 15]</span><span id="page-16" ></span>
<span class="grey"><a href="./rfc4521">RFC 4521</a> LDAP Extensions June 2006</span>
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a>, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM 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.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and <a href="https://www.rfc-editor.org/bcp/bcp79">BCP 79</a>.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
<a href="http://www.ietf.org/ipr">http://www.ietf.org/ipr</a>.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
[email protected].
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Zeilenga Best Current Practice [Page 16]
Annotations
Select text to annotate