You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by no...@apache.org on 2002/12/13 18:40:00 UTC
cvs commit: jakarta-james/www/rfclist/ldap rfc2251.txt rfc2252.txt rfc2253.txt rfc2254.txt rfc2255.txt rfc2256.txt rfc2829.txt rfc2830.txt rfc3377.txt
noel 2002/12/13 09:39:59
Added: www/rfclist/ldap rfc2251.txt rfc2252.txt rfc2253.txt
rfc2254.txt rfc2255.txt rfc2256.txt rfc2829.txt
rfc2830.txt rfc3377.txt
Log:
Added LDAP RFCs
Revision Changes Path
1.1 jakarta-james/www/rfclist/ldap/rfc2251.txt
Index: rfc2251.txt
===================================================================
Network Working Group M. Wahl
Request for Comments: 2251 Critical Angle Inc.
Category: Standards Track T. Howes
Netscape Communications Corp.
S. Kille
Isode Limited
December 1997
Lightweight Directory Access Protocol (v3)
1. Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG Note
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Wahl, et. al. Standards Track [Page 1]
RFC 2251 LDAPv3 December 1997
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
Table of Contents
1. Status of this Memo .................................... 1
Copyright Notice ....................................... 1
IESG Note .............................................. 1
2. Abstract ............................................... 3
3. Models ................................................. 4
3.1. Protocol Model ........................................ 4
3.2. Data Model ............................................ 5
3.2.1. Attributes of Entries ............................... 5
3.2.2. Subschema Entries and Subentries .................... 7
3.3. Relationship to X.500 ................................. 8
3.4. Server-specific Data Requirements ..................... 8
4. Elements of Protocol ................................... 9
4.1. Common Elements ....................................... 9
4.1.1. Message Envelope .................................... 9
4.1.1.1. Message ID ........................................ 11
4.1.2. String Types ........................................ 11
4.1.3. Distinguished Name and Relative Distinguished Name .. 11
4.1.4. Attribute Type ...................................... 12
4.1.5. Attribute Description ............................... 13
4.1.5.1. Binary Option ..................................... 14
4.1.6. Attribute Value ..................................... 14
4.1.7. Attribute Value Assertion ........................... 15
4.1.8. Attribute ........................................... 15
4.1.9. Matching Rule Identifier ............................ 15
4.1.10. Result Message ..................................... 16
4.1.11. Referral ........................................... 18
4.1.12. Controls ........................................... 19
4.2. Bind Operation ........................................ 20
4.2.1. Sequencing of the Bind Request ...................... 21
4.2.2. Authentication and Other Security Services .......... 22
4.2.3. Bind Response ....................................... 23
4.3. Unbind Operation ...................................... 24
4.4. Unsolicited Notification .............................. 24
4.4.1. Notice of Disconnection ............................. 24
4.5. Search Operation ...................................... 25
Wahl, et. al. Standards Track [Page 2]
RFC 2251 LDAPv3 December 1997
4.5.1. Search Request ...................................... 25
4.5.2. Search Result ....................................... 29
4.5.3. Continuation References in the Search Result ........ 31
4.5.3.1. Example ........................................... 31
4.6. Modify Operation ...................................... 32
4.7. Add Operation ......................................... 34
4.8. Delete Operation ...................................... 35
4.9. Modify DN Operation ................................... 36
4.10. Compare Operation .................................... 37
4.11. Abandon Operation .................................... 38
4.12. Extended Operation ................................... 38
5. Protocol Element Encodings and Transfer ................ 39
5.1. Mapping Onto BER-based Transport Services ............. 39
5.2. Transfer Protocols .................................... 40
5.2.1. Transmission Control Protocol (TCP) ................. 40
6. Implementation Guidelines .............................. 40
6.1. Server Implementations ................................ 40
6.2. Client Implementations ................................ 40
7. Security Considerations ................................ 41
8. Acknowledgements ....................................... 41
9. Bibliography ........................................... 41
10. Authors' Addresses ..................................... 42
Appendix A - Complete ASN.1 Definition ..................... 44
Full Copyright Statement ................................... 50
2. Abstract
The protocol described in this document is designed to provide access
to directories supporting the X.500 models, while not incurring the
resource requirements of the X.500 Directory Access Protocol (DAP).
This protocol is specifically targeted at management applications and
browser applications that provide read/write interactive access to
directories. When used with a directory supporting the X.500
protocols, it is intended to be a complement to the X.500 DAP.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document
are to be interpreted as described in RFC 2119 [10].
Key aspects of this version of LDAP are:
- All protocol elements of LDAPv2 (RFC 1777) are supported. The
protocol is carried directly over TCP or other transport, bypassing
much of the session/presentation overhead of X.500 DAP.
- Most protocol data elements can be encoded as ordinary strings
(e.g., Distinguished Names).
Wahl, et. al. Standards Track [Page 3]
RFC 2251 LDAPv3 December 1997
- Referrals to other servers may be returned.
- SASL mechanisms may be used with LDAP to provide association
security services.
- Attribute values and Distinguished Names have been
internationalized through the use of the ISO 10646 character set.
- The protocol can be extended to support new operations, and
controls may be used to extend existing operations.
- Schema is published in the directory for use by clients.
3. Models
Interest in X.500 [1] directory technologies in the Internet has led
to efforts to reduce the high cost of entry associated with use of
these technologies. This document continues the efforts to define
directory protocol alternatives, updating the LDAP [2] protocol
specification.
3.1. Protocol Model
The general model adopted by this protocol is one of clients
performing protocol operations against servers. In this model, a
client transmits a protocol request describing the operation to be
performed to a server. The server is then responsible for performing
the necessary operation(s) in the directory. Upon completion of the
operation(s), the server returns a response containing any results or
errors to the requesting client.
In keeping with the goal of easing the costs associated with use of
the directory, it is an objective of this protocol to minimize the
complexity of clients so as to facilitate widespread deployment of
applications capable of using the directory.
Note that although servers are required to return responses whenever
such responses are defined in the protocol, there is no requirement
for synchronous behavior on the part of either clients or servers.
Requests and responses for multiple operations may be exchanged
between a client and server in any order, provided the client
eventually receives a response for every request that requires one.
In LDAP versions 1 and 2, no provision was made for protocol servers
returning referrals to clients. However, for improved performance
and distribution this version of the protocol permits servers to
return to clients referrals to other servers. This allows servers to
offload the work of contacting other servers to progress operations.
Wahl, et. al. Standards Track [Page 4]
RFC 2251 LDAPv3 December 1997
Note that the core protocol operations defined in this document can
be mapped to a strict subset of the X.500(1997) directory abstract
service, so it can be cleanly provided by the DAP. However there is
not a one-to-one mapping between LDAP protocol operations and DAP
operations: server implementations acting as a gateway to X.500
directories may need to make multiple DAP requests.
3.2. Data Model
This section provides a brief introduction to the X.500 data model,
as used by LDAP.
The LDAP protocol assumes there are one or more servers which jointly
provide access to a Directory Information Tree (DIT). The tree is
made up of entries. Entries have names: one or more attribute values
from the entry form its relative distinguished name (RDN), which MUST
be unique among all its siblings. The concatenation of the relative
distinguished names of the sequence of entries from a particular
entry to an immediate subordinate of the root of the tree forms that
entry's Distinguished Name (DN), which is unique in the tree. An
example of a Distinguished Name is
CN=Steve Kille, O=Isode Limited, C=GB
Some servers may hold cache or shadow copies of entries, which can be
used to answer search and comparison queries, but will return
referrals or contact other servers if modification operations are
requested.
Servers which perform caching or shadowing MUST ensure that they do
not violate any access control constraints placed on the data by the
originating server.
The largest collection of entries, starting at an entry that is
mastered by a particular server, and including all its subordinates
and their subordinates, down to the entries which are mastered by
different servers, is termed a naming context. The root of the DIT
is a DSA-specific Entry (DSE) and not part of any naming context:
each server has different attribute values in the root DSE. (DSA is
an X.500 term for the directory server).
3.2.1. Attributes of Entries
Entries consist of a set of attributes. An attribute is a type with
one or more associated values. The attribute type is identified by a
short descriptive name and an OID (object identifier). The attribute
Wahl, et. al. Standards Track [Page 5]
RFC 2251 LDAPv3 December 1997
type governs whether there can be more than one value of an attribute
of that type in an entry, the syntax to which the values must
conform, the kinds of matching which can be performed on values of
that attribute, and other functions.
An example of an attribute is "mail". There may be one or more values
of this attribute, they must be IA5 (ASCII) strings, and they are
case insensitive (e.g. "foo@bar.com" will match "FOO@BAR.COM").
Schema is the collection of attribute type definitions, object class
definitions and other information which a server uses to determine
how to match a filter or attribute value assertion (in a compare
operation) against the attributes of an entry, and whether to permit
add and modify operations. The definition of schema for use with
LDAP is given in [5] and [6]. Additional schema elements may be
defined in other documents.
Each entry MUST have an objectClass attribute. The objectClass
attribute specifies the object classes of an entry, which along with
the system and user schema determine the permitted attributes of an
entry. Values of this attribute may be modified by clients, but the
objectClass attribute cannot be removed. Servers may restrict the
modifications of this attribute to prevent the basic structural class
of the entry from being changed (e.g. one cannot change a person into
a country). When creating an entry or adding an objectClass value to
an entry, all superclasses of the named classes are implicitly added
as well if not already present, and the client must supply values for
any mandatory attributes of new superclasses.
Some attributes, termed operational attributes, are used by servers
for administering the directory system itself. They are not returned
in search results unless explicitly requested by name. Attributes
which are not operational, such as "mail", will have their schema and
syntax constraints enforced by servers, but servers will generally
not make use of their values.
Servers MUST NOT permit clients to add attributes to an entry unless
those attributes are permitted by the object class definitions, the
schema controlling that entry (specified in the subschema - see
below), or are operational attributes known to that server and used
for administrative purposes. Note that there is a particular
objectClass 'extensibleObject' defined in [5] which permits all user
attributes to be present in an entry.
Entries MAY contain, among others, the following operational
attributes, defined in [5]. These attributes are maintained
automatically by the server and are not modifiable by clients:
Wahl, et. al. Standards Track [Page 6]
RFC 2251 LDAPv3 December 1997
- creatorsName: the Distinguished Name of the user who added this
entry to the directory.
- createTimestamp: the time this entry was added to the directory.
- modifiersName: the Distinguished Name of the user who last modified
this entry.
- modifyTimestamp: the time this entry was last modified.
- subschemaSubentry: the Distinguished Name of the subschema entry
(or subentry) which controls the schema for this entry.
3.2.2. Subschema Entries and Subentries
Subschema entries are used for administering information about the
directory schema, in particular the object classes and attribute
types supported by directory servers. A single subschema entry
contains all schema definitions used by entries in a particular part
of the directory tree.
Servers which follow X.500(93) models SHOULD implement subschema
using the X.500 subschema mechanisms, and so these subschemas are not
ordinary entries. LDAP clients SHOULD NOT assume that servers
implement any of the other aspects of X.500 subschema. A server
which masters entries and permits clients to modify these entries
MUST implement and provide access to these subschema entries, so that
its clients may discover the attributes and object classes which are
permitted to be present. It is strongly recommended that all other
servers implement this as well.
The following four attributes MUST be present in all subschema
entries:
- cn: this attribute MUST be used to form the RDN of the subschema
entry.
- objectClass: the attribute MUST have at least the values "top" and
"subschema".
- objectClasses: each value of this attribute specifies an object
class known to the server.
- attributeTypes: each value of this attribute specifies an attribute
type known to the server.
These are defined in [5]. Other attributes MAY be present in
subschema entries, to reflect additional supported capabilities.
Wahl, et. al. Standards Track [Page 7]
RFC 2251 LDAPv3 December 1997
These include matchingRules, matchingRuleUse, dITStructureRules,
dITContentRules, nameForms and ldapSyntaxes.
Servers SHOULD provide the attributes createTimestamp and
modifyTimestamp in subschema entries, in order to allow clients to
maintain their caches of schema information.
Clients MUST only retrieve attributes from a subschema entry by
requesting a base object search of the entry, where the search filter
is "(objectClass=subschema)". (This will allow LDAPv3 servers which
gateway to X.500(93) to detect that subentry information is being
requested.)
3.3. Relationship to X.500
This document defines LDAP in terms of X.500 as an X.500 access
mechanism. An LDAP server MUST act in accordance with the
X.500(1993) series of ITU recommendations when providing the service.
However, it is not required that an LDAP server make use of any X.500
protocols in providing this service, e.g. LDAP can be mapped onto any
other directory system so long as the X.500 data and service model as
used in LDAP is not violated in the LDAP interface.
3.4. Server-specific Data Requirements
An LDAP server MUST provide information about itself and other
information that is specific to each server. This is represented as
a group of attributes located in the root DSE (DSA-Specific Entry),
which is named with the zero-length LDAPDN. These attributes are
retrievable if a client performs a base object search of the root
with filter "(objectClass=*)", however they are subject to access
control restrictions. The root DSE MUST NOT be included if the
client performs a subtree search starting from the root.
Servers may allow clients to modify these attributes.
The following attributes of the root DSE are defined in section 5 of
[5]. Additional attributes may be defined in other documents.
- namingContexts: naming contexts held in the server. Naming contexts
are defined in section 17 of X.501 [6].
- subschemaSubentry: subschema entries (or subentries) known by this
server.
- altServer: alternative servers in case this one is later
unavailable.
Wahl, et. al. Standards Track [Page 8]
RFC 2251 LDAPv3 December 1997
- supportedExtension: list of supported extended operations.
- supportedControl: list of supported controls.
- supportedSASLMechanisms: list of supported SASL security features.
- supportedLDAPVersion: LDAP versions implemented by the server.
If the server does not master entries and does not know the locations
of schema information, the subschemaSubentry attribute is not present
in the root DSE. If the server masters directory entries under one
or more schema rules, there may be any number of values of the
subschemaSubentry attribute in the root DSE.
4. Elements of Protocol
The LDAP protocol is described using Abstract Syntax Notation 1
(ASN.1) [3], and is typically transferred using a subset of ASN.1
Basic Encoding Rules [11]. In order to support future extensions to
this protocol, clients and servers MUST ignore elements of SEQUENCE
encodings whose tags they do not recognize.
Note that unlike X.500, each change to the LDAP protocol other than
through the extension mechanisms will have a different version
number. A client will indicate the version it supports as part of
the bind request, described in section 4.2. If a client has not sent
a bind, the server MUST assume that version 3 is supported in the
client (since version 2 required that the client bind first).
Clients may determine the protocol version a server supports by
reading the supportedLDAPVersion attribute from the root DSE. Servers
which implement version 3 or later versions MUST provide this
attribute. Servers which only implement version 2 may not provide
this attribute.
4.1. Common Elements
This section describes the LDAPMessage envelope PDU (Protocol Data
Unit) format, as well as data type definitions which are used in the
protocol operations.
4.1.1. Message Envelope
For the purposes of protocol exchanges, all protocol operations are
encapsulated in a common envelope, the LDAPMessage, which is defined
as follows:
LDAPMessage ::= SEQUENCE {
Wahl, et. al. Standards Track [Page 9]
RFC 2251 LDAPv3 December 1997
messageID MessageID,
protocolOp CHOICE {
bindRequest BindRequest,
bindResponse BindResponse,
unbindRequest UnbindRequest,
searchRequest SearchRequest,
searchResEntry SearchResultEntry,
searchResDone SearchResultDone,
searchResRef SearchResultReference,
modifyRequest ModifyRequest,
modifyResponse ModifyResponse,
addRequest AddRequest,
addResponse AddResponse,
delRequest DelRequest,
delResponse DelResponse,
modDNRequest ModifyDNRequest,
modDNResponse ModifyDNResponse,
compareRequest CompareRequest,
compareResponse CompareResponse,
abandonRequest AbandonRequest,
extendedReq ExtendedRequest,
extendedResp ExtendedResponse },
controls [0] Controls OPTIONAL }
MessageID ::= INTEGER (0 .. maxInt)
maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
The function of the LDAPMessage is to provide an envelope containing
common fields required in all protocol exchanges. At this time the
only common fields are the message ID and the controls.
If the server receives a PDU from the client in which the LDAPMessage
SEQUENCE tag cannot be recognized, the messageID cannot be parsed,
the tag of the protocolOp is not recognized as a request, or the
encoding structures or lengths of data fields are found to be
incorrect, then the server MUST return the notice of disconnection
described in section 4.4.1, with resultCode protocolError, and
immediately close the connection. In other cases that the server
cannot parse the request received by the client, the server MUST
return an appropriate response to the request, with the resultCode
set to protocolError.
If the client receives a PDU from the server which cannot be parsed,
the client may discard the PDU, or may abruptly close the connection.
The ASN.1 type Controls is defined in section 4.1.12.
Wahl, et. al. Standards Track [Page 10]
RFC 2251 LDAPv3 December 1997
4.1.1.1. Message ID
All LDAPMessage envelopes encapsulating responses contain the
messageID value of the corresponding request LDAPMessage.
The message ID of a request MUST have a value different from the
values of any other requests outstanding in the LDAP session of which
this message is a part.
A client MUST NOT send a second request with the same message ID as
an earlier request on the same connection if the client has not
received the final response from the earlier request. Otherwise the
behavior is undefined. Typical clients increment a counter for each
request.
A client MUST NOT reuse the message id of an abandonRequest or of the
abandoned operation until it has received a response from the server
for another request invoked subsequent to the abandonRequest, as the
abandonRequest itself does not have a response.
4.1.2. String Types
The LDAPString is a notational convenience to indicate that, although
strings of LDAPString type encode as OCTET STRING types, the ISO
10646 [13] character set (a superset of Unicode) is used, encoded
following the UTF-8 algorithm [14]. Note that in the UTF-8 algorithm
characters which are the same as ASCII (0x0000 through 0x007F) are
represented as that same ASCII character in a single byte. The other
byte values are used to form a variable-length encoding of an
arbitrary character.
LDAPString ::= OCTET STRING
The LDAPOID is a notational convenience to indicate that the
permitted value of this string is a (UTF-8 encoded) dotted-decimal
representation of an OBJECT IDENTIFIER.
LDAPOID ::= OCTET STRING
For example,
1.3.6.1.4.1.1466.1.2.3
4.1.3. Distinguished Name and Relative Distinguished Name
An LDAPDN and a RelativeLDAPDN are respectively defined to be the
representation of a Distinguished Name and a Relative Distinguished
Name after encoding according to the specification in [4], such that
Wahl, et. al. Standards Track [Page 11]
RFC 2251 LDAPv3 December 1997
<distinguished-name> ::= <name>
<relative-distinguished-name> ::= <name-component>
where <name> and <name-component> are as defined in [4].
LDAPDN ::= LDAPString
RelativeLDAPDN ::= LDAPString
Only Attribute Types can be present in a relative distinguished name
component; the options of Attribute Descriptions (next section) MUST
NOT be used in specifying distinguished names.
4.1.4. Attribute Type
An AttributeType takes on as its value the textual string associated
with that AttributeType in its specification.
AttributeType ::= LDAPString
Each attribute type has a unique OBJECT IDENTIFIER which has been
assigned to it. This identifier may be written as decimal digits
with components separated by periods, e.g. "2.5.4.10".
A specification may also assign one or more textual names for an
attribute type. These names MUST begin with a letter, and only
contain ASCII letters, digit characters and hyphens. They are case
insensitive. (These ASCII characters are identical to ISO 10646
characters whose UTF-8 encoding is a single byte between 0x00 and
0x7F.)
If the server has a textual name for an attribute type, it MUST use a
textual name for attributes returned in search results. The dotted-
decimal OBJECT IDENTIFIER is only used if there is no textual name
for an attribute type.
Attribute type textual names are non-unique, as two different
specifications (neither in standards track RFCs) may choose the same
name.
A server which masters or shadows entries SHOULD list all the
attribute types it supports in the subschema entries, using the
attributeTypes attribute. Servers which support an open-ended set of
attributes SHOULD include at least the attributeTypes value for the
'objectClass' attribute. Clients MAY retrieve the attributeTypes
value from subschema entries in order to obtain the OBJECT IDENTIFIER
and other information associated with attribute types.
Wahl, et. al. Standards Track [Page 12]
RFC 2251 LDAPv3 December 1997
Some attribute type names which are used in this version of LDAP are
described in [5]. Servers may implement additional attribute types.
4.1.5. Attribute Description
An AttributeDescription is a superset of the definition of the
AttributeType. It has the same ASN.1 definition, but allows
additional options to be specified. They are also case insensitive.
AttributeDescription ::= LDAPString
A value of AttributeDescription is based on the following BNF:
<AttributeDescription> ::= <AttributeType> [ ";" <options> ]
<options> ::= <option> | <option> ";" <options>
<option> ::= <opt-char> <opt-char>*
<opt-char> ::= ASCII-equivalent letters, numbers and hyphen
Examples of valid AttributeDescription:
cn
userCertificate;binary
One option, "binary", is defined in this document. Additional
options may be defined in IETF standards-track and experimental RFCs.
Options beginning with "x-" are reserved for private experiments.
Any option could be associated with any AttributeType, although not
all combinations may be supported by a server.
An AttributeDescription with one or more options is treated as a
subtype of the attribute type without any options. Options present
in an AttributeDescription are never mutually exclusive.
Implementations MUST generate the <options> list sorted in ascending
order, and servers MUST treat any two AttributeDescription with the
same AttributeType and options as equivalent. A server will treat an
AttributeDescription with any options it does not implement as an
unrecognized attribute type.
The data type "AttributeDescriptionList" describes a list of 0 or
more attribute types. (A list of zero elements has special
significance in the Search request.)
AttributeDescriptionList ::= SEQUENCE OF
AttributeDescription
Wahl, et. al. Standards Track [Page 13]
RFC 2251 LDAPv3 December 1997
4.1.5.1. Binary Option
If the "binary" option is present in an AttributeDescription, it
overrides any string-based encoding representation defined for that
attribute in [5]. Instead the attribute is to be transferred as a
binary value encoded using the Basic Encoding Rules [11]. The syntax
of the binary value is an ASN.1 data type definition which is
referenced by the "SYNTAX" part of the attribute type definition.
The presence or absence of the "binary" option only affects the
transfer of attribute values in protocol; servers store any
particular attribute in a single format. If a client requests that a
server return an attribute in the binary format, but the server
cannot generate that format, the server MUST treat this attribute
type as an unrecognized attribute type. Similarly, clients MUST NOT
expect servers to return an attribute in binary format if the client
requested that attribute by name without the binary option.
This option is intended to be used with attributes whose syntax is a
complex ASN.1 data type, and the structure of values of that type is
needed by clients. Examples of this kind of syntax are "Certificate"
and "CertificateList".
4.1.6. Attribute Value
A field of type AttributeValue takes on as its value either a string
encoding of a AttributeValue data type, or an OCTET STRING containing
an encoded binary value, depending on whether the "binary" option is
present in the companion AttributeDescription to this AttributeValue.
The definition of string encodings for different syntaxes and types
may be found in other documents, and in particular [5].
AttributeValue ::= OCTET STRING
Note that there is no defined limit on the size of this encoding;
thus protocol values may include multi-megabyte attributes (e.g.
photographs).
Attributes may be defined which have arbitrary and non-printable
syntax. Implementations MUST NEITHER simply display nor attempt to
decode as ASN.1 a value if its syntax is not known. The
implementation may attempt to discover the subschema of the source
entry, and retrieve the values of attributeTypes from it.
Clients MUST NOT send attribute values in a request which are not
valid according to the syntax defined for the attributes.
Wahl, et. al. Standards Track [Page 14]
RFC 2251 LDAPv3 December 1997
4.1.7. Attribute Value Assertion
The AttributeValueAssertion type definition is similar to the one in
the X.500 directory standards. It contains an attribute description
and a matching rule assertion value suitable for that type.
AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription,
assertionValue AssertionValue }
AssertionValue ::= OCTET STRING
If the "binary" option is present in attributeDesc, this signals to
the server that the assertionValue is a binary encoding of the
assertion value.
For all the string-valued user attributes described in [5], the
assertion value syntax is the same as the value syntax. Clients may
use attribute values as assertion values in compare requests and
search filters.
Note however that the assertion syntax may be different from the
value syntax for other attributes or for non-equality matching rules.
These may have an assertion syntax which contains only part of the
value. See section 20.2.1.8 of X.501 [6] for examples.
4.1.8. Attribute
An attribute consists of a type and one or more values of that type.
(Though attributes MUST have at least one value when stored, due to
access control restrictions the set may be empty when transferred in
protocol. This is described in section 4.5.2, concerning the
PartialAttributeList type.)
Attribute ::= SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
Each attribute value is distinct in the set (no duplicates). The
order of attribute values within the vals set is undefined and
implementation-dependent, and MUST NOT be relied upon.
4.1.9. Matching Rule Identifier
A matching rule is a means of expressing how a server should compare
an AssertionValue received in a search filter with an abstract data
value. The matching rule defines the syntax of the assertion value
and the process to be performed in the server.
Wahl, et. al. Standards Track [Page 15]
RFC 2251 LDAPv3 December 1997
An X.501(1993) Matching Rule is identified in the LDAP protocol by
the printable representation of its OBJECT IDENTIFIER, either as one
of the strings given in [5], or as decimal digits with components
separated by periods, e.g. "caseIgnoreIA5Match" or
"1.3.6.1.4.1.453.33.33".
MatchingRuleId ::= LDAPString
Servers which support matching rules for use in the extensibleMatch
search filter MUST list the matching rules they implement in
subschema entries, using the matchingRules attributes. The server
SHOULD also list there, using the matchingRuleUse attribute, the
attribute types with which each matching rule can be used. More
information is given in section 4.4 of [5].
4.1.10. Result Message
The LDAPResult is the construct used in this protocol to return
success or failure indications from servers to clients. In response
to various requests servers will return responses containing fields
of type LDAPResult to indicate the final status of a protocol
operation request.
LDAPResult ::= SEQUENCE {
resultCode ENUMERATED {
success (0),
operationsError (1),
protocolError (2),
timeLimitExceeded (3),
sizeLimitExceeded (4),
compareFalse (5),
compareTrue (6),
authMethodNotSupported (7),
strongAuthRequired (8),
-- 9 reserved --
referral (10), -- new
adminLimitExceeded (11), -- new
unavailableCriticalExtension (12), -- new
confidentialityRequired (13), -- new
saslBindInProgress (14), -- new
noSuchAttribute (16),
undefinedAttributeType (17),
inappropriateMatching (18),
constraintViolation (19),
attributeOrValueExists (20),
invalidAttributeSyntax (21),
-- 22-31 unused --
Wahl, et. al. Standards Track [Page 16]
RFC 2251 LDAPv3 December 1997
noSuchObject (32),
aliasProblem (33),
invalidDNSyntax (34),
-- 35 reserved for undefined isLeaf --
aliasDereferencingProblem (36),
-- 37-47 unused --
inappropriateAuthentication (48),
invalidCredentials (49),
insufficientAccessRights (50),
busy (51),
unavailable (52),
unwillingToPerform (53),
loopDetect (54),
-- 55-63 unused --
namingViolation (64),
objectClassViolation (65),
notAllowedOnNonLeaf (66),
notAllowedOnRDN (67),
entryAlreadyExists (68),
objectClassModsProhibited (69),
-- 70 reserved for CLDAP --
affectsMultipleDSAs (71), -- new
-- 72-79 unused --
other (80) },
-- 81-90 reserved for APIs --
matchedDN LDAPDN,
errorMessage LDAPString,
referral [3] Referral OPTIONAL }
All the result codes with the exception of success, compareFalse and
compareTrue are to be treated as meaning the operation could not be
completed in its entirety.
Most of the result codes are based on problem indications from X.511
error data types. Result codes from 16 to 21 indicate an
AttributeProblem, codes 32, 33, 34 and 36 indicate a NameProblem,
codes 48, 49 and 50 indicate a SecurityProblem, codes 51 to 54
indicate a ServiceProblem, and codes 64 to 69 and 71 indicates an
UpdateProblem.
If a client receives a result code which is not listed above, it is
to be treated as an unknown error condition.
The errorMessage field of this construct may, at the server's option,
be used to return a string containing a textual, human-readable
(terminal control and page formatting characters should be avoided)
error diagnostic. As this error diagnostic is not standardized,
Wahl, et. al. Standards Track [Page 17]
RFC 2251 LDAPv3 December 1997
implementations MUST NOT rely on the values returned. If the server
chooses not to return a textual diagnostic, the errorMessage field of
the LDAPResult type MUST contain a zero length string.
For result codes of noSuchObject, aliasProblem, invalidDNSyntax and
aliasDereferencingProblem, the matchedDN field is set to the name of
the lowest entry (object or alias) in the directory that was matched.
If no aliases were dereferenced while attempting to locate the entry,
this will be a truncated form of the name provided, or if aliases
were dereferenced, of the resulting name, as defined in section 12.5
of X.511 [8]. The matchedDN field is to be set to a zero length
string with all other result codes.
4.1.11. Referral
The referral error indicates that the contacted server does not hold
the target entry of the request. The referral field is present in an
LDAPResult if the LDAPResult.resultCode field value is referral, and
absent with all other result codes. It contains a reference to
another server (or set of servers) which may be accessed via LDAP or
other protocols. Referrals can be returned in response to any
operation request (except unbind and abandon which do not have
responses). At least one URL MUST be present in the Referral.
The referral is not returned for a singleLevel or wholeSubtree search
in which the search scope spans multiple naming contexts, and several
different servers would need to be contacted to complete the
operation. Instead, continuation references, described in section
4.5.3, are returned.
Referral ::= SEQUENCE OF LDAPURL -- one or more
LDAPURL ::= LDAPString -- limited to characters permitted in URLs
If the client wishes to progress the operation, it MUST follow the
referral by contacting any one of servers. All the URLs MUST be
equally capable of being used to progress the operation. (The
mechanisms for how this is achieved by multiple servers are outside
the scope of this document.)
URLs for servers implementing the LDAP protocol are written according
to [9]. If an alias was dereferenced, the <dn> part of the URL MUST
be present, with the new target object name. If the <dn> part is
present, the client MUST use this name in its next request to
progress the operation, and if it is not present the client will use
the same name as in the original request. Some servers (e.g.
participating in distributed indexing) may provide a different filter
in a referral for a search operation. If the filter part of the URL
Wahl, et. al. Standards Track [Page 18]
RFC 2251 LDAPv3 December 1997
is present in an LDAPURL, the client MUST use this filter in its next
request to progress this search, and if it is not present the client
MUST use the same filter as it used for that search. Other aspects
of the new request may be the same or different as the request which
generated the referral.
Note that UTF-8 characters appearing in a DN or search filter may not
be legal for URLs (e.g. spaces) and MUST be escaped using the %
method in RFC 1738 [7].
Other kinds of URLs may be returned, so long as the operation could
be performed using that protocol.
4.1.12. Controls
A control is a way to specify extension information. Controls which
are sent as part of a request apply only to that request and are not
saved.
Controls ::= SEQUENCE OF Control
Control ::= SEQUENCE {
controlType LDAPOID,
criticality BOOLEAN DEFAULT FALSE,
controlValue OCTET STRING OPTIONAL }
The controlType field MUST be a UTF-8 encoded dotted-decimal
representation of an OBJECT IDENTIFIER which uniquely identifies the
control. This prevents conflicts between control names.
The criticality field is either TRUE or FALSE.
If the server recognizes the control type and it is appropriate for
the operation, the server will make use of the control when
performing the operation.
If the server does not recognize the control type and the criticality
field is TRUE, the server MUST NOT perform the operation, and MUST
instead return the resultCode unsupportedCriticalExtension.
If the control is not appropriate for the operation and criticality
field is TRUE, the server MUST NOT perform the operation, and MUST
instead return the resultCode unsupportedCriticalExtension.
If the control is unrecognized or inappropriate but the criticality
field is FALSE, the server MUST ignore the control.
Wahl, et. al. Standards Track [Page 19]
RFC 2251 LDAPv3 December 1997
The controlValue contains any information associated with the
control, and its format is defined for the control. The server MUST
be prepared to handle arbitrary contents of the controlValue octet
string, including zero bytes. It is absent only if there is no value
information which is associated with a control of its type.
This document does not define any controls. Controls may be defined
in other documents. The definition of a control consists of:
- the OBJECT IDENTIFIER assigned to the control,
- whether the control is always noncritical, always critical, or
critical at the client's option,
- the format of the controlValue contents of the control.
Servers list the controls which they recognize in the
supportedControl attribute in the root DSE.
4.2. Bind Operation
The function of the Bind Operation is to allow authentication
information to be exchanged between the client and server.
The Bind Request is defined as follows:
BindRequest ::= [APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication AuthenticationChoice }
AuthenticationChoice ::= CHOICE {
simple [0] OCTET STRING,
-- 1 and 2 reserved
sasl [3] SaslCredentials }
SaslCredentials ::= SEQUENCE {
mechanism LDAPString,
credentials OCTET STRING OPTIONAL }
Parameters of the Bind Request are:
- version: A version number indicating the version of the protocol to
be used in this protocol session. This document describes version
3 of the LDAP protocol. Note that there is no version negotiation,
and the client just sets this parameter to the version it desires.
If the client requests protocol version 2, a server that supports
the version 2 protocol as described in [2] will not return any v3-
Wahl, et. al. Standards Track [Page 20]
RFC 2251 LDAPv3 December 1997
specific protocol fields. (Note that not all LDAP servers will
support protocol version 2, since they may be unable to generate
the attribute syntaxes associated with version 2.)
- name: The name of the directory object that the client wishes to
bind as. This field may take on a null value (a zero length
string) for the purposes of anonymous binds, when authentication
has been performed at a lower layer, or when using SASL credentials
with a mechanism that includes the LDAPDN in the credentials.
- authentication: information used to authenticate the name, if any,
provided in the Bind Request.
Upon receipt of a Bind Request, a protocol server will authenticate
the requesting client, if necessary. The server will then return a
Bind Response to the client indicating the status of the
authentication.
Authorization is the use of this authentication information when
performing operations. Authorization MAY be affected by factors
outside of the LDAP Bind request, such as lower layer security
services.
4.2.1. Sequencing of the Bind Request
For some SASL authentication mechanisms, it may be necessary for the
client to invoke the BindRequest multiple times. If at any stage the
client wishes to abort the bind process it MAY unbind and then drop
the underlying connection. Clients MUST NOT invoke operations
between two Bind requests made as part of a multi-stage bind.
A client may abort a SASL bind negotiation by sending a BindRequest
with a different value in the mechanism field of SaslCredentials, or
an AuthenticationChoice other than sasl.
If the client sends a BindRequest with the sasl mechanism field as an
empty string, the server MUST return a BindResponse with
authMethodNotSupported as the resultCode. This will allow clients to
abort a negotiation if it wishes to try again with the same SASL
mechanism.
Unlike LDAP v2, the client need not send a Bind Request in the first
PDU of the connection. The client may request any operations and the
server MUST treat these as unauthenticated. If the server requires
that the client bind before browsing or modifying the directory, the
server MAY reject a request other than binding, unbinding or an
extended request with the "operationsError" result.
Wahl, et. al. Standards Track [Page 21]
RFC 2251 LDAPv3 December 1997
If the client did not bind before sending a request and receives an
operationsError, it may then send a Bind Request. If this also fails
or the client chooses not to bind on the existing connection, it will
close the connection, reopen it and begin again by first sending a
PDU with a Bind Request. This will aid in interoperating with
servers implementing other versions of LDAP.
Clients MAY send multiple bind requests on a connection to change
their credentials. A subsequent bind process has the effect of
abandoning all operations outstanding on the connection. (This
simplifies server implementation.) Authentication from earlier binds
are subsequently ignored, and so if the bind fails, the connection
will be treated as anonymous. If a SASL transfer encryption or
integrity mechanism has been negotiated, and that mechanism does not
support the changing of credentials from one identity to another,
then the client MUST instead establish a new connection.
4.2.2. Authentication and Other Security Services
The simple authentication option provides minimal authentication
facilities, with the contents of the authentication field consisting
only of a cleartext password. Note that the use of cleartext
passwords is not recommended over open networks when there is no
authentication or encryption being performed by a lower layer; see
the "Security Considerations" section.
If no authentication is to be performed, then the simple
authentication option MUST be chosen, and the password be of zero
length. (This is often done by LDAPv2 clients.) Typically the DN is
also of zero length.
The sasl choice allows for any mechanism defined for use with SASL
[12]. The mechanism field contains the name of the mechanism. The
credentials field contains the arbitrary data used for
authentication, inside an OCTET STRING wrapper. Note that unlike
some Internet application protocols where SASL is used, LDAP is not
text-based, thus no base64 transformations are performed on the
credentials.
If any SASL-based integrity or confidentiality services are enabled,
they take effect following the transmission by the server and
reception by the client of the final BindResponse with resultCode
success.
The client can request that the server use authentication information
from a lower layer protocol by using the SASL EXTERNAL mechanism.
Wahl, et. al. Standards Track [Page 22]
RFC 2251 LDAPv3 December 1997
4.2.3. Bind Response
The Bind Response is defined as follows.
BindResponse ::= [APPLICATION 1] SEQUENCE {
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
BindResponse consists simply of an indication from the server of he
status of the client's request for authentication.
f the bind was successful, the resultCode will be success, therwise
it will be one of:
- operationsError: server encountered an internal error,
- protocolError: unrecognized version number or incorrect PDU
structure,
- authMethodNotSupported: unrecognized SASL mechanism name,
- strongAuthRequired: the server requires authentication be
performed with a SASL mechanism,
- referral: this server cannot accept this bind and the client
should try another,
- saslBindInProgress: the server requires the client to send a
new bind request, with the same sasl mechanism, to continue the
authentication process,
- inappropriateAuthentication: the server requires the client
which had attempted to bind anonymously or without supplying
credentials to provide some form of credentials,
- invalidCredentials: the wrong password was supplied or the SASL
credentials could not be processed,
- unavailable: the server is shutting down.
If the server does not support the client's requested protocol
version, it MUST set the resultCode to protocolError.
If the client receives a BindResponse response where the resultCode
was protocolError, it MUST close the connection as the server will be
unwilling to accept further operations. (This is for compatibility
with earlier versions of LDAP, in which the bind was always the first
operation, and there was no negotiation.)
Wahl, et. al. Standards Track [Page 23]
RFC 2251 LDAPv3 December 1997
The serverSaslCreds are used as part of a SASL-defined bind mechanism
to allow the client to authenticate the server to which it is
communicating, or to perform "challenge-response" authentication. If
the client bound with the password choice, or the SASL mechanism does
not require the server to return information to the client, then this
field is not to be included in the result.
4.3. Unbind Operation
The function of the Unbind Operation is to terminate a protocol
session. The Unbind Operation is defined as follows:
UnbindRequest ::= [APPLICATION 2] NULL
The Unbind Operation has no response defined. Upon transmission of an
UnbindRequest, a protocol client may assume that the protocol session
is terminated. Upon receipt of an UnbindRequest, a protocol server
may assume that the requesting client has terminated the session and
that all outstanding requests may be discarded, and may close the
connection.
4.4. Unsolicited Notification
An unsolicited notification is an LDAPMessage sent from the server to
the client which is not in response to any LDAPMessage received by
the server. It is used to signal an extraordinary condition in the
server or in the connection between the client and the server. The
notification is of an advisory nature, and the server will not expect
any response to be returned from the client.
The unsolicited notification is structured as an LDAPMessage in which
the messageID is 0 and protocolOp is of the extendedResp form. The
responseName field of the ExtendedResponse is present. The LDAPOID
value MUST be unique for this notification, and not be used in any
other situation.
One unsolicited notification is defined in this document.
4.4.1. Notice of Disconnection
This notification may be used by the server to advise the client that
the server is about to close the connection due to an error
condition. Note that this notification is NOT a response to an
unbind requested by the client: the server MUST follow the procedures
of section 4.3. This notification is intended to assist clients in
distinguishing between an error condition and a transient network
Wahl, et. al. Standards Track [Page 24]
RFC 2251 LDAPv3 December 1997
failure. As with a connection close due to network failure, the
client MUST NOT assume that any outstanding requests which modified
the directory have succeeded or failed.
The responseName is 1.3.6.1.4.1.1466.20036, the response field is
absent, and the resultCode is used to indicate the reason for the
disconnection.
The following resultCode values are to be used in this notification:
- protocolError: The server has received data from the client in
which
the LDAPMessage structure could not be parsed.
- strongAuthRequired: The server has detected that an established
underlying security association protecting communication between
the client and server has unexpectedly failed or been compromised.
- unavailable: This server will stop accepting new connections and
operations on all existing connections, and be unavailable for an
extended period of time. The client may make use of an alternative
server.
After sending this notice, the server MUST close the connection.
After receiving this notice, the client MUST NOT transmit any further
on the connection, and may abruptly close the connection.
4.5. Search Operation
The Search Operation allows a client to request that a search be
performed on its behalf by a server. This can be used to read
attributes from a single entry, from entries immediately below a
particular entry, or a whole subtree of entries.
4.5.1. Search Request
The Search Request is defined as follows:
SearchRequest ::= [APPLICATION 3] SEQUENCE {
baseObject LDAPDN,
scope ENUMERATED {
baseObject (0),
singleLevel (1),
wholeSubtree (2) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
Wahl, et. al. Standards Track [Page 25]
RFC 2251 LDAPv3 December 1997
derefAlways (3) },
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
typesOnly BOOLEAN,
filter Filter,
attributes AttributeDescriptionList }
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeDescription,
approxMatch [8] AttributeValueAssertion,
extensibleMatch [9] MatchingRuleAssertion }
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
-- at least one must be present
substrings SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString } }
MatchingRuleAssertion ::= SEQUENCE {
matchingRule [1] MatchingRuleId OPTIONAL,
type [2] AttributeDescription OPTIONAL,
matchValue [3] AssertionValue,
dnAttributes [4] BOOLEAN DEFAULT FALSE }
Parameters of the Search Request are:
- baseObject: An LDAPDN that is the base object entry relative to
which the search is to be performed.
- scope: An indicator of the scope of the search to be performed. The
semantics of the possible values of this field are identical to the
semantics of the scope field in the X.511 Search Operation.
- derefAliases: An indicator as to how alias objects (as defined in
X.501) are to be handled in searching. The semantics of the
possible values of this field are:
neverDerefAliases: do not dereference aliases in searching
or in locating the base object of the search;
Wahl, et. al. Standards Track [Page 26]
RFC 2251 LDAPv3 December 1997
derefInSearching: dereference aliases in subordinates of
the base object in searching, but not in locating the
base object of the search;
derefFindingBaseObj: dereference aliases in locating
the base object of the search, but not when searching
subordinates of the base object;
derefAlways: dereference aliases both in searching and in
locating the base object of the search.
- sizelimit: A sizelimit that restricts the maximum number of entries
to be returned as a result of the search. A value of 0 in this
field indicates that no client-requested sizelimit restrictions are
in effect for the search. Servers may enforce a maximum number of
entries to return.
- timelimit: A timelimit that restricts the maximum time (in seconds)
allowed for a search. A value of 0 in this field indicates that no
client-requested timelimit restrictions are in effect for the
search.
- typesOnly: An indicator as to whether search results will contain
both attribute types and values, or just attribute types. Setting
this field to TRUE causes only attribute types (no values) to be
returned. Setting this field to FALSE causes both attribute types
and values to be returned.
- filter: A filter that defines the conditions that must be fulfilled
in order for the search to match a given entry.
The 'and', 'or' and 'not' choices can be used to form combinations of
filters. At least one filter element MUST be present in an 'and' or
'or' choice. The others match against individual attribute values of
entries in the scope of the search. (Implementor's note: the 'not'
filter is an example of a tagged choice in an implicitly-tagged
module. In BER this is treated as if the tag was explicit.)
A server MUST evaluate filters according to the three-valued logic
of X.511(93) section 7.8.1. In summary, a filter is evaluated to
either "TRUE", "FALSE" or "Undefined". If the filter evaluates
to TRUE for a particular entry, then the attributes of that entry
are returned as part of the search result (subject to any applicable
access control restrictions). If the filter evaluates to FALSE or
Undefined, then the entry is ignored for the search.
Wahl, et. al. Standards Track [Page 27]
RFC 2251 LDAPv3 December 1997
A filter of the "and" choice is TRUE if all the filters in the SET
OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
otherwise Undefined. A filter of the "or" choice is FALSE if all
of the filters in the SET OF evaluate to FALSE, TRUE if at least
one filter is TRUE, and Undefined otherwise. A filter of the "not"
choice is TRUE if the filter being negated is FALSE, FALSE if it is
TRUE, and Undefined if it is Undefined.
The present match evaluates to TRUE where there is an attribute or
subtype of the specified attribute description present in an entry,
and FALSE otherwise (including a presence test with an unrecognized
attribute description.)
The extensibleMatch is new in this version of LDAP. If the
matchingRule field is absent, the type field MUST be present, and
the equality match is performed for that type. If the type field is
absent and matchingRule is present, the matchValue is compared
against all attributes in an entry which support that matchingRule,
and the matchingRule determines the syntax for the assertion value
(the filter item evaluates to TRUE if it matches with at least
one attribute in the entry, FALSE if it does not match any attribute
in the entry, and Undefined if the matchingRule is not recognized
or the assertionValue cannot be parsed.) If the type field is
present and matchingRule is present, the matchingRule MUST be one
permitted for use with that type, otherwise the filter item is
undefined. If the dnAttributes field is set to TRUE, the match is
applied against all the attributes in an entry's distinguished name
as well, and also evaluates to TRUE if there is at least one
attribute in the distinguished name for which the filter item
evaluates to TRUE. (Editors note: The dnAttributes field is present
so that there does not need to be multiple versions of generic
matching rules such as for word matching, one to apply to entries
and another to apply to entries and dn attributes as well).
A filter item evaluates to Undefined when the server would not
be able to determine whether the assertion value matches an
entry. If an attribute description in an equalityMatch, substrings,
greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
filter is not recognized by the server, a matching rule id in the
extensibleMatch is not recognized by the server, the assertion
value cannot be parsed, or the type of filtering requested is not
implemented, then the filter is Undefined. Thus for example if a
server did not recognize the attribute type shoeSize, a filter of
(shoeSize=*) would evaluate to FALSE, and the filters (shoeSize=12),
(shoeSize>=12) and (shoeSize<=12) would evaluate to Undefined.
Wahl, et. al. Standards Track [Page 28]
RFC 2251 LDAPv3 December 1997
Servers MUST NOT return errors if attribute descriptions or matching
rule ids are not recognized, or assertion values cannot be parsed.
More details of filter processing are given in section 7.8 of X.511
[8].
- attributes: A list of the attributes to be returned from each entry
which matches the search filter. There are two special values which
may be used: an empty list with no attributes, and the attribute
description string "*". Both of these signify that all user
attributes are to be returned. (The "*" allows the client to
request all user attributes in addition to specific operational
attributes).
Attributes MUST be named at most once in the list, and are returned
at most once in an entry. If there are attribute descriptions in
the list which are not recognized, they are ignored by the server.
If the client does not want any attributes returned, it can specify
a list containing only the attribute with OID "1.1". This OID was
chosen arbitrarily and does not correspond to any attribute in use.
Client implementors should note that even if all user attributes are
requested, some attributes of the entry may not be included in
search results due to access control or other restrictions.
Furthermore, servers will not return operational attributes, such
as objectClasses or attributeTypes, unless they are listed by name,
since there may be extremely large number of values for certain
operational attributes. (A list of operational attributes for use
in LDAP is given in [5].)
Note that an X.500 "list"-like operation can be emulated by the client
requesting a one-level LDAP search operation with a filter checking
for the existence of the objectClass attribute, and that an X.500
"read"-like operation can be emulated by a base object LDAP search
operation with the same filter. A server which provides a gateway to
X.500 is not required to use the Read or List operations, although it
may choose to do so, and if it does must provide the same semantics
as the X.500 search operation.
4.5.2. Search Result
The results of the search attempted by the server upon receipt of a
Search Request are returned in Search Responses, which are LDAP
messages containing either SearchResultEntry, SearchResultReference,
ExtendedResponse or SearchResultDone data types.
SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
objectName LDAPDN,
Wahl, et. al. Standards Track [Page 29]
RFC 2251 LDAPv3 December 1997
attributes PartialAttributeList }
PartialAttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
-- implementors should note that the PartialAttributeList may
-- have zero elements (if none of the attributes of that entry
-- were requested, or could be returned), and that the vals set
-- may also have zero elements (if types only was requested, or
-- all values were excluded from the result.)
SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
-- at least one LDAPURL element must be present
SearchResultDone ::= [APPLICATION 5] LDAPResult
Upon receipt of a Search Request, a server will perform the necessary
search of the DIT.
If the LDAP session is operating over a connection-oriented transport
such as TCP, the server will return to the client a sequence of
responses in separate LDAP messages. There may be zero or more
responses containing SearchResultEntry, one for each entry found
during the search. There may also be zero or more responses
containing SearchResultReference, one for each area not explored by
this server during the search. The SearchResultEntry and
SearchResultReference PDUs may come in any order. Following all the
SearchResultReference responses and all SearchResultEntry responses
to be returned by the server, the server will return a response
containing the SearchResultDone, which contains an indication of
success, or detailing any errors that have occurred.
Each entry returned in a SearchResultEntry will contain all
attributes, complete with associated values if necessary, as
specified in the attributes field of the Search Request. Return of
attributes is subject to access control and other administrative
policy. Some attributes may be returned in binary format (indicated
by the AttributeDescription in the response having the binary option
present).
Some attributes may be constructed by the server and appear in a
SearchResultEntry attribute list, although they are not stored
attributes of an entry. Clients MUST NOT assume that all attributes
can be modified, even if permitted by access control.
LDAPMessage responses of the ExtendedResponse form are reserved for
returning information associated with a control requested by the
client. These may be defined in future versions of this document.
Wahl, et. al. Standards Track [Page 30]
RFC 2251 LDAPv3 December 1997
4.5.3. Continuation References in the Search Result
If the server was able to locate the entry referred to by the
baseObject but was unable to search all the entries in the scope at
and under the baseObject, the server may return one or more
SearchResultReference, each containing a reference to another set of
servers for continuing the operation. A server MUST NOT return any
SearchResultReference if it has not located the baseObject and
thus has not searched any entries; in this case it would return a
SearchResultDone containing a referral resultCode.
In the absence of indexing information provided to a server from
servers holding subordinate naming contexts, SearchResultReference
responses are not affected by search filters and are always returned
when in scope.
The SearchResultReference is of the same data type as the Referral.
URLs for servers implementing the LDAP protocol are written according
to [9]. The <dn> part MUST be present in the URL, with the new target
object name. The client MUST use this name in its next request.
Some servers (e.g. part of a distributed index exchange system) may
provide a different filter in the URLs of the SearchResultReference.
If the filter part of the URL is present in an LDAP URL, the client
MUST use the new filter in its next request to progress the search,
and if the filter part is absent the client will use again the same
filter. Other aspects of the new search request may be the same or
different as the search which generated the continuation references.
Other kinds of URLs may be returned so long as the operation could be
performed using that protocol.
The name of an unexplored subtree in a SearchResultReference need not
be subordinate to the base object.
In order to complete the search, the client MUST issue a new search
operation for each SearchResultReference that is returned. Note that
the abandon operation described in section 4.11 applies only to a
particular operation sent on a connection between a client and server,
and if the client has multiple outstanding search operations to
different servers, it MUST abandon each operation individually.
4.5.3.1. Example
For example, suppose the contacted server (hosta) holds the entry
"O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW". It knows that
either LDAP-capable servers (hostb) or (hostc) hold
"OU=People,O=MNN,C=WW" (one is the master and the other server a
Wahl, et. al. Standards Track [Page 31]
RFC 2251 LDAPv3 December 1997
shadow), and that LDAP-capable server (hostd) holds the subtree
"OU=Roles,O=MNN,C=WW". If a subtree search of "O=MNN,C=WW" is
requested to the contacted server, it may return the following:
SearchResultEntry for O=MNN,C=WW
SearchResultEntry for CN=Manager,O=MNN,C=WW
SearchResultReference {
ldap://hostb/OU=People,O=MNN,C=WW
ldap://hostc/OU=People,O=MNN,C=WW
}
SearchResultReference {
ldap://hostd/OU=Roles,O=MNN,C=WW
}
SearchResultDone (success)
Client implementors should note that when following a
SearchResultReference, additional SearchResultReference may be
generated. Continuing the example, if the client contacted the
server (hostb) and issued the search for the subtree
"OU=People,O=MNN,C=WW", the server might respond as follows:
SearchResultEntry for OU=People,O=MNN,C=WW
SearchResultReference {
ldap://hoste/OU=Managers,OU=People,O=MNN,C=WW
}
SearchResultReference {
ldap://hostf/OU=Consultants,OU=People,O=MNN,C=WW
}
SearchResultDone (success)
If the contacted server does not hold the base object for the search,
then it will return a referral to the client. For example, if the
client requests a subtree search of "O=XYZ,C=US" to hosta, the server
may return only a SearchResultDone containing a referral.
SearchResultDone (referral) {
ldap://hostg/
}
4.6. Modify Operation
The Modify Operation allows a client to request that a modification
of an entry be performed on its behalf by a server. The Modify
Request is defined as follows:
ModifyRequest ::= [APPLICATION 6] SEQUENCE {
object LDAPDN,
modification SEQUENCE OF SEQUENCE {
Wahl, et. al. Standards Track [Page 32]
RFC 2251 LDAPv3 December 1997
operation ENUMERATED {
add (0),
delete (1),
replace (2) },
modification AttributeTypeAndValues } }
AttributeTypeAndValues ::= SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
Parameters of the Modify Request are:
- object: The object to be modified. The value of this field contains
the DN of the entry to be modified. The server will not perform
any alias dereferencing in determining the object to be modified.
- modification: A list of modifications to be performed on the entry.
The entire list of entry modifications MUST be performed
in the order they are listed, as a single atomic operation. While
individual modifications may violate the directory schema, the
resulting entry after the entire list of modifications is performed
MUST conform to the requirements of the directory schema. The
values that may be taken on by the 'operation' field in each
modification construct have the following semantics respectively:
add: add values listed to the given attribute, creating
the attribute if necessary;
delete: delete values listed from the given attribute,
removing the entire attribute if no values are listed, or
if all current values of the attribute are listed for
deletion;
replace: replace all existing values of the given attribute
with the new values listed, creating the attribute if it
did not already exist. A replace with no value will delete
the entire attribute if it exists, and is ignored if the
attribute does not exist.
The result of the modify attempted by the server upon receipt of a
Modify Request is returned in a Modify Response, defined as follows:
ModifyResponse ::= [APPLICATION 7] LDAPResult
Upon receipt of a Modify Request, a server will perform the necessary
modifications to the DIT.
Wahl, et. al. Standards Track [Page 33]
RFC 2251 LDAPv3 December 1997
The server will return to the client a single Modify Response
indicating either the successful completion of the DIT modification,
or the reason that the modification failed. Note that due to the
requirement for atomicity in applying the list of modifications in
the Modify Request, the client may expect that no modifications of
the DIT have been performed if the Modify Response received indicates
any sort of error, and that all requested modifications have been
performed if the Modify Response indicates successful completion of
the Modify Operation. If the connection fails, whether the
modification occurred or not is indeterminate.
The Modify Operation cannot be used to remove from an entry any of
its distinguished values, those values which form the entry's
relative distinguished name. An attempt to do so will result in the
server returning the error notAllowedOnRDN. The Modify DN Operation
described in section 4.9 is used to rename an entry.
If an equality match filter has not been defined for an attribute type,
clients MUST NOT attempt to delete individual values of that attribute
from an entry using the "delete" form of a modification, and MUST
instead use the "replace" form.
Note that due to the simplifications made in LDAP, there is not a
direct mapping of the modifications in an LDAP ModifyRequest onto the
EntryModifications of a DAP ModifyEntry operation, and different
implementations of LDAP-DAP gateways may use different means of
representing the change. If successful, the final effect of the
operations on the entry MUST be identical.
4.7. Add Operation
The Add Operation allows a client to request the addition of an entry
into the directory. The Add Request is defined as follows:
AddRequest ::= [APPLICATION 8] SEQUENCE {
entry LDAPDN,
attributes AttributeList }
AttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
Parameters of the Add Request are:
- entry: the Distinguished Name of the entry to be added. Note that
the server will not dereference any aliases in locating the entry
to be added.
Wahl, et. al. Standards Track [Page 34]
RFC 2251 LDAPv3 December 1997
- attributes: the list of attributes that make up the content of the
entry being added. Clients MUST include distinguished values
(those forming the entry's own RDN) in this list, the objectClass
attribute, and values of any mandatory attributes of the listed
object classes. Clients MUST NOT supply the createTimestamp or
creatorsName attributes, since these will be generated
automatically by the server.
The entry named in the entry field of the AddRequest MUST NOT exist
for the AddRequest to succeed. The parent of the entry to be added
MUST exist. For example, if the client attempted to add
"CN=JS,O=Foo,C=US", the "O=Foo,C=US" entry did not exist, and the
"C=US" entry did exist, then the server would return the error
noSuchObject with the matchedDN field containing "C=US". If the
parent entry exists but is not in a naming context held by the
server, the server SHOULD return a referral to the server holding the
parent entry.
Servers implementations SHOULD NOT restrict where entries can be
located in the directory. Some servers MAY allow the administrator
to restrict the classes of entries which can be added to the
directory.
Upon receipt of an Add Request, a server will attempt to perform the
add requested. The result of the add attempt will be returned to the
client in the Add Response, defined as follows:
AddResponse ::= [APPLICATION 9] LDAPResult
A response of success indicates that the new entry is present in the
directory.
4.8. Delete Operation
The Delete Operation allows a client to request the removal of an
entry from the directory. The Delete Request is defined as follows:
DelRequest ::= [APPLICATION 10] LDAPDN
The Delete Request consists of the Distinguished Name of the entry to
be deleted. Note that the server will not dereference aliases while
resolving the name of the target entry to be removed, and that only
leaf entries (those with no subordinate entries) can be deleted with
this operation.
The result of the delete attempted by the server upon receipt of a
Delete Request is returned in the Delete Response, defined as
follows:
Wahl, et. al. Standards Track [Page 35]
RFC 2251 LDAPv3 December 1997
DelResponse ::= [APPLICATION 11] LDAPResult
Upon receipt of a Delete Request, a server will attempt to perform
the entry removal requested. The result of the delete attempt will be
returned to the client in the Delete Response.
4.9. Modify DN Operation
The Modify DN Operation allows a client to change the leftmost (least
significant) component of the name of an entry in the directory, or
to move a subtree of entries to a new location in the directory. The
Modify DN Request is defined as follows:
ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
entry LDAPDN,
newrdn RelativeLDAPDN,
deleteoldrdn BOOLEAN,
newSuperior [0] LDAPDN OPTIONAL }
Parameters of the Modify DN Request are:
- entry: the Distinguished Name of the entry to be changed. This
entry may or may not have subordinate entries.
- newrdn: the RDN that will form the leftmost component of the new
name of the entry.
- deleteoldrdn: a boolean parameter that controls whether the old RDN
attribute values are to be retained as attributes of the entry, or
deleted from the entry.
- newSuperior: if present, this is the Distinguished Name of the entry
which becomes the immediate superior of the existing entry.
The result of the name change attempted by the server upon receipt of
a Modify DN Request is returned in the Modify DN Response, defined
as follows:
ModifyDNResponse ::= [APPLICATION 13] LDAPResult
Upon receipt of a ModifyDNRequest, a server will attempt to
perform the name change. The result of the name change attempt will
be returned to the client in the Modify DN Response.
For example, if the entry named in the "entry" parameter was
"cn=John Smith,c=US", the newrdn parameter was "cn=John Cougar Smith",
and the newSuperior parameter was absent, then this operation would
Wahl, et. al. Standards Track [Page 36]
RFC 2251 LDAPv3 December 1997
attempt to rename the entry to be "cn=John Cougar Smith,c=US". If
there was already an entry with that name, the operation would fail
with error code entryAlreadyExists.
If the deleteoldrdn parameter is TRUE, the values forming the old
RDN are deleted from the entry. If the deleteoldrdn parameter is
FALSE, the values forming the old RDN will be retained as
non-distinguished attribute values of the entry. The server may
not perform the operation and return an error code if the setting of
the deleteoldrdn parameter would cause a schema inconsistency in the
entry.
Note that X.500 restricts the ModifyDN operation to only affect
entries that are contained within a single server. If the LDAP
server is mapped onto DAP, then this restriction will apply, and the
resultCode affectsMultipleDSAs will be returned if this error
occurred. In general clients MUST NOT expect to be able to perform
arbitrary movements of entries and subtrees between servers.
4.10. Compare Operation
The Compare Operation allows a client to compare an assertion
provided with an entry in the directory. The Compare Request is
defined as follows:
CompareRequest ::= [APPLICATION 14] SEQUENCE {
entry LDAPDN,
ava AttributeValueAssertion }
Parameters of the Compare Request are:
- entry: the name of the entry to be compared with.
- ava: the assertion with which an attribute in the entry is to be
compared.
The result of the compare attempted by the server upon receipt of a
Compare Request is returned in the Compare Response, defined as
follows:
CompareResponse ::= [APPLICATION 15] LDAPResult
Upon receipt of a Compare Request, a server will attempt to perform
the requested comparison. The result of the comparison will be
returned to the client in the Compare Response. Note that errors and
the result of comparison are all returned in the same construct.
Wahl, et. al. Standards Track [Page 37]
RFC 2251 LDAPv3 December 1997
Note that some directory systems may establish access controls which
permit the values of certain attributes (such as userPassword) to be
compared but not read. In a search result, it may be that an
attribute of that type would be returned, but with an empty set of
values.
4.11. Abandon Operation
The function of the Abandon Operation is to allow a client to request
that the server abandon an outstanding operation. The Abandon
Request is defined as follows:
AbandonRequest ::= [APPLICATION 16] MessageID
The MessageID MUST be that of a an operation which was requested
earlier in this connection.
(The abandon request itself has its own message id. This is distinct
from the id of the earlier operation being abandoned.)
There is no response defined in the Abandon Operation. Upon
transmission of an Abandon Operation, a client may expect that the
operation identified by the Message ID in the Abandon Request has
been abandoned. In the event that a server receives an Abandon
Request on a Search Operation in the midst of transmitting responses
to the search, that server MUST cease transmitting entry responses to
the abandoned request immediately, and MUST NOT send the
SearchResponseDone. Of course, the server MUST ensure that only
properly encoded LDAPMessage PDUs are transmitted.
Clients MUST NOT send abandon requests for the same operation
multiple times, and MUST also be prepared to receive results from
operations it has abandoned (since these may have been in transit
when the abandon was requested).
Servers MUST discard abandon requests for message IDs they do not
recognize, for operations which cannot be abandoned, and for
operations which have already been abandoned.
4.12. Extended Operation
An extension mechanism has been added in this version of LDAP, in
order to allow additional operations to be defined for services not
available elsewhere in this protocol, for instance digitally signed
operations and results.
Wahl, et. al. Standards Track [Page 38]
RFC 2251 LDAPv3 December 1997
The extended operation allows clients to make requests and receive
responses with predefined syntaxes and semantics. These may be
defined in RFCs or be private to particular implementations. Each
request MUST have a unique OBJECT IDENTIFIER assigned to it.
ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
requestName [0] LDAPOID,
requestValue [1] OCTET STRING OPTIONAL }
The requestName is a dotted-decimal representation of the OBJECT
IDENTIFIER corresponding to the request. The requestValue is
information in a form defined by that request, encapsulated inside an
OCTET STRING.
The server will respond to this with an LDAPMessage containing the
ExtendedResponse.
ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
COMPONENTS OF LDAPResult,
responseName [10] LDAPOID OPTIONAL,
response [11] OCTET STRING OPTIONAL }
If the server does not recognize the request name, it MUST return
only the response fields from LDAPResult, containing the
protocolError result code.
5. Protocol Element Encodings and Transfer
One underlying service is defined here. Clients and servers SHOULD
implement the mapping of LDAP over TCP described in 5.2.1.
5.1. Mapping Onto BER-based Transport Services
The protocol elements of LDAP are encoded for exchange using the
Basic Encoding Rules (BER) [11] of ASN.1 [3]. However, due to the
high overhead involved in using certain elements of the BER, the
following additional restrictions are placed on BER-encodings of LDAP
protocol elements:
(1) Only the definite form of length encoding will be used.
(2) OCTET STRING values will be encoded in the primitive form only.
(3) If the value of a BOOLEAN type is true, the encoding MUST have
its contents octets set to hex "FF".
Wahl, et. al. Standards Track [Page 39]
RFC 2251 LDAPv3 December 1997
(4) If a value of a type is its default value, it MUST be absent.
Only some BOOLEAN and INTEGER types have default values in this
protocol definition.
These restrictions do not apply to ASN.1 types encapsulated inside of
OCTET STRING values, such as attribute values, unless otherwise
noted.
5.2. Transfer Protocols
This protocol is designed to run over connection-oriented, reliable
transports, with all 8 bits in an octet being significant in the data
stream.
5.2.1. Transmission Control Protocol (TCP)
The LDAPMessage PDUs are mapped directly onto the TCP bytestream. It
is recommended that server implementations running over the TCP MAY
provide a protocol listener on the assigned port, 389. Servers may
instead provide a listener on a different port number. Clients MUST
support contacting servers on any valid TCP port.
6. Implementation Guidelines
This document describes an Internet protocol.
6.1. Server Implementations
The server MUST be capable of recognizing all the mandatory attribute
type names and implement the syntaxes specified in [5]. Servers MAY
also recognize additional attribute type names.
6.2. Client Implementations
Clients which request referrals MUST ensure that they do not loop
between servers. They MUST NOT repeatedly contact the same server for
the same request with the same target entry name, scope and filter.
Some clients may be using a counter that is incremented each time
referral handling occurs for an operation, and these kinds of clients
MUST be able to handle a DIT with at least ten layers of naming
contexts between the root and a leaf entry.
In the absence of prior agreements with servers, clients SHOULD NOT
assume that servers support any particular schemas beyond those
referenced in section 6.1. Different schemas can have different
attribute types with the same names. The client can retrieve the
subschema entries referenced by the subschemaSubentry attribute in
the server's root DSE or in entries held by the server.
Wahl, et. al. Standards Track [Page 40]
RFC 2251 LDAPv3 December 1997
7. Security Considerations
When used with a connection-oriented transport, this version of the
protocol provides facilities for the LDAP v2 authentication
mechanism, simple authentication using a cleartext password, as well
as any SASL mechanism [12]. SASL allows for integrity and privacy
services to be negotiated.
It is also permitted that the server can return its credentials to
the client, if it chooses to do so.
Use of cleartext password is strongly discouraged where the
underlying transport service cannot guarantee confidentiality and may
result in disclosure of the password to unauthorized parties.
When used with SASL, it should be noted that the name field of the
BindRequest is not protected against modification. Thus if the
distinguished name of the client (an LDAPDN) is agreed through the
negotiation of the credentials, it takes precedence over any value in
the unprotected name field.
Implementations which cache attributes and entries obtained via LDAP
MUST ensure that access controls are maintained if that information
is to be provided to multiple clients, since servers may have access
control policies which prevent the return of entries or attributes in
search results except to particular authenticated clients. For
example, caches could serve result information only to the client
whose request caused it to be cache.
8. Acknowledgements
This document is an update to RFC 1777, by Wengyik Yeong, Tim Howes,
and Steve Kille. Design ideas included in this document are based on
those discussed in ASID and other IETF Working Groups. The
contributions of individuals in these working groups is gratefully
acknowledged.
9. Bibliography
[1] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models
and Service", 1993.
[2] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
Protocol", RFC 1777, March 1995.
[3] ITU-T Rec. X.680, "Abstract Syntax Notation One (ASN.1) -
Specification of Basic Notation", 1994.
Wahl, et. al. Standards Track [Page 41]
RFC 2251 LDAPv3 December 1997
[4] Kille, S., Wahl, M., and T. Howes, "Lightweight Directory Access
Protocol (v3): UTF-8 String Representation of Distinguished
Names", RFC 2253, December 1997.
[5] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
Directory Access Protocol (v3): Attribute Syntax Definitions",
RFC 2252, December 1997.
[6] ITU-T Rec. X.501, "The Directory: Models", 1993.
[7] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
Resource Locators (URL)", RFC 1738, December 1994.
[8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
1993.
[9] Howes, T., and M. Smith, "The LDAP URL Format", RFC 2255,
December 1997.
[10] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
[11] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules: Basic,
Canonical, and Distinguished Encoding Rules", 1994.
[12] Meyers, J., "Simple Authentication and Security Layer",
RFC 2222, October 1997.
[13] Universal Multiple-Octet Coded Character Set (UCS) -
Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 :
1993.
[14] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO
10646", RFC 2044, October 1996.
10. Authors' Addresses
Mark Wahl
Critical Angle Inc.
4815 W Braker Lane #502-385
Austin, TX 78759
USA
Phone: +1 512 372-3160
EMail: M.Wahl@critical-angle.com
Wahl, et. al. Standards Track [Page 42]
RFC 2251 LDAPv3 December 1997
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd., MS MV068
Mountain View, CA 94043
USA
Phone: +1 650 937-3419
EMail: howes@netscape.com
Steve Kille
Isode Limited
The Dome, The Square
Richmond
TW9 1DT
UK
Phone: +44-181-332-9091
EMail: S.Kille@isode.com
Wahl, et. al. Standards Track [Page 43]
RFC 2251 LDAPv3 December 1997
Appendix A - Complete ASN.1 Definition
Lightweight-Directory-Access-Protocol-V3 DEFINITIONS
IMPLICIT TAGS ::=
BEGIN
LDAPMessage ::= SEQUENCE {
messageID MessageID,
protocolOp CHOICE {
bindRequest BindRequest,
bindResponse BindResponse,
unbindRequest UnbindRequest,
searchRequest SearchRequest,
searchResEntry SearchResultEntry,
searchResDone SearchResultDone,
searchResRef SearchResultReference,
modifyRequest ModifyRequest,
modifyResponse ModifyResponse,
addRequest AddRequest,
addResponse AddResponse,
delRequest DelRequest,
delResponse DelResponse,
modDNRequest ModifyDNRequest,
modDNResponse ModifyDNResponse,
compareRequest CompareRequest,
compareResponse CompareResponse,
abandonRequest AbandonRequest,
extendedReq ExtendedRequest,
extendedResp ExtendedResponse },
controls [0] Controls OPTIONAL }
MessageID ::= INTEGER (0 .. maxInt)
maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
LDAPString ::= OCTET STRING
LDAPOID ::= OCTET STRING
LDAPDN ::= LDAPString
RelativeLDAPDN ::= LDAPString
AttributeType ::= LDAPString
AttributeDescription ::= LDAPString
Wahl, et. al. Standards Track [Page 44]
RFC 2251 LDAPv3 December 1997
AttributeDescriptionList ::= SEQUENCE OF
AttributeDescription
AttributeValue ::= OCTET STRING
AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription,
assertionValue AssertionValue }
AssertionValue ::= OCTET STRING
Attribute ::= SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
MatchingRuleId ::= LDAPString
LDAPResult ::= SEQUENCE {
resultCode ENUMERATED {
success (0),
operationsError (1),
protocolError (2),
timeLimitExceeded (3),
sizeLimitExceeded (4),
compareFalse (5),
compareTrue (6),
authMethodNotSupported (7),
strongAuthRequired (8),
-- 9 reserved --
referral (10), -- new
adminLimitExceeded (11), -- new
unavailableCriticalExtension (12), -- new
confidentialityRequired (13), -- new
saslBindInProgress (14), -- new
noSuchAttribute (16),
undefinedAttributeType (17),
inappropriateMatching (18),
constraintViolation (19),
attributeOrValueExists (20),
invalidAttributeSyntax (21),
-- 22-31 unused --
noSuchObject (32),
aliasProblem (33),
invalidDNSyntax (34),
-- 35 reserved for undefined isLeaf --
aliasDereferencingProblem (36),
-- 37-47 unused --
inappropriateAuthentication (48),
Wahl, et. al. Standards Track [Page 45]
RFC 2251 LDAPv3 December 1997
invalidCredentials (49),
insufficientAccessRights (50),
busy (51),
unavailable (52),
unwillingToPerform (53),
loopDetect (54),
-- 55-63 unused --
namingViolation (64),
objectClassViolation (65),
notAllowedOnNonLeaf (66),
notAllowedOnRDN (67),
entryAlreadyExists (68),
objectClassModsProhibited (69),
-- 70 reserved for CLDAP --
affectsMultipleDSAs (71), -- new
-- 72-79 unused --
other (80) },
-- 81-90 reserved for APIs --
matchedDN LDAPDN,
errorMessage LDAPString,
referral [3] Referral OPTIONAL }
Referral ::= SEQUENCE OF LDAPURL
LDAPURL ::= LDAPString -- limited to characters permitted in URLs
Controls ::= SEQUENCE OF Control
Control ::= SEQUENCE {
controlType LDAPOID,
criticality BOOLEAN DEFAULT FALSE,
controlValue OCTET STRING OPTIONAL }
BindRequest ::= [APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication AuthenticationChoice }
AuthenticationChoice ::= CHOICE {
simple [0] OCTET STRING,
-- 1 and 2 reserved
sasl [3] SaslCredentials }
SaslCredentials ::= SEQUENCE {
mechanism LDAPString,
credentials OCTET STRING OPTIONAL }
BindResponse ::= [APPLICATION 1] SEQUENCE {
Wahl, et. al. Standards Track [Page 46]
RFC 2251 LDAPv3 December 1997
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
UnbindRequest ::= [APPLICATION 2] NULL
SearchRequest ::= [APPLICATION 3] SEQUENCE {
baseObject LDAPDN,
scope ENUMERATED {
baseObject (0),
singleLevel (1),
wholeSubtree (2) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3) },
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
typesOnly BOOLEAN,
filter Filter,
attributes AttributeDescriptionList }
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeDescription,
approxMatch [8] AttributeValueAssertion,
extensibleMatch [9] MatchingRuleAssertion }
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
-- at least one must be present
substrings SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString } }
MatchingRuleAssertion ::= SEQUENCE {
matchingRule [1] MatchingRuleId OPTIONAL,
type [2] AttributeDescription OPTIONAL,
matchValue [3] AssertionValue,
dnAttributes [4] BOOLEAN DEFAULT FALSE }
Wahl, et. al. Standards Track [Page 47]
RFC 2251 LDAPv3 December 1997
SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
objectName LDAPDN,
attributes PartialAttributeList }
PartialAttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
SearchResultDone ::= [APPLICATION 5] LDAPResult
ModifyRequest ::= [APPLICATION 6] SEQUENCE {
object LDAPDN,
modification SEQUENCE OF SEQUENCE {
operation ENUMERATED {
add (0),
delete (1),
replace (2) },
modification AttributeTypeAndValues } }
AttributeTypeAndValues ::= SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
ModifyResponse ::= [APPLICATION 7] LDAPResult
AddRequest ::= [APPLICATION 8] SEQUENCE {
entry LDAPDN,
attributes AttributeList }
AttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
AddResponse ::= [APPLICATION 9] LDAPResult
DelRequest ::= [APPLICATION 10] LDAPDN
DelResponse ::= [APPLICATION 11] LDAPResult
ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
entry LDAPDN,
newrdn RelativeLDAPDN,
deleteoldrdn BOOLEAN,
newSuperior [0] LDAPDN OPTIONAL }
ModifyDNResponse ::= [APPLICATION 13] LDAPResult
Wahl, et. al. Standards Track [Page 48]
RFC 2251 LDAPv3 December 1997
CompareRequest ::= [APPLICATION 14] SEQUENCE {
entry LDAPDN,
ava AttributeValueAssertion }
CompareResponse ::= [APPLICATION 15] LDAPResult
AbandonRequest ::= [APPLICATION 16] MessageID
ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
requestName [0] LDAPOID,
requestValue [1] OCTET STRING OPTIONAL }
ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
COMPONENTS OF LDAPResult,
responseName [10] LDAPOID OPTIONAL,
response [11] OCTET STRING OPTIONAL }
END
Wahl, et. al. Standards Track [Page 49]
RFC 2251 LDAPv3 December 1997
Full Copyright Statement
Copyright (C) The Internet Society (1997). 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 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.
Wahl, et. al. Standards Track [Page 50]
1.1 jakarta-james/www/rfclist/ldap/rfc2252.txt
Index: rfc2252.txt
===================================================================
Network Working Group M. Wahl
Request for Comments: 2252 Critical Angle Inc.
Category: Standards Track A. Coulbeck
Isode Inc.
T. Howes
Netscape Communications Corp.
S. Kille
Isode Limited
December 1997
Lightweight Directory Access Protocol (v3):
Attribute Syntax Definitions
1. Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG Note
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
Wahl, et. al. Standards Track [Page 1]
RFC 2252 LADPv3 Attributes December 1997
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
2. Abstract
The Lightweight Directory Access Protocol (LDAP) [1] requires that
the contents of AttributeValue fields in protocol elements be octet
strings. This document defines a set of syntaxes for LDAPv3, and the
rules by which attribute values of these syntaxes are represented as
octet strings for transmission in the LDAP protocol. The syntaxes
defined in this document are referenced by this and other documents
that define attribute types. This document also defines the set of
attribute types which LDAP servers should support.
3. Overview
This document defines the framework for developing schemas for
directories accessible via the Lightweight Directory Access Protocol.
Schema is the collection of attribute type definitions, object class
definitions and other information which a server uses to determine
how to match a filter or attribute value assertion (in a compare
operation) against the attributes of an entry, and whether to permit
add and modify operations.
Section 4 states the general requirements and notations for attribute
types, object classes, syntax and matching rule definitions.
Section 5 lists attributes, section 6 syntaxes and section 7 object
classes.
Additional documents define schemas for representing real-world
objects as directory entries.
Wahl, et. al. Standards Track [Page 2]
RFC 2252 LADPv3 Attributes December 1997
4. General Issues
This document describes encodings used in an Internet protocol.
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 RFC 2119 [4].
Attribute Type and Object Class definitions are written in a string
representation of the AttributeTypeDescription and
ObjectClassDescription data types defined in X.501(93) [3].
Implementors are strongly advised to first read the description of
how schema is represented in X.500 before reading the rest of this
document.
4.1. Common Encoding Aspects
For the purposes of defining the encoding rules for attribute
syntaxes, the following BNF definitions will be used. They are based
on the BNF styles of RFC 822 [13].
a = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" /
"j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" /
"s" / "t" / "u" / "v" / "w" / "x" / "y" / "z" / "A" /
"B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" /
"K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" / "S" /
"T" / "U" / "V" / "W" / "X" / "Y" / "Z"
d = "0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8" / "9"
hex-digit = d / "a" / "b" / "c" / "d" / "e" / "f" /
"A" / "B" / "C" / "D" / "E" / "F"
k = a / d / "-" / ";"
p = a / d / """ / "(" / ")" / "+" / "," /
"-" / "." / "/" / ":" / "?" / " "
letterstring = 1*a
numericstring = 1*d
anhstring = 1*k
keystring = a [ anhstring ]
printablestring = 1*p
Wahl, et. al. Standards Track [Page 3]
RFC 2252 LADPv3 Attributes December 1997
space = 1*" "
whsp = [ space ]
utf8 = <any sequence of octets formed from the UTF-8 [9]
transformation of a character from ISO10646 [10]>
dstring = 1*utf8
qdstring = whsp "'" dstring "'" whsp
qdstringlist = [ qdstring *( qdstring ) ]
qdstrings = qdstring / ( whsp "(" qdstringlist ")" whsp )
In the following BNF for the string representation of OBJECT
IDENTIFIERs, descr is the syntactic representation of an object
descriptor, which consists of letters and digits, starting with a
letter. An OBJECT IDENTIFIER in the numericoid format should not
have leading zeroes (e.g. "0.9.3" is permitted but "0.09.3" should
not be generated).
When encoding 'oid' elements in a value, the descr encoding option
SHOULD be used in preference to the numericoid. An object descriptor
is a more readable alias for a number OBJECT IDENTIFIER, and these
(where assigned and known by the implementation) SHOULD be used in
preference to numeric oids to the greatest extent possible. Examples
of object descriptors in LDAP are attribute type, object class and
matching rule names.
oid = descr / numericoid
descr = keystring
numericoid = numericstring *( "." numericstring )
woid = whsp oid whsp
; set of oids of either form
oids = woid / ( "(" oidlist ")" )
oidlist = woid *( "$" woid )
; object descriptors used as schema element names
qdescrs = qdescr / ( whsp "(" qdescrlist ")" whsp )
qdescrlist = [ qdescr *( qdescr ) ]
Wahl, et. al. Standards Track [Page 4]
RFC 2252 LADPv3 Attributes December 1997
qdescr = whsp "'" descr "'" whsp
4.2. Attribute Types
The attribute types are described by sample values for the subschema
"attributeTypes" attribute, which is written in the
AttributeTypeDescription syntax. While lines have been folded for
readability, the values transferred in protocol would not contain
newlines.
The AttributeTypeDescription is encoded according to the following
BNF, and the productions for oid, qdescrs and qdstring are given in
section 4.1. Implementors should note that future versions of this
document may have expanded this BNF to include additional terms.
Terms which begin with the characters "X-" are reserved for private
experiments, and MUST be followed by a <qdstrings>.
AttributeTypeDescription = "(" whsp
numericoid whsp ; AttributeType identifier
[ "NAME" qdescrs ] ; name used in AttributeType
[ "DESC" qdstring ] ; description
[ "OBSOLETE" whsp ]
[ "SUP" woid ] ; derived from this other
; AttributeType
[ "EQUALITY" woid ; Matching Rule name
[ "ORDERING" woid ; Matching Rule name
[ "SUBSTR" woid ] ; Matching Rule name
[ "SYNTAX" whsp noidlen whsp ] ; see section 4.3
[ "SINGLE-VALUE" whsp ] ; default multi-valued
[ "COLLECTIVE" whsp ] ; default not collective
[ "NO-USER-MODIFICATION" whsp ]; default user modifiable
[ "USAGE" whsp AttributeUsage ]; default userApplications
whsp ")"
AttributeUsage =
"userApplications" /
"directoryOperation" /
"distributedOperation" / ; DSA-shared
"dSAOperation" ; DSA-specific, value depends on server
Servers are not required to provide the same or any text in the
description part of the subschema values they maintain. Servers
SHOULD provide at least one of the "SUP" and "SYNTAX" fields for each
AttributeTypeDescription.
Servers MUST implement all the attribute types referenced in sections
5.1, 5.2 and 5.3.
Wahl, et. al. Standards Track [Page 5]
RFC 2252 LADPv3 Attributes December 1997
Servers MAY recognize additional names and attributes not listed in
this document, and if they do so, MUST publish the definitions of the
types in the attributeTypes attribute of their subschema entries.
Schema developers MUST NOT create attribute definitions whose names
conflict with attributes defined for use with LDAP in existing
standards-track RFCs.
An AttributeDescription can be used as the value in a NAME part of an
AttributeTypeDescription. Note that these are case insensitive.
Note that the AttributeTypeDescription does not list the matching
rules which can can be used with that attribute type in an
extensibleMatch search filter. This is done using the
matchingRuleUse attribute described in section 4.5.
This document refines the schema description of X.501 by requiring
that the syntax field in an AttributeTypeDescription be a string
representation of an OBJECT IDENTIFIER for the LDAP string syntax
definition, and an optional indication of the maximum length of a
value of this attribute (defined in section 4.3.2).
4.3. Syntaxes
This section defines general requirements for LDAP attribute value
syntax encodings. All documents defining attribute syntax encodings
for use with LDAP are expected to conform to these requirements.
The encoding rules defined for a given attribute syntax must produce
octet strings. To the greatest extent possible, encoded octet
strings should be usable in their native encoded form for display
purposes. In particular, encoding rules for attribute syntaxes
defining non-binary values should produce strings that can be
displayed with little or no translation by clients implementing LDAP.
There are a few cases (e.g. audio) however, when it is not sensible
to produce a printable representation, and clients MUST NOT assume
that an unrecognized syntax is a string representation.
In encodings where an arbitrary string, not a Distinguished Name, is
used as part of a larger production, and other than as part of a
Distinguished Name, a backslash quoting mechanism is used to escape
the following separator symbol character (such as "'", "$" or "#") if
it should occur in that string. The backslash is followed by a pair
of hexadecimal digits representing the next character. A backslash
itself in the string which forms part of a larger syntax is always
transmitted as '\5C' or '\5c'. An example is given in section 6.27.
Wahl, et. al. Standards Track [Page 6]
RFC 2252 LADPv3 Attributes December 1997
Syntaxes are also defined for matching rules whose assertion value
syntax is different from the attribute value syntax.
4.3.1 Binary Transfer of Values
This encoding format is used if the binary encoding is requested by
the client for an attribute, or if the attribute syntax name is
"1.3.6.1.4.1.1466.115.121.1.5". The contents of the LDAP
AttributeValue or AssertionValue field is a BER-encoded instance of
the attribute value or a matching rule assertion value ASN.1 data
type as defined for use with X.500. (The first byte inside the OCTET
STRING wrapper is a tag octet. However, the OCTET STRING is still
encoded in primitive form.)
All servers MUST implement this form for both generating attribute
values in search responses, and parsing attribute values in add,
compare and modify requests, if the attribute type is recognized and
the attribute syntax name is that of Binary. Clients which request
that all attributes be returned from entries MUST be prepared to
receive values in binary (e.g. userCertificate;binary), and SHOULD
NOT simply display binary or unrecognized values to users.
4.3.2. Syntax Object Identifiers
Syntaxes for use with LDAP are named by OBJECT IDENTIFIERs, which are
dotted-decimal strings. These are not intended to be displayed to
users.
noidlen = numericoid [ "{" len "}" ]
len = numericstring
The following table lists some of the syntaxes that have been defined
for LDAP thus far. The H-R column suggests whether a value in that
syntax would likely be a human readable string. Clients and servers
need not implement all the syntaxes listed here, and MAY implement
other syntaxes.
Other documents may define additional syntaxes. However, the
definition of additional arbitrary syntaxes is strongly deprecated
since it will hinder interoperability: today's client and server
implementations generally do not have the ability to dynamically
recognize new syntaxes. In most cases attributes will be defined
with the syntax for directory strings.
Wahl, et. al. Standards Track [Page 7]
RFC 2252 LADPv3 Attributes December 1997
Value being represented H-R OBJECT IDENTIFIER
=================================================================
ACI Item N 1.3.6.1.4.1.1466.115.121.1.1
Access Point Y 1.3.6.1.4.1.1466.115.121.1.2
Attribute Type Description Y 1.3.6.1.4.1.1466.115.121.1.3
Audio N 1.3.6.1.4.1.1466.115.121.1.4
Binary N 1.3.6.1.4.1.1466.115.121.1.5
Bit String Y 1.3.6.1.4.1.1466.115.121.1.6
Boolean Y 1.3.6.1.4.1.1466.115.121.1.7
Certificate N 1.3.6.1.4.1.1466.115.121.1.8
Certificate List N 1.3.6.1.4.1.1466.115.121.1.9
Certificate Pair N 1.3.6.1.4.1.1466.115.121.1.10
Country String Y 1.3.6.1.4.1.1466.115.121.1.11
DN Y 1.3.6.1.4.1.1466.115.121.1.12
Data Quality Syntax Y 1.3.6.1.4.1.1466.115.121.1.13
Delivery Method Y 1.3.6.1.4.1.1466.115.121.1.14
Directory String Y 1.3.6.1.4.1.1466.115.121.1.15
DIT Content Rule Description Y 1.3.6.1.4.1.1466.115.121.1.16
DIT Structure Rule Description Y 1.3.6.1.4.1.1466.115.121.1.17
DL Submit Permission Y 1.3.6.1.4.1.1466.115.121.1.18
DSA Quality Syntax Y 1.3.6.1.4.1.1466.115.121.1.19
DSE Type Y 1.3.6.1.4.1.1466.115.121.1.20
Enhanced Guide Y 1.3.6.1.4.1.1466.115.121.1.21
Facsimile Telephone Number Y 1.3.6.1.4.1.1466.115.121.1.22
Fax N 1.3.6.1.4.1.1466.115.121.1.23
Generalized Time Y 1.3.6.1.4.1.1466.115.121.1.24
Guide Y 1.3.6.1.4.1.1466.115.121.1.25
IA5 String Y 1.3.6.1.4.1.1466.115.121.1.26
INTEGER Y 1.3.6.1.4.1.1466.115.121.1.27
JPEG N 1.3.6.1.4.1.1466.115.121.1.28
LDAP Syntax Description Y 1.3.6.1.4.1.1466.115.121.1.54
LDAP Schema Definition Y 1.3.6.1.4.1.1466.115.121.1.56
LDAP Schema Description Y 1.3.6.1.4.1.1466.115.121.1.57
Master And Shadow Access Points Y 1.3.6.1.4.1.1466.115.121.1.29
Matching Rule Description Y 1.3.6.1.4.1.1466.115.121.1.30
Matching Rule Use Description Y 1.3.6.1.4.1.1466.115.121.1.31
Mail Preference Y 1.3.6.1.4.1.1466.115.121.1.32
MHS OR Address Y 1.3.6.1.4.1.1466.115.121.1.33
Modify Rights Y 1.3.6.1.4.1.1466.115.121.1.55
Name And Optional UID Y 1.3.6.1.4.1.1466.115.121.1.34
Name Form Description Y 1.3.6.1.4.1.1466.115.121.1.35
Numeric String Y 1.3.6.1.4.1.1466.115.121.1.36
Object Class Description Y 1.3.6.1.4.1.1466.115.121.1.37
Octet String Y 1.3.6.1.4.1.1466.115.121.1.40
OID Y 1.3.6.1.4.1.1466.115.121.1.38
Other Mailbox Y 1.3.6.1.4.1.1466.115.121.1.39
Postal Address Y 1.3.6.1.4.1.1466.115.121.1.41
Protocol Information Y 1.3.6.1.4.1.1466.115.121.1.42
Wahl, et. al. Standards Track [Page 8]
RFC 2252 LADPv3 Attributes December 1997
Presentation Address Y 1.3.6.1.4.1.1466.115.121.1.43
Printable String Y 1.3.6.1.4.1.1466.115.121.1.44
Substring Assertion Y 1.3.6.1.4.1.1466.115.121.1.58
Subtree Specification Y 1.3.6.1.4.1.1466.115.121.1.45
Supplier Information Y 1.3.6.1.4.1.1466.115.121.1.46
Supplier Or Consumer Y 1.3.6.1.4.1.1466.115.121.1.47
Supplier And Consumer Y 1.3.6.1.4.1.1466.115.121.1.48
Supported Algorithm N 1.3.6.1.4.1.1466.115.121.1.49
Telephone Number Y 1.3.6.1.4.1.1466.115.121.1.50
Teletex Terminal Identifier Y 1.3.6.1.4.1.1466.115.121.1.51
Telex Number Y 1.3.6.1.4.1.1466.115.121.1.52
UTC Time Y 1.3.6.1.4.1.1466.115.121.1.53
A suggested minimum upper bound on the number of characters in value
with a string-based syntax, or the number of bytes in a value for all
other syntaxes, may be indicated by appending this bound count inside
of curly braces following the syntax name's OBJECT IDENTIFIER in an
Attribute Type Description. This bound is not part of the syntax
name itself. For instance, "1.3.6.4.1.1466.0{64}" suggests that
server implementations should allow a string to be 64 characters
long, although they may allow longer strings. Note that a single
character of the Directory String syntax may be encoded in more than
one byte since UTF-8 is a variable-length encoding.
4.3.3. Syntax Description
The following BNF may be used to associate a short description with a
syntax OBJECT IDENTIFIER. Implementors should note that future
versions of this document may expand this definition to include
additional terms. Terms whose identifier begins with "X-" are
reserved for private experiments, and MUST be followed by a
<qdstrings>.
SyntaxDescription = "(" whsp
numericoid whsp
[ "DESC" qdstring ]
whsp ")"
4.4. Object Classes
The format for representation of object classes is defined in X.501
[3]. In general every entry will contain an abstract class ("top" or
"alias"), at least one structural object class, and zero or more
auxiliary object classes. Whether an object class is abstract,
structural or auxiliary is defined when the object class identifier
is assigned. An object class definition should not be changed
without having a new identifier assigned to it.
Wahl, et. al. Standards Track [Page 9]
RFC 2252 LADPv3 Attributes December 1997
Object class descriptions are written according to the following BNF.
Implementors should note that future versions of this document may
expand this definition to include additional terms. Terms whose
identifier begins with "X-" are reserved for private experiments, and
MUST be followed by a <qdstrings> encoding.
ObjectClassDescription = "(" whsp
numericoid whsp ; ObjectClass identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
[ "SUP" oids ] ; Superior ObjectClasses
[ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
; default structural
[ "MUST" oids ] ; AttributeTypes
[ "MAY" oids ] ; AttributeTypes
whsp ")"
These are described as sample values for the subschema
"objectClasses" attribute for a server which implements the LDAP
schema. While lines have been folded for readability, the values
transferred in protocol would not contain newlines.
Servers SHOULD implement all the object classes referenced in section
7, except for extensibleObject, which is optional. Servers MAY
implement additional object classes not listed in this document, and
if they do so, MUST publish the definitions of the classes in the
objectClasses attribute of their subschema entries.
Schema developers MUST NOT create object class definitions whose
names conflict with attributes defined for use with LDAP in existing
standards-track RFCs.
4.5. Matching Rules
Matching rules are used by servers to compare attribute values
against assertion values when performing Search and Compare
operations. They are also used to identify the value to be added or
deleted when modifying entries, and are used when comparing a
purported distinguished name with the name of an entry.
Most of the attributes given in this document will have an equality
matching rule defined.
Matching rule descriptions are written according to the following
BNF. Implementors should note that future versions of this document
may have expanded this BNF to include additional terms. Terms whose
identifier begins with "X-" are reserved for private experiments, and
Wahl, et. al. Standards Track [Page 10]
RFC 2252 LADPv3 Attributes December 1997
MUST be followed by a <qdstrings> encoding.
MatchingRuleDescription = "(" whsp
numericoid whsp ; MatchingRule identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
"SYNTAX" numericoid
whsp ")"
Values of the matchingRuleUse list the attributes which are suitable
for use with an extensible matching rule.
MatchingRuleUseDescription = "(" whsp
numericoid whsp ; MatchingRule identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" ]
"APPLIES" oids ; AttributeType identifiers
whsp ")"
Servers which support matching rules and the extensibleMatch SHOULD
implement all the matching rules in section 8.
Servers MAY implement additional matching rules not listed in this
document, and if they do so, MUST publish the definitions of the
matching rules in the matchingRules attribute of their subschema
entries. If the server supports the extensibleMatch, then the server
MUST publish the relationship between the matching rules and
attributes in the matchingRuleUse attribute.
For example, a server which implements a privately-defined matching
rule for performing sound-alike matches on Directory String-valued
attributes would include the following in the subschema entry
(1.2.3.4.5 is an example, the OID of an actual matching rule would be
different):
matchingRule: ( 1.2.3.4.5 NAME 'soundAlikeMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
If this matching rule could be used with the attributes 2.5.4.41 and
2.5.4.15, the following would also be present:
matchingRuleUse: ( 1.2.3.4.5 APPLIES (2.5.4.41 $ 2.5.4.15) )
Wahl, et. al. Standards Track [Page 11]
RFC 2252 LADPv3 Attributes December 1997
A client could then make use of this matching rule by sending a
search operation in which the filter is of the extensibleMatch
choice, the matchingRule field is "soundAlikeMatch", and the type
field is "2.5.4.41" or "2.5.4.15".
5. Attribute Types
All LDAP server implementations MUST recognize the attribute types
defined in this section.
Servers SHOULD also recognize all the attributes from section 5 of
[12].
5.1. Standard Operational Attributes
Servers MUST maintain values of these attributes in accordance with
the definitions in X.501(93).
5.1.1. createTimestamp
This attribute SHOULD appear in entries which were created using the
Add operation.
( 2.5.18.1 NAME 'createTimestamp' EQUALITY generalizedTimeMatch
ORDERING generalizedTimeOrderingMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
5.1.2. modifyTimestamp
This attribute SHOULD appear in entries which have been modified
using the Modify operation.
( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY generalizedTimeMatch
ORDERING generalizedTimeOrderingMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
5.1.3. creatorsName
This attribute SHOULD appear in entries which were created using the
Add operation.
( 2.5.18.3 NAME 'creatorsName' EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
Wahl, et. al. Standards Track [Page 12]
RFC 2252 LADPv3 Attributes December 1997
5.1.4. modifiersName
This attribute SHOULD appear in entries which have been modified
using the Modify operation.
( 2.5.18.4 NAME 'modifiersName' EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation )
5.1.5. subschemaSubentry
The value of this attribute is the name of a subschema entry (or
subentry if the server is based on X.500(93)) in which the server
makes available attributes specifying the schema.
( 2.5.18.10 NAME 'subschemaSubentry'
EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION
SINGLE-VALUE USAGE directoryOperation )
5.1.6. attributeTypes
This attribute is typically located in the subschema entry.
( 2.5.21.5 NAME 'attributeTypes'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
5.1.7. objectClasses
This attribute is typically located in the subschema entry.
( 2.5.21.6 NAME 'objectClasses'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
5.1.8. matchingRules
This attribute is typically located in the subschema entry.
( 2.5.21.4 NAME 'matchingRules'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.30 USAGE directoryOperation )
Wahl, et. al. Standards Track [Page 13]
RFC 2252 LADPv3 Attributes December 1997
5.1.9. matchingRuleUse
This attribute is typically located in the subschema entry.
( 2.5.21.8 NAME 'matchingRuleUse'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.31 USAGE directoryOperation )
5.2. LDAP Operational Attributes
These attributes are only present in the root DSE (see [1] and [3]).
Servers MUST recognize these attribute names, but it is not required
that a server provide values for these attributes, when the attribute
corresponds to a feature which the server does not implement.
5.2.1. namingContexts
The values of this attribute correspond to naming contexts which this
server masters or shadows. If the server does not master any
information (e.g. it is an LDAP gateway to a public X.500 directory)
this attribute will be absent. If the server believes it contains
the entire directory, the attribute will have a single value, and
that value will be the empty string (indicating the null DN of the
root). This attribute will allow a client to choose suitable base
objects for searching when it has contacted a server.
( 1.3.6.1.4.1.1466.101.120.5 NAME 'namingContexts'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 USAGE dSAOperation )
5.2.2. altServer
The values of this attribute are URLs of other servers which may be
contacted when this server becomes unavailable. If the server does
not know of any other servers which could be used this attribute will
be absent. Clients may cache this information in case their preferred
LDAP server later becomes unavailable.
( 1.3.6.1.4.1.1466.101.120.6 NAME 'altServer'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 USAGE dSAOperation )
5.2.3. supportedExtension
The values of this attribute are OBJECT IDENTIFIERs identifying the
supported extended operations which the server supports.
If the server does not support any extensions this attribute will be
absent.
Wahl, et. al. Standards Track [Page 14]
RFC 2252 LADPv3 Attributes December 1997
( 1.3.6.1.4.1.1466.101.120.7 NAME 'supportedExtension'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation )
5.2.4. supportedControl
The values of this attribute are the OBJECT IDENTIFIERs identifying
controls which the server supports. If the server does not support
any controls, this attribute will be absent.
( 1.3.6.1.4.1.1466.101.120.13 NAME 'supportedControl'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation )
5.2.5. supportedSASLMechanisms
The values of this attribute are the names of supported SASL
mechanisms which the server supports. If the server does not support
any mechanisms this attribute will be absent.
( 1.3.6.1.4.1.1466.101.120.14 NAME 'supportedSASLMechanisms'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE dSAOperation )
5.2.6. supportedLDAPVersion
The values of this attribute are the versions of the LDAP protocol
which the server implements.
( 1.3.6.1.4.1.1466.101.120.15 NAME 'supportedLDAPVersion'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 USAGE dSAOperation )
5.3. LDAP Subschema Attribute
This attribute is typically located in the subschema entry.
5.3.1. ldapSyntaxes
Servers MAY use this attribute to list the syntaxes which are
implemented. Each value corresponds to one syntax.
( 1.3.6.1.4.1.1466.101.120.16 NAME 'ldapSyntaxes'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.54 USAGE directoryOperation )
5.4. X.500 Subschema attributes
These attributes are located in the subschema entry. All servers
SHOULD recognize their name, although typically only X.500 servers
will implement their functionality.
Wahl, et. al. Standards Track [Page 15]
RFC 2252 LADPv3 Attributes December 1997
5.4.1. dITStructureRules
( 2.5.21.1 NAME 'dITStructureRules' EQUALITY integerFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.17 USAGE directoryOperation )
5.4.2. nameForms
( 2.5.21.7 NAME 'nameForms'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.35 USAGE directoryOperation )
5.4.3. ditContentRules
( 2.5.21.2 NAME 'dITContentRules'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.16 USAGE directoryOperation )
6. Syntaxes
Servers SHOULD recognize all the syntaxes described in this section.
6.1. Attribute Type Description
( 1.3.6.1.4.1.1466.115.121.1.3 DESC 'Attribute Type Description' )
Values in this syntax are encoded according to the BNF given at the
start of section 4.2. For example,
( 2.5.4.0 NAME 'objectClass'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
6.2. Binary
( 1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary' )
Values in this syntax are encoded as described in section 4.3.1.
6.3. Bit String
( 1.3.6.1.4.1.1466.115.121.1.6 DESC 'Bit String' )
Values in this syntax are encoded according to the following BNF:
bitstring = "'" *binary-digit "'B"
binary-digit = "0" / "1"
Wahl, et. al. Standards Track [Page 16]
RFC 2252 LADPv3 Attributes December 1997
Example:
'0101111101'B
6.4. Boolean
( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' )
Values in this syntax are encoded according to the following BNF:
boolean = "TRUE" / "FALSE"
Boolean values have an encoding of "TRUE" if they are logically true,
and have an encoding of "FALSE" otherwise.
6.5. Certificate
( 1.3.6.1.4.1.1466.115.121.1.8 DESC 'Certificate' )
Because of the changes from X.509(1988) and X.509(1993) and
additional changes to the ASN.1 definition to support certificate
extensions, no string representation is defined, and values in this
syntax MUST only be transferred using the binary encoding, by
requesting or returning the attributes with descriptions
"userCertificate;binary" or "caCertificate;binary". The BNF notation
in RFC 1778 for "User Certificate" is not recommended to be used.
6.6. Certificate List
( 1.3.6.1.4.1.1466.115.121.1.9 DESC 'Certificate List' )
Because of the incompatibility of the X.509(1988) and X.509(1993)
definitions of revocation lists, values in this syntax MUST only be
transferred using a binary encoding, by requesting or returning the
attributes with descriptions "certificateRevocationList;binary" or
"authorityRevocationList;binary". The BNF notation in RFC 1778 for
"Authority Revocation List" is not recommended to be used.
6.7. Certificate Pair
( 1.3.6.1.4.1.1466.115.121.1.10 DESC 'Certificate Pair' )
Because the Certificate is being carried in binary, values in this
syntax MUST only be transferred using a binary encoding, by
requesting or returning the attribute description
"crossCertificatePair;binary". The BNF notation in RFC 1778 for
"Certificate Pair" is not recommended to be used.
Wahl, et. al. Standards Track [Page 17]
RFC 2252 LADPv3 Attributes December 1997
6.8. Country String
( 1.3.6.1.4.1.1466.115.121.1.11 DESC 'Country String' )
A value in this syntax is encoded the same as a value of Directory
String syntax. Note that this syntax is limited to values of exactly
two printable string characters, as listed in ISO 3166 [14].
CountryString = p p
Example:
US
6.9. DN
( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' )
Values in the Distinguished Name syntax are encoded to have the
representation defined in [5]. Note that this representation is not
reversible to an ASN.1 encoding used in X.500 for Distinguished
Names, as the CHOICE of any DirectoryString element in an RDN is no
longer known.
Examples (from [5]):
CN=Steve Kille,O=Isode Limited,C=GB
OU=Sales+CN=J. Smith,O=Widget Inc.,C=US
CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB
CN=Before\0DAfter,O=Test,C=GB
1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB
SN=Lu\C4\8Di\C4\87
6.10. Directory String
( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' )
A string in this syntax is encoded in the UTF-8 form of ISO 10646 (a
superset of Unicode). Servers and clients MUST be prepared to
receive encodings of arbitrary Unicode characters, including
characters not presently assigned to any character set.
For characters in the PrintableString form, the value is encoded as
the string value itself.
If it is of the TeletexString form, then the characters are
transliterated to their equivalents in UniversalString, and encoded
in UTF-8 [9].
Wahl, et. al. Standards Track [Page 18]
RFC 2252 LADPv3 Attributes December 1997
If it is of the UniversalString or BMPString forms [10], UTF-8 is
used to encode them.
Note: the form of DirectoryString is not indicated in protocol unless
the attribute value is carried in binary. Servers which convert to
DAP MUST choose an appropriate form. Servers MUST NOT reject values
merely because they contain legal Unicode characters outside of the
range of printable ASCII.
Example:
This is a string of DirectoryString containing #!%#@
6.11. DIT Content Rule Description
( 1.3.6.1.4.1.1466.115.121.1.16 DESC 'DIT Content Rule Description' )
Values in this syntax are encoded according to the following BNF.
Implementors should note that future versions of this document may
have expanded this BNF to include additional terms.
DITContentRuleDescription = "("
numericoid ; Structural ObjectClass identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" ]
[ "AUX" oids ] ; Auxiliary ObjectClasses
[ "MUST" oids ] ; AttributeType identifiers
[ "MAY" oids ] ; AttributeType identifiers
[ "NOT" oids ] ; AttributeType identifiers
")"
6.12. Facsimile Telephone Number
( 1.3.6.1.4.1.1466.115.121.1.22 DESC 'Facsimile Telephone Number' )
Values in this syntax are encoded according to the following BNF:
fax-number = printablestring [ "$" faxparameters ]
faxparameters = faxparm / ( faxparm "$" faxparameters )
faxparm = "twoDimensional" / "fineResolution" /
"unlimitedLength" /
"b4Length" / "a3Width" / "b4Width" / "uncompressed"
Wahl, et. al. Standards Track [Page 19]
RFC 2252 LADPv3 Attributes December 1997
In the above, the first printablestring is the telephone number,
based on E.123 [15], and the faxparm tokens represent fax parameters.
6.13. Fax
( 1.3.6.1.4.1.1466.115.121.1.23 DESC 'Fax' )
Values in this syntax are encoded as if they were octet strings
containing Group 3 Fax images as defined in [7].
6.14. Generalized Time
( 1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' )
Values in this syntax are encoded as printable strings, represented
as specified in X.208. Note that the time zone must be specified.
It is strongly recommended that GMT time be used. For example,
199412161032Z
6.15. IA5 String
( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' )
The encoding of a value in this syntax is the string value itself.
6.16. INTEGER
( 1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER' )
Values in this syntax are encoded as the decimal representation of
their values, with each decimal digit represented by the its
character equivalent. So the number 1321 is represented by the
character string "1321".
6.17. JPEG
( 1.3.6.1.4.1.1466.115.121.1.28 DESC 'JPEG' )
Values in this syntax are encoded as strings containing JPEG images
in the JPEG File Interchange Format (JFIF), as described in [8].
6.18. Matching Rule Description
( 1.3.6.1.4.1.1466.115.121.1.30 DESC 'Matching Rule Description' )
Values of type matchingRules are encoded as strings according to the
BNF given in section 4.5.
Wahl, et. al. Standards Track [Page 20]
RFC 2252 LADPv3 Attributes December 1997
6.19. Matching Rule Use Description
( 1.3.6.1.4.1.1466.115.121.1.31 DESC 'Matching Rule Use Description'
)
Values of type matchingRuleUse are encoded as strings according to
the BNF given in section 4.5.
6.20. MHS OR Address
( 1.3.6.1.4.1.1466.115.121.1.33 DESC 'MHS OR Address' )
Values in this syntax are encoded as strings, according to the format
defined in [11].
6.21. Name And Optional UID
( 1.3.6.1.4.1.1466.115.121.1.34 DESC 'Name And Optional UID' )
Values in this syntax are encoded according to the following BNF:
NameAndOptionalUID = DistinguishedName [ "#" bitstring ]
Although the '#' character may occur in a string representation of a
distinguished name, no additional special quoting is done. This
syntax has been added subsequent to RFC 1778.
Example:
1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB#'0101'B
6.22. Name Form Description
( 1.3.6.1.4.1.1466.115.121.1.35 DESC 'Name Form Description' )
Values in this syntax are encoded according to the following BNF.
Implementors should note that future versions of this document may
have expanded this BNF to include additional terms.
NameFormDescription = "(" whsp
numericoid whsp ; NameForm identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
"OC" woid ; Structural ObjectClass
"MUST" oids ; AttributeTypes
[ "MAY" oids ] ; AttributeTypes
whsp ")"
Wahl, et. al. Standards Track [Page 21]
RFC 2252 LADPv3 Attributes December 1997
6.23. Numeric String
( 1.3.6.1.4.1.1466.115.121.1.36 DESC 'Numeric String' )
The encoding of a string in this syntax is the string value itself.
Example:
1997
6.24. Object Class Description
( 1.3.6.1.4.1.1466.115.121.1.37 DESC 'Object Class Description' )
Values in this syntax are encoded according to the BNF in section
4.4.
6.25. OID
( 1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' )
Values in the Object Identifier syntax are encoded according to
the BNF in section 4.1 for "oid".
Example:
1.2.3.4
cn
6.26. Other Mailbox
( 1.3.6.1.4.1.1466.115.121.1.39 DESC 'Other Mailbox' )
Values in this syntax are encoded according to the following BNF:
otherMailbox = mailbox-type "$" mailbox
mailbox-type = printablestring
mailbox = <an encoded IA5 String>
In the above, mailbox-type represents the type of mail system in
which the mailbox resides, for example "MCIMail"; and mailbox is the
actual mailbox in the mail system defined by mailbox-type.
6.27. Postal Address
( 1.3.6.1.4.1.1466.115.121.1.41 DESC 'Postal Address' )
Wahl, et. al. Standards Track [Page 22]
RFC 2252 LADPv3 Attributes December 1997
Values in this syntax are encoded according to the following BNF:
postal-address = dstring *( "$" dstring )
In the above, each dstring component of a postal address value is
encoded as a value of type Directory String syntax. Backslashes and
dollar characters, if they occur in the component, are quoted as
described in section 4.3. Many servers limit the postal address to
six lines of up to thirty characters.
Example:
1234 Main St.$Anytown, CA 12345$USA
\241,000,000 Sweepstakes$PO Box 1000000$Anytown, CA 12345$USA
6.28. Presentation Address
( 1.3.6.1.4.1.1466.115.121.1.43 DESC 'Presentation Address' )
Values in this syntax are encoded with the representation described
in RFC 1278 [6].
6.29. Printable String
( 1.3.6.1.4.1.1466.115.121.1.44 DESC 'Printable String' )
The encoding of a value in this syntax is the string value itself.
PrintableString is limited to the characters in production p of
section 4.1.
Example:
This is a PrintableString
6.30. Telephone Number
( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' )
Values in this syntax are encoded as if they were Printable String
types. Telephone numbers are recommended in X.520 to be in
international form, as described in E.123 [15].
Example:
+1 512 305 0280
Wahl, et. al. Standards Track [Page 23]
RFC 2252 LADPv3 Attributes December 1997
6.31. UTC Time
( 1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' )
Values in this syntax are encoded as if they were printable strings
with the strings containing a UTCTime value. This is historical; new
attribute definitions SHOULD use GeneralizedTime instead.
6.32. LDAP Syntax Description
( 1.3.6.1.4.1.1466.115.121.1.54 DESC 'LDAP Syntax Description' )
Values in this syntax are encoded according to the BNF in section
4.3.3.
6.33. DIT Structure Rule Description
( 1.3.6.1.4.1.1466.115.121.1.17 DESC 'DIT Structure Rule Description'
)
Values with this syntax are encoded according to the following BNF:
DITStructureRuleDescription = "(" whsp
ruleidentifier whsp ; DITStructureRule identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
"FORM" woid whsp ; NameForm
[ "SUP" ruleidentifiers whsp ] ; superior DITStructureRules
")"
ruleidentifier = integer
ruleidentifiers = ruleidentifier |
"(" whsp ruleidentifierlist whsp ")"
ruleidentifierlist = [ ruleidentifier *( ruleidentifier ) ]
7. Object Classes
Servers SHOULD recognize all the names of standard classes from
section 7 of [12].
7.1. Extensible Object Class
The extensibleObject object class, if present in an entry, permits
that entry to optionally hold any attribute. The MAY attribute list
of this class is implicitly the set of all attributes.
Wahl, et. al. Standards Track [Page 24]
RFC 2252 LADPv3 Attributes December 1997
( 1.3.6.1.4.1.1466.101.120.111 NAME 'extensibleObject'
SUP top AUXILIARY )
The mandatory attributes of the other object classes of this entry
are still required to be present.
Note that not all servers will implement this object class, and those
which do not will reject requests to add entries which contain this
object class, or modify an entry to add this object class.
7.2. subschema
This object class is used in the subschema entry.
( 2.5.20.1 NAME 'subschema' AUXILIARY
MAY ( dITStructureRules $ nameForms $ ditContentRules $
objectClasses $ attributeTypes $ matchingRules $
matchingRuleUse ) )
The ldapSyntaxes operational attribute may also be present in
subschema entries.
8. Matching Rules
Servers which implement the extensibleMatch filter SHOULD allow all
the matching rules listed in this section to be used in the
extensibleMatch. In general these servers SHOULD allow matching
rules to be used with all attribute types known to the server, when
the assertion syntax of the matching rule is the same as the value
syntax of the attribute.
Servers MAY implement additional matching rules.
8.1. Matching Rules used in Equality Filters
Servers SHOULD be capable of performing the following matching rules.
For all these rules, the assertion syntax is the same
1.1 jakarta-james/www/rfclist/ldap/rfc2253.txt
Index: rfc2253.txt
===================================================================
Network Working Group M. Wahl
Request for Comments: 2253 Critical Angle Inc.
Obsoletes: 1779 S. Kille
Category: Standards Track Isode Ltd.
T. Howes
Netscape Communications Corp.
December 1997
Lightweight Directory Access Protocol (v3):
UTF-8 String Representation of Distinguished Names
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG Note
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Wahl, et. al. Proposed Standard [Page 1]
RFC 2253 LADPv3 Distinguished Names December 1997
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
Abstract
The X.500 Directory uses distinguished names as the primary keys to
entries in the directory. Distinguished Names are encoded in ASN.1
in the X.500 Directory protocols. In the Lightweight Directory
Access Protocol, a string representation of distinguished names is
transferred. This specification defines the string format for
representing names, which is designed to give a clean representation
of commonly used distinguished names, while being able to represent
any distinguished name.
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 RFC 2119 [6].
1. Background
This specification assumes familiarity with X.500 [1], and the
concept of Distinguished Name. It is important to have a common
format to be able to unambiguously represent a distinguished name.
The primary goal of this specification is ease of encoding and
decoding. A secondary goal is to have names that are human readable.
It is not expected that LDAP clients with a human user interface
would display these strings directly to the user, but would most
likely be performing translations (such as expressing attribute type
names in one of the local national languages).
2. Converting DistinguishedName from ASN.1 to a String
In X.501 [2] the ASN.1 structure of distinguished name is defined as:
DistinguishedName ::= RDNSequence
RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
Wahl, et. al. Proposed Standard [Page 2]
RFC 2253 LADPv3 Distinguished Names December 1997
RelativeDistinguishedName ::= SET SIZE (1..MAX) OF
AttributeTypeAndValue
AttributeTypeAndValue ::= SEQUENCE {
type AttributeType,
value AttributeValue }
The following sections define the algorithm for converting from an
ASN.1 structured representation to a UTF-8 string representation.
2.1. Converting the RDNSequence
If the RDNSequence is an empty sequence, the result is the empty or
zero length string.
Otherwise, the output consists of the string encodings of each
RelativeDistinguishedName in the RDNSequence (according to 2.2),
starting with the last element of the sequence and moving backwards
toward the first.
The encodings of adjoining RelativeDistinguishedNames are separated
by a comma character (',' ASCII 44).
2.2. Converting RelativeDistinguishedName
When converting from an ASN.1 RelativeDistinguishedName to a string,
the output consists of the string encodings of each
AttributeTypeAndValue (according to 2.3), in any order.
Where there is a multi-valued RDN, the outputs from adjoining
AttributeTypeAndValues are separated by a plus ('+' ASCII 43)
character.
2.3. Converting AttributeTypeAndValue
The AttributeTypeAndValue is encoded as the string representation of
the AttributeType, followed by an equals character ('=' ASCII 61),
followed by the string representation of the AttributeValue. The
encoding of the AttributeValue is given in section 2.4.
If the AttributeType is in a published table of attribute types
associated with LDAP [4], then the type name string from that table
is used, otherwise it is encoded as the dotted-decimal encoding of
the AttributeType's OBJECT IDENTIFIER. The dotted-decimal notation is
described in [3]. As an example, strings for a few of the attribute
types frequently seen in RDNs include:
Wahl, et. al. Proposed Standard [Page 3]
RFC 2253 LADPv3 Distinguished Names December 1997
String X.500 AttributeType
------------------------------
CN commonName
L localityName
ST stateOrProvinceName
O organizationName
OU organizationalUnitName
C countryName
STREET streetAddress
DC domainComponent
UID userid
2.4. Converting an AttributeValue from ASN.1 to a String
If the AttributeValue is of a type which does not have a string
representation defined for it, then it is simply encoded as an
octothorpe character ('#' ASCII 35) followed by the hexadecimal
representation of each of the bytes of the BER encoding of the X.500
AttributeValue. This form SHOULD be used if the AttributeType is of
the dotted-decimal form.
Otherwise, if the AttributeValue is of a type which has a string
representation, the value is converted first to a UTF-8 string
according to its syntax specification (see for example section 6 of
[4]).
If the UTF-8 string does not have any of the following characters
which need escaping, then that string can be used as the string
representation of the value.
o a space or "#" character occurring at the beginning of the
string
o a space character occurring at the end of the string
o one of the characters ",", "+", """, "\", "<", ">" or ";"
Implementations MAY escape other characters.
If a character to be escaped is one of the list shown above, then it
is prefixed by a backslash ('\' ASCII 92).
Otherwise the character to be escaped is replaced by a backslash and
two hex digits, which form a single byte in the code of the
character.
Examples of the escaping mechanism are shown in section 5.
Wahl, et. al. Proposed Standard [Page 4]
RFC 2253 LADPv3 Distinguished Names December 1997
3. Parsing a String back to a Distinguished Name
The structure of the string is specified in a BNF grammar, based on
the grammar defined in RFC 822 [5]. Server implementations parsing a
DN string generated by an LDAPv2 client MUST also accept (and ignore)
the variants given in section 4 of this document.
distinguishedName = [name] ; may be empty string
name = name-component *("," name-component)
name-component = attributeTypeAndValue *("+" attributeTypeAndValue)
attributeTypeAndValue = attributeType "=" attributeValue
attributeType = (ALPHA 1*keychar) / oid
keychar = ALPHA / DIGIT / "-"
oid = 1*DIGIT *("." 1*DIGIT)
attributeValue = string
string = *( stringchar / pair )
/ "#" hexstring
/ QUOTATION *( quotechar / pair ) QUOTATION ; only from v2
quotechar = <any character except "\" or QUOTATION >
special = "," / "=" / "+" / "<" / ">" / "#" / ";"
pair = "\" ( special / "\" / QUOTATION / hexpair )
stringchar = <any character except one of special, "\" or QUOTATION >
hexstring = 1*hexpair
hexpair = hexchar hexchar
hexchar = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
/ "a" / "b" / "c" / "d" / "e" / "f"
ALPHA = <any ASCII alphabetic character>
; (decimal 65-90 and 97-122)
DIGIT = <any ASCII decimal digit> ; (decimal 48-57)
QUOTATION = <the ASCII double quotation mark character '"' decimal 34>
Wahl, et. al. Proposed Standard [Page 5]
RFC 2253 LADPv3 Distinguished Names December 1997
4. Relationship with RFC 1779 and LDAPv2
The syntax given in this document is more restrictive than the syntax
in RFC 1779. Implementations parsing a string generated by an LDAPv2
client MUST accept the syntax of RFC 1779. Implementations MUST NOT,
however, generate any of the RFC 1779 encodings which are not
described above in section 2.
Implementations MUST allow a semicolon character to be used instead
of a comma to separate RDNs in a distinguished name, and MUST also
allow whitespace characters to be present on either side of the comma
or semicolon. The whitespace characters are ignored, and the
semicolon replaced with a comma.
Implementations MUST allow an oid in the attribute type to be
prefixed by one of the character strings "oid." or "OID.".
Implementations MUST allow for space (' ' ASCII 32) characters to be
present between name-component and ',', between attributeTypeAndValue
and '+', between attributeType and '=', and between '=' and
attributeValue. These space characters are ignored when parsing.
Implementations MUST allow a value to be surrounded by quote ('"'
ASCII 34) characters, which are not part of the value. Inside the
quoted value, the following characters can occur without any
escaping:
",", "=", "+", "<", ">", "#" and ";"
5. Examples
This notation is designed to be convenient for common forms of name.
This section gives a few examples of distinguished names written
using this notation. First is a name containing three relative
distinguished names (RDNs):
CN=Steve Kille,O=Isode Limited,C=GB
Here is an example name containing three RDNs, in which the first RDN
is multi-valued:
OU=Sales+CN=J. Smith,O=Widget Inc.,C=US
This example shows the method of quoting of a comma in an
organization name:
CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB
Wahl, et. al. Proposed Standard [Page 6]
RFC 2253 LADPv3 Distinguished Names December 1997
An example name in which a value contains a carriage return
character:
CN=Before\0DAfter,O=Test,C=GB
An example name in which an RDN was of an unrecognized type. The
value is the BER encoding of an OCTET STRING containing two bytes
0x48 and 0x69.
1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB
Finally, an example of an RDN surname value consisting of 5 letters:
Unicode Letter Description 10646 code UTF-8 Quoted
=============================== ========== ====== =======
LATIN CAPITAL LETTER L U0000004C 0x4C L
LATIN SMALL LETTER U U00000075 0x75 u
LATIN SMALL LETTER C WITH CARON U0000010D 0xC48D \C4\8D
LATIN SMALL LETTER I U00000069 0x69 i
LATIN SMALL LETTER C WITH ACUTE U00000107 0xC487 \C4\87
Could be written in printable ASCII (useful for debugging purposes):
SN=Lu\C4\8Di\C4\87
6. References
[1] The Directory -- overview of concepts, models and services.
ITU-T Rec. X.500(1993).
[2] The Directory -- Models. ITU-T Rec. X.501(1993).
[3] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
Directory Access Protocol (v3): Attribute Syntax Definitions",
RFC 2252, December 1997.
[5] Crocker, D., "Standard of the Format of ARPA-Internet Text
Messages", STD 11, RFC 822, August 1982.
[6] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119.
Wahl, et. al. Proposed Standard [Page 7]
RFC 2253 LADPv3 Distinguished Names December 1997
7. Security Considerations
7.1. Disclosure
Distinguished Names typically consist of descriptive information
about the entries they name, which can be people, organizations,
devices or other real-world objects. This frequently includes some
of the following kinds of information:
- the common name of the object (i.e. a person's full name)
- an email or TCP/IP address
- its physical location (country, locality, city, street address)
- organizational attributes (such as department name or affiliation)
Most countries have privacy laws regarding the publication of
information about people.
7.2. Use of Distinguished Names in Security Applications
The transformations of an AttributeValue value from its X.501 form to
an LDAP string representation are not always reversible back to the
same BER or DER form. An example of a situation which requires the
DER form of a distinguished name is the verification of an X.509
certificate.
For example, a distinguished name consisting of one RDN with one AVA,
in which the type is commonName and the value is of the TeletexString
choice with the letters 'Sam' would be represented in LDAP as the
string CN=Sam. Another distinguished name in which the value is
still 'Sam' but of the PrintableString choice would have the same
representation CN=Sam.
Applications which require the reconstruction of the DER form of the
value SHOULD NOT use the string representation of attribute syntaxes
when converting a distinguished name to the LDAP format. Instead,
they SHOULD use the hexadecimal form prefixed by the octothorpe ('#')
as described in the first paragraph of section 2.4.
8. Authors' Addresses
Mark Wahl
Critical Angle Inc.
4815 W. Braker Lane #502-385
Austin, TX 78759
USA
EMail: M.Wahl@critical-angle.com
Wahl, et. al. Proposed Standard [Page 8]
RFC 2253 LADPv3 Distinguished Names December 1997
Steve Kille
Isode Ltd.
The Dome
The Square
Richmond, Surrey
TW9 1DT
England
Phone: +44-181-332-9091
EMail: S.Kille@ISODE.COM
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd, MS MV068
Mountain
1.1 jakarta-james/www/rfclist/ldap/rfc2254.txt
Index: rfc2254.txt
===================================================================
Network Working Group T. Howes
Request for Comments: 2254 Netscape Communications Corp.
Category: Standards Track December 1997
The String Representation of LDAP Search Filters
1. Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG Note
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Howes Standards Track [Page 1]
RFC 2254 String Representation of LDAP December 1997
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
2. Abstract
The Lightweight Directory Access Protocol (LDAP) [1] defines a
network representation of a search filter transmitted to an LDAP
server. Some applications may find it useful to have a common way of
representing these search filters in a human-readable form. This
document defines a human-readable string format for representing LDAP
search filters.
This document replaces RFC 1960, extending the string LDAP filter
definition to include support for LDAP version 3 extended match
filters, and including support for representing the full range of
possible LDAP search filters.
Howes Standards Track [Page 2]
RFC 2254 String Representation of LDAP December 1997
3. LDAP Search Filter Definition
An LDAPv3 search filter is defined in Section 4.5.1 of [1] as
follows:
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeDescription,
approxMatch [8] AttributeValueAssertion,
extensibleMatch [9] MatchingRuleAssertion
}
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString
}
}
AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription,
attributeValue AttributeValue
}
MatchingRuleAssertion ::= SEQUENCE {
matchingRule [1] MatchingRuleID OPTIONAL,
type [2] AttributeDescription OPTIONAL,
matchValue [3] AssertionValue,
dnAttributes [4] BOOLEAN DEFAULT FALSE
}
AttributeDescription ::= LDAPString
AttributeValue ::= OCTET STRING
MatchingRuleID ::= LDAPString
AssertionValue ::= OCTET STRING
LDAPString ::= OCTET STRING
Howes Standards Track [Page 3]
RFC 2254 String Representation of LDAP December 1997
where the LDAPString above is limited to the UTF-8 encoding of the
ISO 10646 character set [4]. The AttributeDescription is a string
representation of the attribute description and is defined in [1].
The AttributeValue and AssertionValue OCTET STRING have the form
defined in [2]. The Filter is encoded for transmission over a
network using the Basic Encoding Rules defined in [3], with
simplifications described in [1].
4. String Search Filter Definition
The string representation of an LDAP search filter is defined by the
following grammar, following the ABNF notation defined in [5]. The
filter format uses a prefix notation.
filter = "(" filtercomp ")"
filtercomp = and / or / not / item
and = "&" filterlist
or = "|" filterlist
not = "!" filter
filterlist = 1*filter
item = simple / present / substring / extensible
simple = attr filtertype value
filtertype = equal / approx / greater / less
equal = "="
approx = "~="
greater = ">="
less = "<="
extensible = attr [":dn"] [":" matchingrule] ":=" value
/ [":dn"] ":" matchingrule ":=" value
present = attr "=*"
substring = attr "=" [initial] any [final]
initial = value
any = "*" *(value "*")
final = value
attr = AttributeDescription from Section 4.1.5 of [1]
matchingrule = MatchingRuleId from Section 4.1.9 of [1]
value = AttributeValue from Section 4.1.6 of [1]
The attr, matchingrule, and value constructs are as described in the
corresponding section of [1] given above.
Howes Standards Track [Page 4]
RFC 2254 String Representation of LDAP December 1997
If a value should contain any of the following characters
Character ASCII value
---------------------------
* 0x2a
( 0x28
) 0x29
\ 0x5c
NUL 0x00
the character must be encoded as the backslash '\' character (ASCII
0x5c) followed by the two hexadecimal digits representing the ASCII
value of the encoded character. The case of the two hexadecimal
digits is not significant.
This simple escaping mechanism eliminates filter-parsing ambiguities
and allows any filter that can be represented in LDAP to be
represented as a NUL-terminated string. Other characters besides the
ones listed above may be escaped using this mechanism, for example,
non-printing characters.
For example, the filter checking whether the "cn" attribute contained
a value with the character "*" anywhere in it would be represented as
"(cn=*\2a*)".
Note that although both the substring and present productions in the
grammar above can produce the "attr=*" construct, this construct is
used only to denote a presence filter.
5. Examples
This section gives a few examples of search filters written using
this notation.
(cn=Babs Jensen)
(!(cn=Tim Howes))
(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
(o=univ*of*mich*)
The following examples illustrate the use of extensible matching.
(cn:1.2.3.4.5:=Fred Flintstone)
(sn:dn:2.4.6.8.10:=Barney Rubble)
(o:dn:=Ace Industry)
(:dn:2.4.6.8.10:=Dino)
Howes Standards Track [Page 5]
RFC 2254 String Representation of LDAP December 1997
The second example illustrates the use of the ":dn" notation to
indicate that matching rule "2.4.6.8.10" should be used when making
comparisons, and that the attributes of an entry's distinguished name
should be considered part of the entry when evaluating the match.
The third example denotes an equality match, except that DN
components should be considered part of the entry when doing the
match.
The fourth example is a filter that should be applied to any
attribute supporting the matching rule given (since the attr has been
left off). Attributes supporting the matching rule contained in the
DN should also be considered.
The following examples illustrate the use of the escaping mechanism.
(o=Parens R Us \28for all your parenthetical needs\29)
(cn=*\2A*)
(filename=C:\5cMyFile)
(bin=\00\00\00\04)
(sn=Lu\c4\8di\c4\87)
The first example shows the use of the escaping mechanism to
represent parenthesis characters. The second shows how to represent a
"*" in a value, preventing it from being interpreted as a substring
indicator. The third illustrates the escaping of the backslash
character.
The fourth example shows a filter searching for the four-byte value
0x00000004, illustrating the use of the escaping mechanism to
represent arbitrary data, including NUL characters.
The final example illustrates the use of the escaping mechanism to
represent various non-ASCII UTF-8 characters.
6. Security Considerations
This memo describes a string representation of LDAP search filters.
While the representation itself has no known security implications,
LDAP search filters do. They are interpreted by LDAP servers to
select entries from which data is retrieved. LDAP servers should
take care to protect the data they maintain from unauthorized access.
Howes Standards Track [Page 6]
RFC 2254 String Representation of LDAP December 1997
7. References
[1] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[2] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
Directory Access Protocol (v3): Attribute Syntax Definitions", RFC
2252, December 1997.
[3] Specification of ASN.1 encoding rules: Basic, Canonical, and
Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994.
[4] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO
10646", RFC 2044, October 1996.
[5] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, August 1982.
8. Author's Address
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Road
Mountain View, CA 94043
USA
Phone: +1 415 937-3419
EMail: howes@netscape.com
Howes Standards Track [Page 7]
RFC 2254 String Representation of LDAP December 1997
9. Full Copyright Statement
Copyright (C) The Internet Society (1997). 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 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.
Howes Standards Track [Page 8]
1.1 jakarta-james/www/rfclist/ldap/rfc2255.txt
Index: rfc2255.txt
===================================================================
Network Working Group T. Howes
Request for Comments: 2255 M. Smith
Category: Standards Track Netscape Communications Corp.
December 1997
The LDAP URL Format
1. Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG NOTE
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Howes & Smith Standards Track [Page 1]
RFC 2255 LDAP URL Format December 1997
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
2. Abstract
LDAP is the Lightweight Directory Access Protocol, defined in [1],
[2] and [3]. This document describes a format for an LDAP Uniform
Resource Locator. The format describes an LDAP search operation to
perform to retrieve information from an LDAP directory. This document
replaces RFC 1959. It updates the LDAP URL format for version 3 of
LDAP and clarifies how LDAP URLs are resolved. This document also
defines an extension mechanism for LDAP URLs, so that future
documents can extend their functionality, for example, to provide
access to new LDAPv3 extensions as they are defined.
The key words "MUST", "MAY", and "SHOULD" used in this document are
to be interpreted as described in [6].
Howes & Smith Standards Track [Page 2]
RFC 2255 LDAP URL Format December 1997
3. URL Definition
An LDAP URL begins with the protocol prefix "ldap" and is defined by
the following grammar.
ldapurl = scheme "://" [hostport] ["/"
[dn ["?" [attributes] ["?" [scope]
["?" [filter] ["?" extensions]]]]]]
scheme = "ldap"
attributes = attrdesc *("," attrdesc)
scope = "base" / "one" / "sub"
dn = distinguishedName from Section 3 of [1]
hostport = hostport from Section 5 of RFC 1738 [5]
attrdesc = AttributeDescription from Section 4.1.5 of [2]
filter = filter from Section 4 of [4]
extensions = extension *("," extension)
extension = ["!"] extype ["=" exvalue]
extype = token / xtoken
exvalue = LDAPString from section 4.1.2 of [2]
token = oid from section 4.1 of [3]
xtoken = ("X-" / "x-") token
The "ldap" prefix indicates an entry or entries residing in the LDAP
server running on the given hostname at the given portnumber. The
default LDAP port is TCP port 389. If no hostport is given, the
client must have some apriori knowledge of an appropriate LDAP server
to contact.
The dn is an LDAP Distinguished Name using the string format
described in [1]. It identifies the base object of the LDAP search.
ldapurl = scheme "://" [hostport] ["/"
[dn ["?" [attributes] ["?" [scope]
["?" [filter] ["?" extensions]]]]]]
scheme = "ldap"
attributes = attrdesc *("," attrdesc)
scope = "base" / "one" / "sub"
dn = distinguishedName from Section 3 of [1]
hostport = hostport from Section 5 of RFC 1738 [5]
attrdesc = AttributeDescription from Section 4.1.5 of [2]
filter = filter from Section 4 of [4]
extensions = extension *("," extension)
extension = ["!"] extype ["=" exvalue]
extype = token / xtoken
exvalue = LDAPString from section 4.1.2 of [2]
token = oid from section 4.1 of [3]
xtoken = ("X-" / "x-") token
Howes & Smith Standards Track [Page 3]
RFC 2255 LDAP URL Format December 1997
The "ldap" prefix indicates an entry or entries residing in the LDAP
server running on the given hostname at the given portnumber. The
default LDAP port is TCP port 389. If no hostport is given, the
client must have some apriori knowledge of an appropriate LDAP server
to contact.
The dn is an LDAP Distinguished Name using the string format
described in [1]. It identifies the base object of the LDAP search.
The attributes construct is used to indicate which attributes should
be returned from the entry or entries. Individual attrdesc names are
as defined for AttributeDescription in [2]. If the attributes part
is omitted, all user attributes of the entry or entries should be
requested (e.g., by setting the attributes field
AttributeDescriptionList in the LDAP search request to a NULL list,
or (in LDAPv3) by requesting the special attribute name "*").
The scope construct is used to specify the scope of the search to
perform in the given LDAP server. The allowable scopes are "base"
for a base object search, "one" for a one-level search, or "sub" for
a subtree search. If scope is omitted, a scope of "base" is assumed.
The filter is used to specify the search filter to apply to entries
within the specified scope during the search. It has the format
specified in [4]. If filter is omitted, a filter of
"(objectClass=*)" is assumed.
The extensions construct provides the LDAP URL with an extensibility
mechanism, allowing the capabilities of the URL to be extended in the
future. Extensions are a simple comma-separated list of type=value
pairs, where the =value portion MAY be omitted for options not
requiring it. Each type=value pair is a separate extension. These
LDAP URL extensions are not necessarily related to any of the LDAPv3
extension mechanisms. Extensions may be supported or unsupported by
the client resolving the URL. An extension prefixed with a '!'
character (ASCII 33) is critical. An extension not prefixed with a '
!' character is non-critical.
If an extension is supported by the client, the client MUST obey the
extension if the extension is critical. The client SHOULD obey
supported extensions that are non-critical.
If an extension is unsupported by the client, the client MUST NOT
process the URL if the extension is critical. If an unsupported
extension is non-critical, the client MUST ignore the extension.
Howes & Smith Standards Track [Page 4]
RFC 2255 LDAP URL Format December 1997
If a critical extension cannot be processed successfully by the
client, the client MUST NOT process the URL. If a non-critical
extension cannot be processed successfully by the client, the client
SHOULD ignore the extension.
Extension types prefixed by "X-" or "x-" are reserved for use in
bilateral agreements between communicating parties. Other extension
types MUST be defined in this document, or in other standards-track
documents.
One LDAP URL extension is defined in this document in the next
section. Other documents or a future version of this document MAY
define other extensions.
Note that any URL-illegal characters (e.g., spaces), URL special
characters (as defined in section 2.2 of RFC 1738) and the reserved
character '?' (ASCII 63) occurring inside a dn, filter, or other
element of an LDAP URL MUST be escaped using the % method described
in RFC 1738 [5]. If a comma character ',' occurs inside an extension
value, the character MUST also be escaped using the % method.
4. The Bindname Extension
This section defines an LDAP URL extension for representing the
distinguished name for a client to use when authenticating to an LDAP
directory during resolution of an LDAP URL. Clients MAY implement
this extension.
The extension type is "bindname". The extension value is the
distinguished name of the directory entry to authenticate as, in the
same form as described for dn in the grammar above. The dn may be the
NULL string to specify unauthenticated access. The extension may be
either critical (prefixed with a '!' character) or non-critical (not
prefixed with a '!' character).
If the bindname extension is critical, the client resolving the URL
MUST authenticate to the directory using the given distinguished name
and an appropriate authentication method. Note that for a NULL
distinguished name, no bind MAY be required to obtain anonymous
access to the directory. If the extension is non-critical, the client
MAY bind to the directory using the given distinguished name.
5. URL Processing
This section describes how an LDAP URL SHOULD be resolved by a
client.
Howes & Smith Standards Track [Page 5]
RFC 2255 LDAP URL Format December 1997
First, the client obtains a connection to the LDAP server referenced
in the URL, or an LDAP server of the client's choice if no LDAP
server is explicitly referenced. This connection MAY be opened
specifically for the purpose of resolving the URL or the client MAY
reuse an already open connection. The connection MAY provide
confidentiality, integrity, or other services, e.g., using TLS. Use
of security services is at the client's discretion if not specified
in the URL.
Next, the client authenticates itself to the LDAP server. This step
is optional, unless the URL contains a critical bindname extension
with a non-NULL value. If a bindname extension is given, the client
proceeds according to the section above.
If a bindname extension is not specified, the client MAY bind to the
directory using a appropriate dn and authentication method of its own
choosing (including NULL authentication).
Next, the client performs the LDAP search operation specified in the
URL. Additional fields in the LDAP protocol search request, such as
sizelimit, timelimit, deref, and anything else not specified or
defaulted in the URL specification, MAY be set at the client's
discretion.
Once the search has completed, the client MAY close the connection to
the LDAP server, or the client MAY keep the connection open for
future use.
6. Examples
The following are some example LDAP URLs using the format defined
above. The first example is an LDAP URL referring to the University
of Michigan entry, available from an LDAP server of the client's
choosing:
ldap:///o=University%20of%20Michigan,c=US
The next example is an LDAP URL referring to the University of
Michigan entry in a particular ldap server:
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
Both of these URLs correspond to a base object search of the
"o=University of Michigan, c=US" entry using a filter of
"(objectclass=*)", requesting all attributes.
The next example is an LDAP URL referring to only the postalAddress
attribute of the University of Michigan entry:
Howes & Smith Standards Track [Page 6]
RFC 2255 LDAP URL Format December 1997
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,
c=US?postalAddress
The corresponding LDAP search operation is the same as in the
previous example, except that only the postalAddress attribute is
requested.
The next example is an LDAP URL referring to the set of entries found
by querying the given LDAP server on port 6666 and doing a subtree
search of the University of Michigan for any entry with a common name
of "Babs Jensen", retrieving all attributes:
ldap://host.com:6666/o=University%20of%20Michigan,
c=US??sub?(cn=Babs%20Jensen)
The next example is an LDAP URL referring to all children of the c=GB
entry:
ldap://ldap.itd.umich.edu/c=GB?objectClass?one
The objectClass attribute is requested to be returned along with the
entries, and the default filter of "(objectclass=*)" is used.
The next example is an LDAP URL to retrieve the mail attribute for
the LDAP entry named "o=Question?,c=US" is given below, illustrating
the use of the escaping mechanism on the reserved character '?'.
ldap://ldap.question.com/o=Question%3f,c=US?mail
The next example illustrates the interaction between LDAP and URL
quoting mechanisms.
ldap://ldap.netscape.com/o=Babsco,c=US??(int=%5c00%5c00%5c00%5c04)
The filter in this example uses the LDAP escaping mechanism of \ to
encode three zero or null bytes in the value. In LDAP, the filter
would be written as (int=\00\00\00\04). Because the \ character must
be escaped in a URL, the \'s are escaped as %5c in the URL encoding.
The final example shows the use of the bindname extension to specify
the dn a client should use for authentication when resolving the URL.
ldap:///??sub??bindname=cn=Manager%2co=Foo
ldap:///??sub??!bindname=cn=Manager%2co=Foo
The two URLs are the same, except that the second one marks the
bindname extension as critical. Notice the use of the % encoding
method to encode the comma in the distinguished name value in the
Howes & Smith Standards Track [Page 7]
RFC 2255 LDAP URL Format December 1997
bindname extension.
7. Security Considerations
General URL security considerations discussed in [5] are relevant for
LDAP URLs.
The use of security mechanisms when processing LDAP URLs requires
particular care, since clients may encounter many different servers
via URLs, and since URLs are likely to be processed automatically,
without user intervention. A client SHOULD have a user-configurable
policy about which servers to connect to using which security
mechanisms, and SHOULD NOT make connections that are inconsistent
with this policy.
Sending authentication information, no matter the mechanism, may
violate a user's privacy requirements. In the absence of specific
policy permitting authentication information to be sent to a server,
a client should use an anonymous connection. (Note that clients
conforming to previous LDAP URL specifications, where all connections
are anonymous and unprotected, are consistent with this
specification; they simply have the default security policy.)
Some authentication methods, in particular reusable passwords sent to
the server, may reveal
1.1 jakarta-james/www/rfclist/ldap/rfc2256.txt
Index: rfc2256.txt
===================================================================
Network Working Group M. Wahl
Request for Comments: 2256 Critical Angle Inc.
Category: Standards Track December 1997
A Summary of the X.500(96) User Schema for use with LDAPv3
1. Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
IESG Note
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation of
any satisfactory authentication mechanisms.
In accordance with RFC 2026, section 4.4.1, this specification is
being approved by IESG as a Proposed Standard despite this
limitation, for the following reasons:
a. to encourage implementation and interoperability testing of
these protocols (with or without update access) before they
are deployed, and
b. to encourage deployment and use of these protocols in read-only
applications. (e.g. applications where LDAPv3 is used as
a query language for directories which are updated by some
secure mechanism other than LDAP), and
c. to avoid delaying the advancement and deployment of other Internet
standards-track protocols which require the ability to query, but
not update, LDAPv3 directory servers.
Readers are hereby warned that until mandatory authentication
mechanisms are standardized, clients and servers written according to
this specification which make use of update functionality are
UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
Wahl Standards Track [Page 1]
RFC 2256 LDAPv3 Schema December 1997
Implementors are hereby discouraged from deploying LDAPv3 clients or
servers which implement the update functionality, until a Proposed
Standard for mandatory authentication in LDAPv3 has been approved and
published as an RFC.
2. Abstract
This document provides an overview of the attribute types and object
classes defined by the ISO and ITU-T committees in the X.500
documents, in particular those intended for use by directory clients.
This is the most widely used schema for LDAP/X.500 directories, and
many other schema definitions for white pages objects use it as a
basis. This document does not cover attributes used for the
administration of X.500 directory servers, nor does it include
attributes defined by other ISO/ITU-T documents.
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 RFC 2119 [6].
3. General Issues
This document references syntaxes given in section 6 of this document
and section 6 of [1]. Matching rules are listed in section 8 of this
document and section 8 of [1].
The attribute type and object class definitions are written using the
BNF form of AttributeTypeDescription and ObjectClassDescription given
in [1]. Lines have been folded for readability.
4. Source
The schema definitions in this document are based on those found in
X.500 [2],[3],[4],[5], and updates to these documents, specifically:
Sections Source
============ ============
5.1 - 5.2 X.501(93)
5.3 - 5.36 X.520(88)
5.37 - 5.41 X.509(93)
5.42 - 5.52 X.520(93)
5.53 - 5.54 X.509(96)
5.55 X.520(96)
6.1 RFC 1274
6.2 (new syntax)
6.3 - 6.6 RFC 1274
7.1 - 7.2 X.501(93)
7.3 - 7.18 X.521(93)
Wahl Standards Track [Page 2]
RFC 2256 LDAPv3 Schema December 1997
7.19 - 7.21 X.509(96)
7.22 X.521(96)
Some attribute names are different from those found in X.520(93).
Three new attributes supportedAlgorithms, deltaRevocationList and
dmdName, and the objectClass dmd, are defined in the X.500(96)
documents.
5. Attribute Types
An LDAP server implementation SHOULD recognize the attribute types
described in this section.
5.1. objectClass
The values of the objectClass attribute describe the kind of object
which an entry represents. The objectClass attribute is present in
every entry, with at least two values. One of the values is either
"top" or "alias".
( 2.5.4.0 NAME 'objectClass' EQUALITY objectIdentifierMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
5.2. aliasedObjectName
The aliasedObjectName attribute is used by the directory service if
the entry containing this attribute is an alias.
( 2.5.4.1 NAME 'aliasedObjectName' EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE )
5.3. knowledgeInformation
This attribute is no longer used.
( 2.5.4.2 NAME 'knowledgeInformation' EQUALITY caseIgnoreMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
5.4. cn
This is the X.500 commonName attribute, which contains a name of an
object. If the object corresponds to a person, it is typically the
person's full name.
( 2.5.4.3 NAME 'cn' SUP name )
Wahl Standards Track [Page 3]
RFC 2256 LDAPv3 Schema December 1997
5.5. sn
This is the X.500 surname attribute, which contains the family name
of a person.
( 2.5.4.4 NAME 'sn' SUP name )
5.6. serialNumber
This attribute contains the serial number of a device.
( 2.5.4.5 NAME 'serialNumber' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{64} )
5.7. c
This attribute contains a two-letter ISO 3166 country code
(countryName).
( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
5.8. l
This attribute contains the name of a locality, such as a city,
county or other geographic region (localityName).
( 2.5.4.7 NAME 'l' SUP name )
5.9. st
This attribute contains the full name of a state or province
(stateOrProvinceName).
( 2.5.4.8 NAME 'st' SUP name )
5.10. street
This attribute contains the physical address of the object to which
the entry corresponds, such as an address for package delivery
(streetAddress).
( 2.5.4.9 NAME 'street' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} )
Wahl Standards Track [Page 4]
RFC 2256 LDAPv3 Schema December 1997
5.11. o
This attribute contains the name of an organization
(organizationName).
( 2.5.4.10 NAME 'o' SUP name )
5.12. ou
This attribute contains the name of an organizational unit
(organizationalUnitName).
( 2.5.4.11 NAME 'ou' SUP name )
5.13. title
This attribute contains the title, such as "Vice President", of a
person in their organizational context. The "personalTitle"
attribute would be used for a person's title independent of their job
function.
( 2.5.4.12 NAME 'title' SUP name )
5.14. description
This attribute contains a human-readable description of the object.
( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} )
5.15. searchGuide
This attribute is for use by X.500 clients in constructing search
filters. It is obsoleted by enhancedSearchGuide, described below in
5.48.
( 2.5.4.14 NAME 'searchGuide'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.25 )
5.16. businessCategory
This attribute describes the kind of business performed by an
organization.
( 2.5.4.15 NAME 'businessCategory' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} )
Wahl Standards Track [Page 5]
RFC 2256 LDAPv3 Schema December 1997
5.17. postalAddress
( 2.5.4.16 NAME 'postalAddress' EQUALITY caseIgnoreListMatch
SUBSTR caseIgnoreListSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 )
5.18. postalCode
( 2.5.4.17 NAME 'postalCode' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} )
5.19. postOfficeBox
( 2.5.4.18 NAME 'postOfficeBox' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} )
5.20. physicalDeliveryOfficeName
( 2.5.4.19 NAME 'physicalDeliveryOfficeName' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} )
5.21. telephoneNumber
( 2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch
SUBSTR telephoneNumberSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.50{32} )
5.22. telexNumber
( 2.5.4.21 NAME 'telexNumber'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.52 )
5.23. teletexTerminalIdentifier
( 2.5.4.22 NAME 'teletexTerminalIdentifier'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.51 )
5.24. facsimileTelephoneNumber
( 2.5.4.23 NAME 'facsimileTelephoneNumber'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.22 )
Wahl Standards Track [Page 6]
RFC 2256 LDAPv3 Schema December 1997
5.25. x121Address
( 2.5.4.24 NAME 'x121Address' EQUALITY numericStringMatch
SUBSTR numericStringSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{15} )
5.26. internationaliSDNNumber
( 2.5.4.25 NAME 'internationaliSDNNumber' EQUALITY numericStringMatch
SUBSTR numericStringSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{16} )
5.27. registeredAddress
This attribute holds a postal address suitable for reception of
telegrams or expedited documents, where it is necessary to have the
recipient accept delivery.
( 2.5.4.26 NAME 'registeredAddress' SUP postalAddress
SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 )
5.28. destinationIndicator
This attribute is used for the telegram service.
( 2.5.4.27 NAME 'destinationIndicator' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{128} )
5.29. preferredDeliveryMethod
( 2.5.4.28 NAME 'preferredDeliveryMethod'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.14
SINGLE-VALUE )
5.30. presentationAddress
This attribute contains an OSI presentation address.
( 2.5.4.29 NAME 'presentationAddress'
EQUALITY presentationAddressMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.43
SINGLE-VALUE )
Wahl Standards Track [Page 7]
RFC 2256 LDAPv3 Schema December 1997
5.31. supportedApplicationContext
This attribute contains the identifiers of OSI application contexts.
( 2.5.4.30 NAME 'supportedApplicationContext'
EQUALITY objectIdentifierMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
5.32. member
( 2.5.4.31 NAME 'member' SUP distinguishedName )
5.33. owner
( 2.5.4.32 NAME 'owner' SUP distinguishedName )
5.34. roleOccupant
( 2.5.4.33 NAME 'roleOccupant' SUP distinguishedName )
5.35. seeAlso
( 2.5.4.34 NAME 'seeAlso' SUP distinguishedName )
5.36. userPassword
( 2.5.4.35 NAME 'userPassword' EQUALITY octetStringMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{128} )
Passwords are stored using an Octet String syntax and are not
encrypted. Transfer of cleartext passwords are strongly discouraged
where the underlying transport service cannot guarantee
confidentiality and may result in disclosure of the password to
unauthorized parties.
5.37. userCertificate
This attribute is to be stored and requested in the binary form, as
'userCertificate;binary'.
( 2.5.4.36 NAME 'userCertificate'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 )
5.38. cACertificate
This attribute is to be stored and requested in the binary form, as
'cACertificate;binary'.
Wahl Standards Track [Page 8]
RFC 2256 LDAPv3 Schema December 1997
( 2.5.4.37 NAME 'cACertificate'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 )
5.39. authorityRevocationList
This attribute is to be stored and requested in the binary form, as
'authorityRevocationList;binary'.
( 2.5.4.38 NAME 'authorityRevocationList'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 )
5.40. certificateRevocationList
This attribute is to be stored and requested in the binary form, as
'certificateRevocationList;binary'.
( 2.5.4.39 NAME 'certificateRevocationList'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 )
5.41. crossCertificatePair
This attribute is to be stored and requested in the binary form, as
'crossCertificatePair;binary'.
( 2.5.4.40 NAME 'crossCertificatePair'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.10 )
5.42. name
The name attribute type is the attribute supertype from which string
attribute types typically used for naming may be formed. It is
unlikely that values of this type itself will occur in an entry. LDAP
server implementations which do not support attribute subtyping need
not recognize this attribute in requests. Client implementations
MUST NOT assume that LDAP servers are capable of performing attribute
subtyping.
( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
5.43. givenName
The givenName attribute is used to hold the part of a person's name
which is not their surname nor middle name.
( 2.5.4.42 NAME 'givenName' SUP name )
Wahl Standards Track [Page 9]
RFC 2256 LDAPv3 Schema December 1997
5.44. initials
The initials attribute contains the initials of some or all of an
individuals names, but not the surname(s).
( 2.5.4.43 NAME 'initials' SUP name )
5.45. generationQualifier
The generationQualifier attribute contains the part of the name which
typically is the suffix, as in "IIIrd".
( 2.5.4.44 NAME 'generationQualifier' SUP name )
5.46. x500UniqueIdentifier
The x500UniqueIdentifier attribute is used to distinguish between
objects when a distinguished name has been reused. This is a
different attribute type from both the "uid" and "uniqueIdentifier"
types.
( 2.5.4.45 NAME 'x500UniqueIdentifier' EQUALITY bitStringMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 )
5.47. dnQualifier
The dnQualifier attribute type specifies disambiguating information
to add to the relative distinguished name of an entry. It is
intended for use when merging data from multiple sources in order to
prevent conflicts between entries which would otherwise have the same
name. It is recommended that the value of the dnQualifier attribute
be the same for all entries from a particular source.
( 2.5.4.46 NAME 'dnQualifier' EQUALITY caseIgnoreMatch
ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
5.48. enhancedSearchGuide
This attribute is for use by X.500 clients in constructing search
filters.
( 2.5.4.47 NAME 'enhancedSearchGuide'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.21 )
Wahl Standards Track [Page 10]
RFC 2256 LDAPv3 Schema December 1997
5.49. protocolInformation
This attribute is used in conjunction with the presentationAddress
attribute, to provide additional information to the OSI network
service.
( 2.5.4.48 NAME 'protocolInformation'
EQUALITY protocolInformationMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.42 )
5.50. distinguishedName
This attribute type is not used as the name of the object itself, but
it is instead a base type from which attributes with DN syntax
inherit.
It is unlikely that values of this type itself will occur in an
entry. LDAP server implementations which do not support attribute
subtyping need not recognize this attribute in requests. Client
implementations MUST NOT assume that LDAP servers are capable of
performing attribute subtyping.
( 2.5.4.49 NAME 'distinguishedName' EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 )
5.51. uniqueMember
( 2.5.4.50 NAME 'uniqueMember' EQUALITY uniqueMemberMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.34 )
5.52. houseIdentifier
This attribute is used to identify a building within a location.
( 2.5.4.51 NAME 'houseIdentifier' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
5.53. supportedAlgorithms
This attribute is to be stored and requested in the binary form, as
'supportedAlgorithms;binary'.
( 2.5.4.52 NAME 'supportedAlgorithms'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.49 )
Wahl Standards Track [Page 11]
RFC 2256 LDAPv3 Schema December 1997
5.54. deltaRevocationList
This attribute is to be stored and requested in the binary form, as
'deltaRevocationList;binary'.
( 2.5.4.53 NAME 'deltaRevocationList'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 )
5.55. dmdName
The value of this attribute specifies a directory management domain
(DMD), the administrative authority which operates the directory
server.
( 2.5.4.54 NAME 'dmdName' SUP name )
6. Syntaxes
Servers SHOULD recognize the syntaxes defined in this section. Each
syntax begins with a sample value of the ldapSyntaxes attribute which
defines the OBJECT IDENTIFIER of the syntax. The descriptions of
syntax names are not carried in protocol, and are not guaranteed to
be unique.
6.1. Delivery Method
( 1.3.6.1.4.1.1466.115.121.1.14 DESC 'Delivery Method' )
Values in this syntax are encoded according to the following BNF:
delivery-value = pdm / ( pdm whsp "$" whsp delivery-value )
pdm = "any" / "mhs" / "physical" / "telex" / "teletex" /
"g3fax" / "g4fax" / "ia5" / "videotex" / "telephone"
Example:
telephone
6.2. Enhanced Guide
( 1.3.6.1.4.1.1466.115.121.1.21 DESC 'Enhanced Guide' )
Values in this syntax are encoded according to the following BNF:
EnhancedGuide = woid whsp "#" whsp criteria whsp "#" whsp subset
subset = "baseobject" / "oneLevel" / "wholeSubtree"
Wahl Standards Track [Page 12]
RFC 2256 LDAPv3 Schema December 1997
The criteria production is defined in the Guide syntax below. This
syntax has been added subsequent to RFC 1778.
Example:
person#(sn)#oneLevel
6.3. Guide
( 1.3.6.1.4.1.1466.115.121.1.25 DESC 'Guide' )
Values in this syntax are encoded according to the following BNF:
guide-value = [ object-class "#" ] criteria
object-class = woid
criteria = criteria-item / criteria-set / ( "!" criteria )
criteria-set = ( [ "(" ] criteria "&" criteria-set [ ")" ] ) /
( [ "(" ] criteria "|" criteria-set [ ")" ] )
criteria-item = [ "(" ] attributetype "$" match-type [ ")" ]
match-type = "EQ" / "SUBSTR" / "GE" / "LE" / "APPROX"
This syntax should not be used for defining new attributes.
6.4. Octet String
( 1.3.6.1.4.1.1466.115.121.1.40 DESC 'Octet String' )
Values in this syntax are encoded as octet strings.
Example:
secret
6.5. Teletex Terminal Identifier
( 1.3.6.1.4.1.1466.115.121.1.51 DESC 'Teletex Terminal Identifier' )
Values in this syntax are encoded according to the following BNF:
teletex-id = ttx-term 0*("$" ttx-param)
ttx-term = printablestring
Wahl Standards Track [Page 13]
RFC 2256 LDAPv3 Schema December 1997
ttx-param = ttx-key ":" ttx-value
ttx-key = "graphic" / "control" / "misc" / "page" / "private"
ttx-value = octetstring
In the above, the first printablestring is the encoding of the first
portion of the teletex terminal identifier to be encoded, and the
subsequent 0 or more octetstrings are subsequent portions of the
teletex terminal identifier.
6.6. Telex Number
( 1.3.6.1.4.1.1466.115.121.1.52 DESC 'Telex Number' )
Values in this syntax are encoded according to the following BNF:
telex-number = actual-number "$" country "$" answerback
actual-number = printablestring
country = printablestring
answerback = printablestring
In the above, actual-number is the syntactic representation of the
number portion of the TELEX number being encoded, country is the
TELEX country code, and answerback is the answerback code of a TELEX
terminal.
6.7. Supported Algorithm
( 1.3.6.1.4.1.1466.115.121.1.49 DESC 'Supported Algorithm' )
No printable representation of values of the supportedAlgorithms
attribute is defined in this document. Clients which wish to store
and retrieve this attribute MUST use "supportedAlgorithms;binary", in
which the value is transferred as a binary encoding.
7. Object Classes
LDAP servers MUST recognize the object classes "top" and "subschema".
LDAP servers SHOULD recognize all the other object classes listed
here as values of the objectClass attribute.
7.1. top
( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass )
Wahl Standards Track [Page 14]
RFC 2256 LDAPv3 Schema December 1997
7.2. alias
( 2.5.6.1 NAME 'alias' SUP top STRUCTURAL MUST aliasedObjectName )
7.3. country
( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c
MAY ( searchGuide $ description ) )
7.4. locality
( 2.5.6.3 NAME 'locality' SUP top STRUCTURAL
MAY ( street $ seeAlso $ searchGuide $ st $ l $ description ) )
7.5. organization
( 2.5.6.4 NAME 'organization' SUP top STRUCTURAL MUST o
MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
x121Address $ registeredAddress $ destinationIndicator $
preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
telephoneNumber $ internationaliSDNNumber $
facsimileTelephoneNumber $
street $ postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ st $ l $ description ) )
7.6. organizationalUnit
( 2.5.6.5 NAME 'organizationalUnit' SUP top STRUCTURAL MUST ou
MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
x121Address $ registeredAddress $ destinationIndicator $
preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
telephoneNumber $ internationaliSDNNumber $
facsimileTelephoneNumber $
street $ postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ st $ l $ description ) )
7.7. person
( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )
7.8. organizationalPerson
( 2.5.6.7 NAME 'organizationalPerson' SUP person STRUCTURAL
MAY ( title $ x121Address $ registeredAddress $
destinationIndicator $
preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
telephoneNumber $ internationaliSDNNumber $
Wahl Standards Track [Page 15]
RFC 2256 LDAPv3 Schema December 1997
facsimileTelephoneNumber $
street $ postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ ou $ st $ l ) )
7.9. organizationalRole
( 2.5.6.8 NAME 'organizationalRole' SUP top STRUCTURAL MUST cn
MAY ( x121Address $ registeredAddress $ destinationIndicator $
preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
telephoneNumber $ internationaliSDNNumber $
facsimileTelephoneNumber $
seeAlso $ roleOccupant $ preferredDeliveryMethod $ street $
postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ ou $ st $ l $ description ) )
7.10. groupOfNames
( 2.5.6.9 NAME 'groupOfNames' SUP top STRUCTURAL MUST ( member $ cn )
MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) )
7.11. residentialPerson
( 2.5.6.10 NAME 'residentialPerson' SUP person STRUCTURAL MUST l
MAY ( businessCategory $ x121Address $ registeredAddress $
destinationIndicator $ preferredDeliveryMethod $ telexNumber $
teletexTerminalIdentifier $ telephoneNumber $
internationaliSDNNumber $
facsimileTelephoneNumber $ preferredDeliveryMethod $ street $
postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ st $ l ) )
7.12. applicationProcess
( 2.5.6.11 NAME 'applicationProcess' SUP top STRUCTURAL MUST cn
MAY ( seeAlso $ ou $ l $ description ) )
7.13. applicationEntity
( 2.5.6.12 NAME 'applicationEntity' SUP top STRUCTURAL
MUST ( presentationAddress $ cn )
MAY ( supportedApplicationContext $ seeAlso $ ou $ o $ l $
description ) )
7.14. dSA
( 2.5.6.13 NAME 'dSA' SUP applicationEntity STRUCTURAL
MAY knowledgeInformation )
Wahl Standards Track [Page 16]
RFC 2256 LDAPv3 Schema December 1997
7.15. device
( 2.5.6.14 NAME 'device' SUP top STRUCTURAL MUST cn
MAY ( serialNumber $ seeAlso $ owner $ ou $ o $ l $ description ) )
7.16. strongAuthenticationUser
( 2.5.6.15 NAME 'strongAuthenticationUser' SUP top AUXILIARY
MUST userCertificate )
7.17. certificationAuthority
( 2.5.6.16 NAME 'certificationAuthority' SUP top AUXILIARY
MUST ( authorityRevocationList $ certificateRevocationList $
cACertificate ) MAY crossCertificatePair )
7.18. groupOfUniqueNames
( 2.5.6.17 NAME 'groupOfUniqueNames' SUP top STRUCTURAL
MUST ( uniqueMember $ cn )
MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) )
7.19. userSecurityInformation
( 2.5.6.18 NAME 'userSecurityInformation' SUP top AUXILIARY
MAY ( supportedAlgorithms ) )
7.20. certificationAuthority-V2
( 2.5.6.16.2 NAME 'certificationAuthority-V2' SUP
certificationAuthority
AUXILIARY MAY ( deltaRevocationList ) )
7.21. cRLDistributionPoint
( 2.5.6.19 NAME 'cRLDistributionPoint' SUP top STRUCTURAL
MUST ( cn ) MAY ( certificateRevocationList $
authorityRevocationList $
deltaRevocationList ) )
7.22. dmd
( 2.5.6.20 NAME 'dmd' SUP top STRUCTURAL MUST ( dmdName )
MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $
x121Address $ registeredAddress $ destinationIndicator $
preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $
telephoneNumber $ internationaliSDNNumber $
facsimileTelephoneNumber $
Wahl Standards Track [Page 17]
RFC 2256 LDAPv3 Schema December 1997
street $ postOfficeBox $ postalCode $ postalAddress $
physicalDeliveryOfficeName $ st $ l $ description ) )
8. Matching Rules
Servers MAY implement additional matching rules.
8.1. octetStringMatch
Servers which implement the extensibleMatch filter SHOULD allow the
matching rule listed in this section to be used in the
extensibleMatch. In general these servers SHOULD allow matching
rules to be used with all attribute types known to the server, when
the assertion syntax of the matching rule is the same as the value
syntax of the attribute.
( 2.5.13.17 NAME 'octetStringMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 )
9. Security Considerations
Attributes of directory entries are used to provide descriptive
information about the real-world objects they represent, which can be
people, organizations or devices. Most countries have privacy laws
regarding the publication of information about people.
Transfer of cleartext passwords are strongly discouraged where the
underlying transport service cannot guarantee confidentiality and may
result in disclosure of the password to unauthorized parties.
10. Acknowledgements
The definitions on which this document have been developed by
committees for telecommunications and international standards. No
new attribute definitions have been added. The syntax definitions
are based on the ISODE "QUIPU" implementation of X.500.
11. Bibliography
[1] Wahl, M., Coulbeck, A., Howes, T., and S. Kille,
"Lightweight X.500 Directory Access Protocol (v3): Attribute
Syntax Definitions", RFC 2252, December 1997.
[2] The Directory: Models. ITU-T Recommendation X.501, 1996.
[3] The Directory: Authentication Framework. ITU-T Recommendation
X.509, 1996.
Wahl Standards Track [Page 18]
RFC 2256 LDAPv3 Schema December 1997
[4] The Directory: Selected Attribute Types. ITU-T Recommendation
X.520, 1996.
[5] The Directory: Selected Object Classes. ITU-T Recommendation
X.521, 1996.
[6] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
12. Author's Address
Mark Wahl
Critical Angle Inc.
4815 West Braker Lane #502-385
Austin, TX 78759
USA
Phone: +1 512 372 3160
EMail: M.Wahl@critical-angle.com
Wahl Standards Track [Page 19]
RFC 2256 LDAPv3 Schema December 1997
13. Full Copyright Statement
Copyright (C) The Internet Society (1997). 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 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.
Wahl Standards Track [Page 20]
USAGE dSAOperation )
5.3. LDAP Subschema Attribute
This attribute is typically located in the subschema entry.
5.3.1. ldapSyntaxes
Servers MAY use this attribute to list the syntaxes which are
implemented. Each value corresponds to one syntax.
( 1.3.6.1.4.1.1466.101.120.16 NAME 'ldapSyntaxes'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.14
1.1 jakarta-james/www/rfclist/ldap/rfc2829.txt
Index: rfc2829.txt
===================================================================
Network Working Group M. Wahl
Request for Comments: 2829 Sun Microsystems, Inc.
Category: Standards Track H. Alvestrand
EDB Maxware
J. Hodges
Oblix, Inc.
R. Morgan
University of Washington
May 2000
Authentication Methods for LDAP
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract
This document specifies particular combinations of security
mechanisms which are required and recommended in LDAP [1]
implementations.
1. Introduction
LDAP version 3 is a powerful access protocol for directories.
It offers means of searching, fetching and manipulating directory
content, and ways to access a rich set of security functions.
In order to function for the best of the Internet, it is vital that
these security functions be interoperable; therefore there has to be
a minimum subset of security functions that is common to all
implementations that claim LDAPv3 conformance.
Basic threats to an LDAP directory service include:
(1) Unauthorized access to data via data-fetching operations,
Wahl, et al. Standards Track [Page 1]
RFC 2829 Authentication Methods for LDAP May 2000
(2) Unauthorized access to reusable client authentication
information by monitoring others' access,
(3) Unauthorized access to data by monitoring others' access,
(4) Unauthorized modification of data,
(5) Unauthorized modification of configuration,
(6) Unauthorized or excessive use of resources (denial of
service), and
(7) Spoofing of directory: Tricking a client into believing that
information came from the directory when in fact it did not,
either by modifying data in transit or misdirecting the
client's connection.
Threats (1), (4), (5) and (6) are due to hostile clients. Threats
(2), (3) and (7) are due to hostile agents on the path between client
and server, or posing as a server.
The LDAP protocol suite can be protected with the following security
mechanisms:
(1) Client authentication by means of the SASL [2] mechanism
set, possibly backed by the TLS credentials exchange
mechanism,
(2) Client authorization by means of access control based on the
requestor's authenticated identity,
(3) Data integrity protection by means of the TLS protocol or
data-integrity SASL mechanisms,
(4) Protection against snooping by means of the TLS protocol or
data-encrypting SASL mechanisms,
(5) Resource limitation by means of administrative limits on
service controls, and
(6) Server authentication by means of the TLS protocol or SASL
mechanism.
At the moment, imposition of access controls is done by means outside
the scope of the LDAP protocol.
In this document, the term "user" represents any application which is
an LDAP client using the directory to retrieve or store information.
Wahl, et al. Standards Track [Page 2]
RFC 2829 Authentication Methods for LDAP May 2000
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 RFC 2119 [3].
2. Example deployment scenarios
The following scenarios are typical for LDAP directories on the
Internet, and have different security requirements. (In the
following, "sensitive" means data that will cause real damage to the
owner if revealed; there may be data that is protected but not
sensitive). This is not intended to be a comprehensive list, other
scenarios are possible, especially on physically protected networks.
(1) A read-only directory, containing no sensitive data,
accessible to "anyone", and TCP connection hijacking or IP
spoofing is not a problem. This directory requires no
security functions except administrative service limits.
(2) A read-only directory containing no sensitive data; read
access is granted based on identity. TCP connection
hijacking is not currently a problem. This scenario requires
a secure authentication function.
(3) A read-only directory containing no sensitive data; and the
client needs to ensure that the directory data is
authenticated by the server and not modified while being
returned from the server.
(4) A read-write directory, containing no sensitive data; read
access is available to "anyone", update access to properly
authorized persons. TCP connection hijacking is not
currently a problem. This scenario requires a secure
authentication function.
(5) A directory containing sensitive data. This scenario
requires session confidentiality protection AND secure
authentication.
3. Authentication and Authorization: Definitions and Concepts
This section defines basic terms, concepts, and interrelationships
regarding authentication, authorization, credentials, and identity.
These concepts are used in describing how various security approaches
are utilized in client authentication and authorization.
Wahl, et al. Standards Track [Page 3]
RFC 2829 Authentication Methods for LDAP May 2000
3.1. Access Control Policy
An access control policy is a set of rules defining the protection of
resources, generally in terms of the capabilities of persons or other
entities accessing those resources. A common expression of an access
control policy is an access control list. Security objects and
mechanisms, such as those described here, enable the expression of
access control policies and their enforcement. Access control
policies are typically expressed in terms of access control
attributes as described below.
3.2. Access Control Factors
A request, when it is being processed by a server, may be associated
with a wide variety of security-related factors (section 4.2 of [1]).
The server uses these factors to determine whether and how to process
the request. These are called access control factors (ACFs). They
might include source IP address, encryption strength, the type of
operation being requested, time of day, etc. Some factors may be
specific to the request itself, others may be associated with the
connection via which the request is transmitted, others (e.g. time of
day) may be "environmental".
Access control policies are expressed in terms of access control
factors. E.g., a request having ACFs i,j,k can perform operation Y
on resource Z. The set of ACFs that a server makes available for such
expressions is implementation-specific.
3.3. Authentication, Credentials, Identity
Authentication credentials are the evidence supplied by one party to
another, asserting the identity of the supplying party (e.g. a user)
who is attempting to establish an association with the other party
(typically a server). Authentication is the process of generating,
transmitting, and verifying these credentials and thus the identity
they assert. An authentication identity is the name presented in a
credential.
There are many forms of authentication credentials -- the form used
depends upon the particular authentication mechanism negotiated by
the parties. For example: X.509 certificates, Kerberos tickets,
simple identity and password pairs. Note that an authentication
mechanism may constrain the form of authentication identities used
with it.
Wahl, et al. Standards Track [Page 4]
RFC 2829 Authentication Methods for LDAP May 2000
3.4. Authorization Identity
An authorization identity is one kind of access control factor. It
is the name of the user or other entity that requests that operations
be performed. Access control policies are often expressed in terms
of authorization identities; e.g., entity X can perform operation Y
on resource Z.
The authorization identity bound to an association is often exactly
the same as the authentication identity presented by the client, but
it may be different. SASL allows clients to specify an authorization
identity distinct from the authentication identity asserted by the
client's credentials. This permits agents such as proxy servers to
authenticate using their own credentials, yet request the access
privileges of the identity for which they are proxying [2]. Also,
the form of authentication identity supplied by a service like TLS
may not correspond to the authorization identities used to express a
server's access control policy, requiring a server-specific mapping
to be done. The method by which a server composes and validates an
authorization identity from the authentication credentials supplied
by a client is implementation-specific.
4. Required security mechanisms
It is clear that allowing any implementation, faced with the above
requirements, to pick and choose among the possible alternatives is
not a strategy that is likely to lead to interoperability. In the
absence of mandates, clients will be written that do not support any
security function supported by the server, or worse, support only
mechanisms like cleartext passwords that provide clearly inadequate
security.
Active intermediary attacks are the most difficult for an attacker to
perform, and for an implementation to protect against. Methods that
protect only against hostile client and passive eavesdropping attacks
are useful in situations where the cost of protection against active
intermediary attacks is not justified based on the perceived risk of
active intermediary attacks.
Given the presence of the Directory, there is a strong desire to see
mechanisms where identities take the form of a Distinguished Name and
authentication data can be stored in the directory; this means that
either this data is useless for faking authentication (like the Unix
"/etc/passwd" file format used to be), or its content is never passed
across the wire unprotected - that is, it's either updated outside
the protocol or it is only updated in sessions well protected against
snooping. It is also desirable to allow authentication methods to
Wahl, et al. Standards Track [Page 5]
RFC 2829 Authentication Methods for LDAP May 2000
carry authorization identities based on existing forms of user
identities for backwards compatibility with non-LDAP-based
authentication services.
Therefore, the following implementation conformance requirements are
in place:
(1) For a read-only, public directory, anonymous authentication,
described in section 5, can be used.
(2) Implementations providing password-based authenticated
access MUST support authentication using the DIGEST-MD5 SASL
mechanism [4], as described in section 6.1. This provides
client authentication with protection against passive
eavesdropping attacks, but does not provide protection
against active intermediary attacks.
(3) For a directory needing session protection and
authentication, the Start TLS extended operation [5], and
either the simple authentication choice or the SASL EXTERNAL
mechanism, are to be used together. Implementations SHOULD
support authentication with a password as described in
section 6.2, and SHOULD support authentication with a
certificate as described in section 7.1. Together, these
can provide integrity and disclosure protection of
transmitted data, and authentication of client and server,
including protection against active intermediary attacks.
If TLS is negotiated, the client MUST discard all information about
the server fetched prior to the TLS negotiation. In particular, the
value of supportedSASLMechanisms MAY be different after TLS has been
negotiated (specifically, the EXTERNAL mechanism or the proposed
PLAIN mechanism are likely to only be listed after a TLS negotiation
has been performed).
If a SASL security layer is negotiated, the client MUST discard all
information about the server fetched prior to SASL. In particular,
if the client is configured to support multiple SASL mechanisms, it
SHOULD fetch supportedSASLMechanisms both before and after the SASL
security layer is negotiated and verify that the value has not
changed after the SASL security layer was negotiated. This detects
active attacks which remove supported SASL mechanisms from the
supportedSASLMechanisms list, and allows the client to ensure that it
is using the best mechanism supported by both client and server
(additionally, this is a SHOULD to allow for environments where the
supported SASL mechanisms list is provided to the client through a
different trusted source, e.g. as part of a digitally signed object).
Wahl, et al. Standards Track [Page 6]
RFC 2829 Authentication Methods for LDAP May 2000
5. Anonymous authentication
Directory operations which modify entries or access protected
attributes or entries generally require client authentication.
Clients which do not intend to perform any of these operations
typically use anonymous authentication.
LDAP implementations MUST support anonymous authentication, as
defined in section 5.1.
LDAP implementations MAY support anonymous authentication with TLS,
as defined in section 5.2.
While there MAY be access control restrictions to prevent access to
directory entries, an LDAP server SHOULD allow an anonymously-bound
client to retrieve the supportedSASLMechanisms attribute of the root
DSE.
An LDAP server MAY use other information about the client provided by
the lower layers or external means to grant or deny access even to
anonymously authenticated clients.
5.1. Anonymous authentication procedure
An LDAP client which has not successfully completed a bind operation
on a connection is anonymously authenticated.
An LDAP client MAY also specify anonymous authentication in a bind
request by using a zero-length OCTET STRING with the simple
authentication choice.
5.2. Anonymous authentication and TLS
An LDAP client MAY use the Start TLS operation [5] to negotiate the
use of TLS security [6]. If the client has not bound beforehand,
then until the client uses the EXTERNAL SASL mechanism to negotiate
the recognition of the client's certificate, the client is
anonymously authenticated.
Recommendations on TLS ciphersuites are given in section 10.
An LDAP server which requests that clients provide their certificate
during TLS negotiation MAY use a local security policy to determine
whether to successfully complete TLS negotiation if the client did
not present a certificate which could be validated.
Wahl, et al. Standards Track [Page 7]
RFC 2829 Authentication Methods for LDAP May 2000
6. Password-based authentication
LDAP implementations MUST support authentication with a password
using the DIGEST-MD5 SASL mechanism for password protection, as
defined in section 6.1.
LDAP implementations SHOULD support authentication with the "simple"
password choice when the connection is protected against
eavesdropping using TLS, as defined in section 6.2.
6.1. Digest authentication
An LDAP client MAY determine whether the server supports this
mechanism by performing a search request on the root DSE, requesting
the supportedSASLMechanisms attribute, and checking whether the
string "DIGEST-MD5" is present as a value of this attribute.
In the first stage of authentication, when the client is performing
an "initial authentication" as defined in section 2.1 of [4], the
client sends a bind request in which the version number is 3, the
authentication choice is sasl, the sasl mechanism name is "DIGEST-
MD5", and the credentials are absent. The client then waits for a
response from the server to this request.
The server will respond with a bind response in which the resultCode
is saslBindInProgress, and the serverSaslCreds field is present. The
contents of this field is a string defined by "digest-challenge" in
section 2.1.1 of [4]. The server SHOULD include a realm indication
and MUST indicate support for UTF-8.
The client will send a bind request with a distinct message id, in
which the version number is 3, the authentication choice is sasl, the
sasl mechanism name is "DIGEST-MD5", and the credentials contain the
string defined by "digest-response" in section 2.1.2 of [4]. The
serv-type is "ldap".
The server will respond with a bind response in which the resultCode
is either success, or an error indication. If the authentication is
successful and the server does not support subsequent authentication,
then the credentials field is absent. If the authentication is
successful and the server supports subsequent authentication, then
the credentials field contains the string defined by "response-auth"
in section 2.1.3 of [4]. Support for subsequent authentication is
OPTIONAL in clients and servers.
Wahl, et al. Standards Track [Page 8]
RFC 2829 Authentication Methods for LDAP May 2000
6.2. "simple" authentication choice under TLS encryption
A user who has a directory entry containing a userPassword attribute
MAY authenticate to the directory by performing a simple password
bind sequence following the negotiation of a TLS ciphersuite
providing connection confidentiality [6].
The client will use the Start TLS operation [5] to negotiate the use
of TLS security [6] on the connection to the LDAP server. The client
need not have bound to the directory beforehand.
For this authentication procedure to be successful, the client and
server MUST negotiate a ciphersuite which contains a bulk encryption
algorithm of appropriate strength. Recommendations on cipher suites
are given in section 10.
Following the successful completion of TLS negotiation, the client
MUST send an LDAP bind request with the version number of 3, the name
field containing the name of the user's entry, and the "simple"
authentication choice, containing a password.
The server will, for each value of the userPassword attribute in the
named user's entry, compare these for case-sensitive equality with
the client's presented password. If there is a match, then the
server will respond with resultCode success, otherwise the server
will respond with resultCode invalidCredentials.
6.3. Other authentication choices with TLS
It is also possible, following the negotiation of TLS, to perform a
SASL authentication which does not involve the exchange of plaintext
reusable passwords. In this case the client and server need not
negotiate a ciphersuite which provides confidentiality if the only
service required is data integrity.
7. Certificate-based authentication
LDAP implementations SHOULD support authentication via a client
certificate in TLS, as defined in section 7.1.
7.1. Certificate-based authentication with TLS
A user who has a public/private key pair in which the public key has
been signed by a Certification Authority may use this key pair to
authenticate to the directory server if the user's certificate is
requested by the server. The user's certificate subject field SHOULD
be the name of the user's directory entry, and the Certification
Authority must be sufficiently trusted by the directory server to
Wahl, et al. Standards Track [Page 9]
RFC 2829 Authentication Methods for LDAP May 2000
have issued the certificate in order that the server can process the
certificate. The means by which servers validate certificate paths
is outside the scope of this document.
A server MAY support mappings for certificates in which the subject
field name is different from the name of the user's directory entry.
A server which supports mappings of names MUST be capable of being
configured to support certificates for which no mapping is required.
The client will use the Start TLS operation [5] to negotiate the use
of TLS security [6] on the connection to the LDAP server. The client
need not have bound to the directory beforehand.
In the TLS negotiation, the server MUST request a certificate. The
client will provide its certificate to the server, and MUST perform a
private key-based encryption, proving it has the private key
associated with the certificate.
As deployments will require protection of sensitive data in transit,
the client and server MUST negotiate a ciphersuite which contains a
bulk encryption algorithm of appropriate strength. Recommendations
of cipher suites are given in section 10.
The server MUST verify that the client's certificate is valid. The
server will normally check that the certificate is issued by a known
CA, and that none of the certificates on the client's certificate
chain are invalid or revoked. There are several procedures by which
the server can perform these checks.
Following the successful completion of TLS negotiation, the client
will send an LDAP bind request with the SASL "EXTERNAL" mechanism.
8. Other mechanisms
The LDAP "simple" authentication choice is not suitable for
authentication on the Internet where there is no network or transport
layer confidentiality.
As LDAP includes native anonymous and plaintext authentication
methods, the "ANONYMOUS" and "PLAIN" SASL mechanisms are not used
with LDAP. If an authorization identity of a form different from a
DN is requested by the client, a mechanism that protects the password
in transit SHOULD be used.
The following SASL-based mechanisms are not considered in this
document: KERBEROS_V4, GSSAPI and SKEY.
Wahl, et al. Standards Track [Page 10]
RFC 2829 Authentication Methods for LDAP May 2000
The "EXTERNAL" SASL mechanism can be used to request the LDAP server
make use of security credentials exchanged by a lower layer. If a TLS
session has not been established between the client and server prior
to making the SASL EXTERNAL Bind request and there is no other
external source of authentication credentials (e.g. IP-level
security [8]), or if, during the process of establishing the TLS
session, the server did not request the client's authentication
credentials, the SASL EXTERNAL bind MUST fail with a result code of
inappropriateAuthentication. Any client authentication and
authorization state of the LDAP association is lost, so the LDAP
association is in an anonymous state after the failure.
9. Authorization Identity
The authorization identity is carried as part of the SASL credentials
field in the LDAP Bind request and response.
When the "EXTERNAL" mechanism is being negotiated, if the credentials
field is present, it contains an authorization identity of the
authzId form described below.
Other mechanisms define the location of the authorization identity in
the credentials field.
The authorization identity is a string in the UTF-8 character set,
corresponding to the following ABNF [7]:
; Specific predefined authorization (authz) id schemes are
; defined below -- new schemes may be defined in the future.
authzId = dnAuthzId / uAuthzId
; distinguished-name-based authz id.
dnAuthzId = "dn:" dn
dn = utf8string ; with syntax defined in RFC 2253
; unspecified userid, UTF-8 encoded.
uAuthzId = "u:" userid
userid = utf8string ; syntax unspecified
A utf8string is defined to be the UTF-8 encoding of one or more ISO
10646 characters.
All servers which support the storage of authentication credentials,
such as passwords or certificates, in the directory MUST support the
dnAuthzId choice.
Wahl, et al. Standards Track [Page 11]
RFC 2829 Authentication Methods for LDAP May 2000
The uAuthzId choice allows for compatibility with client applications
which wish to authenticate to a local directory but do not know their
own Distinguished Name or have a directory entry. The format of the
string is defined as only a sequence of UTF-8 encoded ISO 10646
characters, and further interpretation is subject to prior agreement
between the client and server.
For example, the userid could identify a user of a specific directory
service, or be a login name or the local-part of an RFC 822 email
address. In general a uAuthzId MUST NOT be assumed to be globally
unique.
Additional authorization identity schemes MAY be defined in future
versions of this document.
10. TLS Ciphersuites
The following ciphersuites defined in [6] MUST NOT be used for
confidentiality protection of passwords or data:
TLS_NULL_WITH_NULL_NULL
TLS_RSA_WITH_NULL_MD5
TLS_RSA_WITH_NULL_SHA
The following ciphersuites defined in [6] can be cracked easily (less
than a week of CPU time on a standard CPU in 1997). The client and
server SHOULD carefully consider the value of the password or data
being protected before using these ciphersuites:
TLS_RSA_EXPORT_WITH_RC4_40_MD5
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
The following ciphersuites are vulnerable to man-in-the-middle
attacks, and SHOULD NOT be used to protect passwords or sensitive
data, unless the network configuration is such that the danger of a
man-in-the-middle attack is tolerable:
Wahl, et al. Standards Track [Page 12]
RFC 2829 Authentication Methods for LDAP May 2000
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_WITH_RC4_128_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_WITH_DES_CBC_SHA
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
A client or server that supports TLS MUST support at least
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA.
11. SASL service name for LDAP
For use with SASL [2], a protocol must specify a service name to be
used with various SASL mechanisms, such as GSSAPI. For LDAP, the
service name is "ldap", which has been registered with the IANA as a
GSSAPI service name.
12. Security Considerations
Security issues are discussed throughout this memo; the
(unsurprising) conclusion is that mandatory security is important,
and that session encryption is required when snooping is a problem.
Servers are encouraged to prevent modifications by anonymous users.
Servers may also wish to minimize denial of service attacks by timing
out idle connections, and returning the unwillingToPerform result
code rather than performing computationally expensive operations
requested by unauthorized clients.
A connection on which the client has not performed the Start TLS
operation or negotiated a suitable SASL mechanism for connection
integrity and encryption services is subject to man-in-the-middle
attacks to view and modify information in transit.
Additional security considerations relating to the EXTERNAL mechanism
to negotiate TLS can be found in [2], [5] and [6].
13. Acknowledgements
This document is a product of the LDAPEXT Working Group of the IETF.
The contributions of its members is greatly appreciated.
Wahl, et al. Standards Track [Page 13]
RFC 2829 Authentication Methods for LDAP May 2000
14. Bibliography
[1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[2] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC
2222, October 1997.
[3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[4] Leach, P. and C. Newman, "Using Digest Authentication as a SASL
Mechanism", RFC 2831, May 2000.
[5] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access
Protocol (v3): Extension for Transport Layer Security", RFC 2830,
May 2000.
[6] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC
2246, January 1999.
[7] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[8] Kent, S. and R. Atkinson, "Security Architecture for the Internet
Protocol", RFC 2401, November 1998.
Wahl, et al. Standards Track [Page 14]
RFC 2829 Authentication Methods for LDAP May 2000
15. Authors' Addresses
Mark Wahl
Sun Microsystems, Inc.
8911 Capital of Texas Hwy #4140
Austin TX 78759
USA
EMail: M.Wahl@innosoft.com
Harald Tveit Alvestrand
EDB Maxware
Pirsenteret
N-7462 Trondheim, Norway
Phone: +47 73 54 57 97
EMail: Harald@Alvestrand.no
Jeff Hodges
Oblix, Inc.
18922 Forge Drive
Cupertino, CA 95014
USA
Phone: +1-408-861-6656
EMail: JHodges@oblix.com
RL "Bob" Morgan
Computing and Communications
University of Washington
Seattle, WA 98105
USA
Phone: +1-206-221-3307
EMail: rlmorgan@washington.edu
Wahl, et al. Standards Track [Page 15]
RFC 2829 Authentication Methods for LDAP May 2000
16. Full Copyright Statement
Copyright (C) The Internet Society (2000). 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 abov
1.1 jakarta-james/www/rfclist/ldap/rfc2830.txt
Index: rfc2830.txt
===================================================================
Network Working Group J. Hodges
Request for Comments: 2830 Oblix Inc.
Category: Standards Track R. Morgan
Univ of Washington
M. Wahl
Sun Microsystems, Inc.
May 2000
Lightweight Directory Access Protocol (v3):
Extension for Transport Layer Security
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract
This document defines the "Start Transport Layer Security (TLS)
Operation" for LDAP [LDAPv3, TLS]. This operation provides for TLS
establishment in an LDAP association and is defined in terms of an
LDAP extended request.
1. Conventions Used in this Document
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 [ReqsKeywords].
2. The Start TLS Request
This section describes the Start TLS extended request and extended
response themselves: how to form the request, the form of the
response, and enumerates the various result codes the client MUST be
prepared to handle.
The section following this one then describes how to sequence an
overall Start TLS Operation.
Hodges, et al. Standards Track [Page 1]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
2.1. Requesting TLS Establishment
A client may perform a Start TLS operation by transmitting an LDAP
PDU containing an ExtendedRequest [LDAPv3] specifying the OID for the
Start TLS operation:
1.3.6.1.4.1.1466.20037
An LDAP ExtendedRequest is defined as follows:
ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
requestName [0] LDAPOID,
requestValue [1] OCTET STRING OPTIONAL }
A Start TLS extended request is formed by setting the requestName
field to the OID string given above. The requestValue field is
absent. The client MUST NOT send any PDUs on this connection
following this request until it receives a Start TLS extended
response.
When a Start TLS extended request is made, the server MUST return an
LDAP PDU containing a Start TLS extended response. An LDAP
ExtendedResponse is defined as follows:
ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
COMPONENTS OF LDAPResult,
responseName [10] LDAPOID OPTIONAL,
response [11] OCTET STRING OPTIONAL }
A Start TLS extended response MUST contain a responseName field which
MUST be set to the same string as that in the responseName field
present in the Start TLS extended request. The response field is
absent. The server MUST set the resultCode field to either success or
one of the other values outlined in section 2.3.
2.2. "Success" Response
If the ExtendedResponse contains a resultCode of success, this
indicates that the server is willing and able to negotiate TLS. Refer
to section 3, below, for details.
2.3. Response other than "success"
If the ExtendedResponse contains a resultCode other than success,
this indicates that the server is unwilling or unable to negotiate
TLS.
Hodges, et al. Standards Track [Page 2]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
If the Start TLS extended request was not successful, the resultCode
will be one of:
operationsError (operations sequencing incorrect; e.g. TLS already
established)
protocolError (TLS not supported or incorrect PDU structure)
referral (this server doesn't do TLS, try this one)
unavailable (e.g. some major problem with TLS, or server is
shutting down)
The server MUST return operationsError if the client violates any of
the Start TLS extended operation sequencing requirements described in
section 3, below.
If the server does not support TLS (whether by design or by current
configuration), it MUST set the resultCode to protocolError (see
section 4.1.1 of [LDAPv3]), or to referral. The server MUST include
an actual referral value in the LDAP Result if it returns a
resultCode of referral. The client's current session is unaffected if
the server does not support TLS. The client MAY proceed with any LDAP
operation, or it MAY close the connection.
The server MUST return unavailable if it supports TLS but cannot
establish a TLS connection for some reason, e.g. the certificate
server not responding, it cannot contact its TLS implementation, or
if the server is in process of shutting down. The client MAY retry
the StartTLS operation, or it MAY proceed with any other LDAP
operation, or it MAY close the connection.
3. Sequencing of the Start TLS Operation
This section describes the overall procedures clients and servers
MUST follow for TLS establishment. These procedures take into
consideration various aspects of the overall security of the LDAP
association including discovery of resultant security level and
assertion of the client's authorization identity.
Note that the precise effects, on a client's authorization identity,
of establishing TLS on an LDAP association are described in detail in
section 5.
Hodges, et al. Standards Track [Page 3]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
3.1. Requesting to Start TLS on an LDAP Association
The client MAY send the Start TLS extended request at any time after
establishing an LDAP association, except that in the following cases
the client MUST NOT send a Start TLS extended request:
- if TLS is currently established on the connection, or
- during a multi-stage SASL negotiation, or
- if there are any LDAP operations outstanding on the connection.
The result of violating any of these requirements is a resultCode of
operationsError, as described above in section 2.3.
The client MAY have already performed a Bind operation when it sends
a Start TLS request, or the client might have not yet bound.
If the client did not establish a TLS connection before sending any
other requests, and the server requires the client to establish a TLS
connection before performing a particular request, the server MUST
reject that request with a confidentialityRequired or
strongAuthRequired result. The client MAY send a Start TLS extended
request, or it MAY choose to close the connection.
3.2. Starting TLS
The server will return an extended response with the resultCode of
success if it is willing and able to negotiate TLS. It will return
other resultCodes, documented above, if it is unable.
In the successful case, the client, which has ceased to transfer LDAP
requests on the connection, MUST either begin a TLS negotiation or
close the connection. The client will send PDUs in the TLS Record
Protocol directly over the underlying transport connection to the
server to initiate TLS negotiation [TLS].
3.3. TLS Version Negotiation
Negotiating the version of TLS or SSL to be used is a part of the TLS
Handshake Protocol, as documented in [TLS]. Please refer to that
document for details.
3.4. Discovery of Resultant Security Level
After a TLS connection is established on an LDAP association, both
parties MUST individually decide whether or not to continue based on
the privacy level achieved. Ascertaining the TLS connection's privacy
level is implementation dependent, and accomplished by communicating
with one's respective local TLS implementation.
Hodges, et al. Standards Track [Page 4]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
If the client or server decides that the level of authentication or
privacy is not high enough for it to continue, it SHOULD gracefully
close the TLS connection immediately after the TLS negotiation has
completed (see sections 4.1 and 5.2, below).
The client MAY attempt to Start TLS again, or MAY send an unbind
request, or send any other LDAP request.
3.5. Assertion of Client's Authorization Identity
The client MAY, upon receipt of a Start TLS extended response
indicating success, assert that a specific authorization identity be
utilized in determining the client's authorization status. The client
accomplishes this via an LDAP Bind request specifying a SASL
mechanism of "EXTERNAL" [SASL]. See section 5.1.2, below.
3.6. Server Identity Check
The client MUST check its understanding of the server's hostname
against the server's identity as presented in the server's
Certificate message, in order to prevent man-in-the-middle attacks.
Matching is performed according to these rules:
- The client MUST use the server hostname it used to open the LDAP
connection as the value to compare against the server name as
expressed in the server's certificate. The client MUST NOT use the
server's canonical DNS name or any other derived form of name.
- If a subjectAltName extension of type dNSName is present in the
certificate, it SHOULD be used as the source of the server's
identity.
- Matching is case-insensitive.
- The "*" wildcard character is allowed. If present, it applies only
to the left-most name component.
E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not
bar.com. If more than one identity of a given type is present in the
certificate (e.g. more than one dNSName name), a match in any one of
the set is considered acceptable.
If the hostname does not match the dNSName-based identity in the
certificate per the above check, user-oriented clients SHOULD either
notify the user (clients MAY give the user the opportunity to
Hodges, et al. Standards Track [Page 5]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
continue with the connection in any case) or terminate the connection
and indicate that the server's identity is suspect. Automated clients
SHOULD close the connection, returning and/or logging an error
indicating that the server's identity is suspect.
Beyond the server identity checks described in this section, clients
SHOULD be prepared to do further checking to ensure that the server
is authorized to provide the service it is observed to provide. The
client MAY need to make use of local policy information.
3.7. Refresh of Server Capabilities Information
The client MUST refresh any cached server capabilities information
(e.g. from the server's root DSE; see section 3.4 of [LDAPv3]) upon
TLS session establishment. This is necessary to protect against
active-intermediary attacks which may have altered any server
capabilities information retrieved prior to TLS establishment. The
server MAY advertise different capabilities after TLS establishment.
4. Closing a TLS Connection
4.1. Graceful Closure
Either the client or server MAY terminate the TLS connection on an
LDAP association by sending a TLS closure alert. This will leave the
LDAP association intact.
Before closing a TLS connection, the client MUST either wait for any
outstanding LDAP operations to complete, or explicitly abandon them
[LDAPv3].
After the initiator of a close has sent a closure alert, it MUST
discard any TLS messages until it has received an alert from the
other party. It will cease to send TLS Record Protocol PDUs, and
following the receipt of the alert, MAY send and receive LDAP PDUs.
The other party, if it receives a closure alert, MUST immediately
transmit a TLS closure alert. It will subsequently cease to send TLS
Record Protocol PDUs, and MAY send and receive LDAP PDUs.
4.2. Abrupt Closure
Either the client or server MAY abruptly close the entire LDAP
association and any TLS connection established on it by dropping the
underlying TCP connection. A server MAY beforehand send the client a
Notice of Disconnection [LDAPv3] in this case.
Hodges, et al. Standards Track [Page 6]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
5. Effects of TLS on a Client's Authorization Identity
This section describes the effects on a client's authorization
identity brought about by establishing TLS on an LDAP association.
The default effects are described first, and next the facilities for
client assertion of authorization identity are discussed including
error conditions. Lastly, the effects of closing the TLS connection
are described.
Authorization identities and related concepts are defined in
[AuthMeth].
5.1. TLS Connection Establishment Effects
5.1.1. Default Effects
Upon establishment of the TLS connection onto the LDAP association,
any previously established authentication and authorization
identities MUST remain in force, including anonymous state. This
holds even in the case where the server requests client
authentication via TLS -- e.g. requests the client to supply its
certificate during TLS negotiation (see [TLS]).
5.1.2. Client Assertion of Authorization Identity
A client MAY either implicitly request that its LDAP authorization
identity be derived from its authenticated TLS credentials or it MAY
explicitly provide an authorization identity and assert that it be
used in combination with its authenticated TLS credentials. The
former is known as an implicit assertion, and the latter as an
explicit assertion.
5.1.2.1. Implicit Assertion
An implicit authorization identity assertion is accomplished after
TLS establishment by invoking a Bind request of the SASL form using
the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL NOT include
the optional credentials octet string (found within the
SaslCredentials sequence in the Bind Request). The server will derive
the client's authorization identity from the authentication identity
supplied in the client's TLS credentials (typically a public key
certificate) according to local policy. The underlying mechanics of
how this is accomplished are implementation specific.
Hodges, et al. Standards Track [Page 7]
RFC 2830 LDAPv3: Extension for Transport Layer Security May 2000
5.1.2.2. Explicit Assertion
An explicit authorization identity assertion is accomplished after
TLS establishment by invoking a Bind request of the SASL form using
the "EXTERNAL" mechanism name [SASL, LDAPv3] that SHALL include the
credentials octet string. This string MUST be constructed as
documented in section 9 of [AuthMeth].
5.1.2.3. Error Conditions
For either form of assertion, the server MUST verify that the
client's authentication identity as supplied in its TLS credentials
is permitted to be mapped to the asserted authorization identity. The
server MUST reject the Bind operation with an invalidCredentials
resultCode in the Bind response if the client is not so authorized.
Additionally, with either form of assertion, if a TLS session has not
been established between the client and server prior to making the
SASL EXTERNAL Bind request and there is no other external source of
authentication credentials (e.g. IP-level security [IPSEC]), or if,
during the process of establishing th
1.1 jakarta-james/www/rfclist/ldap/rfc3377.txt
Index: rfc3377.txt
===================================================================
Network Working Group J. Hodges
Request for Comments: 3377 Sun Microsystems Inc.
Category: Standards Track R. Morgan
University of Washington
September 2002
Lightweight Directory Access Protocol (v3):
Technical Specification
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
This document specifies the set of RFCs comprising the Lightweight
Directory Access Protocol Version 3 (LDAPv3), and addresses the "IESG
Note" attached to RFCs 2251 through 2256.
1. Background and Motivation
The specification for the Lightweight Directory Access Protocol
version 3 (LDAPv3) nominally comprises eight RFCs which were issued
in two distinct subsets at separate times -- RFCs 2251 through 2256
first, then RFCs 2829 and 2830 following later.
RFC 2251 through 2256 do not mandate the implementation of any
satisfactory authentication mechanisms and hence were published with
an "IESG Note" discouraging implementation and deployment of LDAPv3
clients or servers implementing update functionality until a Proposed
Standard for mandatory authentication in LDAPv3 is published.
RFC 2829 was subsequently published in answer to the IESG Note.
The purpose of this document is to explicitly specify the set of RFCs
comprising LDAPv3, and formally address the IESG Note through
explicit inclusion of RFC 2829.
Hodges & Morgan Standards Track [Page 1]
RFC 3377 LDAPv3: Technical Specification September 2002
2. Specification of LDAPv3
The Lightweight Directory Access Protocol version 3 (LDAPv3) is
specified by this set of nine RFCs:
[RFC2251] Lightweight Directory Access Protocol (v3) [the
specification of the LDAP on-the-wire protocol]
[RFC2252] Lightweight Directory Access Protocol (v3): Attribute
Syntax Definitions
[RFC2253] Lightweight Directory Access Protocol (v3): UTF-8
String Representation of Distinguished Names
[RFC2254] The String Representation of LDAP Search Filters
[RFC2255] The LDAP URL Format
[RFC2256] A Summary of the X.500(96) User Schema for use with
LDAPv3
[RFC2829] Authentication Methods for LDAP
[RFC2830] Lightweight Directory Access Protocol (v3): Extension
for Transport Layer Security
And, this document (RFC3377).
The term "LDAPv3" is often used informally to refer to the protocol
specified by the above set of RFCs, or subsets thereof. However, the
LDAPv3 protocol suite, as defined here, should be formally identified
in other documents by a normative reference to this document.
3. Addressing the "IESG Note" in RFCs 2251 through 2256
The IESG approved publishing RFCs 2251 through 2256 with an attendant
IESG Note included in each document. The Note begins with:
This document describes a directory access protocol that provides
both read and update access. Update access requires secure
authentication, but this document does not mandate implementation
of any satisfactory authentication mechanisms.
Hodges & Morgan Standards Track [Page 2]
RFC 3377 LDAPv3: Technical Specification September 2002
The Note ends with this statement:
Implementors are hereby discouraged from deploying LDAPv3 clients
or servers which implement the update functionality, until a
Proposed Standard for mandatory authentication in LDAPv3 has been
approved and published as an RFC.
[RFC2829] is expressly the "Proposed Standard for mandatory
authentication in LDAPv3" called for in the Note. Thus, the IESG
Note in [RFC2251], [RFC2252], [RFC2253], [RFC2254], [RFC2255], and
[RFC2256] is addressed.
4. Security Considerations
This document does not directly discuss security, although the
context of the aforementioned IESG Note is security related, as is
the manner in which it is addressed.
Please refer to the referenced documents, especially [RFC2829],
[RFC2251], and [RFC2830], for further information concerning LDAPv3
security.
5. Acknowledgements
The authors thank Patrik Faltstrom, Leslie Daigle, Thomas Narten, and
Kurt Zeilenga for their contributions to this document.
6. References
[RFC2251] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille,
"Lightweight Directory Access Protocol (v3): Attribute
Syntax Definitions", RFC 2252, December 1997.
[RFC2253] Kille, S., Wahl, M. and T. Howes, "Lightweight Directory
Access Protocol (v3): UTF-8 String Representation of
Distinguished Names", RFC 2253, December 1997.
[RFC2254] Howes, T., "The String Representation of LDAP Search
Filters", RFC 2254, December 1997.
[RFC2255] Howes, T. and 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.
Hodges & Morgan Standards Track [Page 3]
RFC 3377 LDAPv3: Technical Specification September 2002
[RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
"Authentication Methods for LDAP", RFC 2829, May 2000.
[RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory
Access Protocol (v3): Extension for Transport Layer
Security", RFC 2830, May 2000.
7. Intellectual Property Rights Notices
The IETF takes no position regarding the validity or scope of any
intellectual property 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; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication 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 implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Hodges & Morgan Standards Track [Page 4]
RFC 3377 LDAPv3: Technical Specification September 2002
8. Authors' Addresses
Jeff Hodges
Sun Microsystems, Inc.
901 San Antonio Road, USCA22-212
Palo Alto, CA 94303
USA
Phone: +1-408-276-5467
EMail: Jeff.Hodges@sun.com
RL "Bob" Morgan
Computing and Communications
University of Washington
Seattle, WA
USA
Phone: +1-206-221-3307
EMail: rlmorgan@washington.edu
Hodges & Morgan Standards Track [Page 5]
RFC 3377 LDAPv3: Technical Specification September 2002
9. Full Copyright Statement
Copyright (C) The Internet Society (2002). 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 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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Hodges & Morgan Standards Track [Page 6]
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>