sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-11-06 08:23:50 +03:00
Code Activity

r2758: keep docos handy while developing it

Browse Source
This commit is contained in:
Simo Sorce
2004-09-30 16:08:09 +00:00
committed by Gerald (Jerry) Carter
parent 991b4777c8
commit 5f9b58c785
6 changed files with 5674 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1795
source/ldap_server/devdocs/rfc2252.txt Normal file
View File

File diff suppressed because it is too large Load Diff

563
source/ldap_server/devdocs/rfc2253.txt Normal file
View File

@@ -0,0 +1,563 @@
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 View, CA 94043
USA
Phone: +1 650 937-3419
EMail: howes@netscape.com
Wahl, et. al. Proposed Standard [Page 9]
RFC 2253 LADPv3 Distinguished Names 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.
Wahl, et. al. Proposed Standard [Page 10]

451
source/ldap_server/devdocs/rfc2254.txt Normal file
View File

@@ -0,0 +1,451 @@
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]

563
source/ldap_server/devdocs/rfc2255.txt Normal file
View File

@@ -0,0 +1,563 @@
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 easily-abused information to the remote server
or to eavesdroppers in transit, and should not be used in URL
processing unless explicitly permitted by policy. Confirmation by
the human user of the use of authentication information is
appropriate in many circumstances. Use of strong authentication
methods that do not reveal sensitive information is much preferred.
The LDAP URL format allows the specification of an arbitrary LDAP
search operation to be performed when evaluating the LDAP URL.
Following an LDAP URL may cause unexpected results, for example, the
retrieval of large amounts of data, the initiation of a long-lived
search, etc. The security implications of resolving an LDAP URL are
the same as those of resolving an LDAP search query.
8. Acknowledgements
The LDAP URL format was originally defined at the University of
Michigan. This material is based upon work supported by the National
Science Foundation under Grant No. NCR-9416667. The support of both
the University of Michigan and the National Science Foundation is
gratefully acknowledged.
Howes & Smith Standards Track [Page 8]
RFC 2255 LDAP URL Format December 1997
Several people have made valuable comments on this document. In
particular RL "Bob" Morgan and Mark Wahl deserve special thanks for
their contributions.
9. References
[1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access
Protocol (v3): UTF-8 String Representation of Distinguished Names",
RFC 2253, December 1997.
[2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
[3] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
Directory Access Protocol (v3): Attribute Syntax Definitions", RFC
2252, December 1997.
[4] Howes, T., "A String Representation of LDAP Search Filters", RFC
2254, December 1997.
[5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
Locators (URL)," RFC 1738, December 1994.
[6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement
Levels," RFC 2119, March 1997.
Authors' Addresses
Tim Howes
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
Phone: +1 415 937-3419
EMail: howes@netscape.com
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
Phone: +1 415 937-3477
EMail: mcs@netscape.com
Howes & Smith Standards Track [Page 9]
RFC 2255 LDAP URL Format 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.
Howes & Smith Standards Track [Page 10]

1123
source/ldap_server/devdocs/rfc2256.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1179
source/ldap_server/devdocs/rfc2307.txt Normal file
View File

File diff suppressed because it is too large Load Diff