s4:smbd/open: add missing TALLOC_FREE(frame) to inherit_new_acl()
[Samba/gebeck_regimport.git] / source4 / ldap_server / devdocs / rfc4515.txt
blob86f03ebcd3501f1e186a078877d5d44f6072d029
7 Network Working Group                                      M. Smith, Ed.
8 Request for Comments: 4515                           Pearl Crescent, LLC
9 Obsoletes: 2254                                                 T. Howes
10 Category: Standards Track                                  Opsware, Inc.
11                                                                June 2006
14              Lightweight Directory Access Protocol (LDAP):
15                 String Representation of Search Filters
17 Status of This Memo
19    This document specifies an Internet standards track protocol for the
20    Internet community, and requests discussion and suggestions for
21    improvements.  Please refer to the current edition of the "Internet
22    Official Protocol Standards" (STD 1) for the standardization state
23    and status of this protocol.  Distribution of this memo is unlimited.
25 Copyright Notice
27    Copyright (C) The Internet Society (2006).
29 Abstract
31    Lightweight Directory Access Protocol (LDAP) search filters are
32    transmitted in the LDAP protocol using a binary representation that
33    is appropriate for use on the network.  This document defines a
34    human-readable string representation of LDAP search filters that is
35    appropriate for use in LDAP URLs (RFC 4516) and in other
36    applications.
38 Table of Contents
40    1. Introduction ....................................................2
41    2. LDAP Search Filter Definition ...................................2
42    3. String Search Filter Definition .................................3
43    4. Examples ........................................................5
44    5. Security Considerations .........................................7
45    6. Normative References ............................................7
46    7. Informative References ..........................................8
47    8. Acknowledgements ................................................8
48    Appendix A: Changes Since RFC 2254 .................................9
49       A.1. Technical Changes ..........................................9
50       A.2. Editorial Changes ..........................................9
58 Smith and Howes             Standards Track                     [Page 1]
60 RFC 4515     LDAP: String Representation of Search Filters     June 2006
63 1.  Introduction
65    The Lightweight Directory Access Protocol (LDAP) [RFC4510] defines a
66    network representation of a search filter transmitted to an LDAP
67    server.  Some applications may find it useful to have a common way of
68    representing these search filters in a human-readable form; LDAP URLs
69    [RFC4516] are an example of one such application.  This document
70    defines a human-readable string format for representing the full
71    range of possible LDAP version 3 search filters, including extended
72    match filters.
74    This document is a integral part of the LDAP technical specification
75    [RFC4510], which obsoletes the previously defined LDAP technical
76    specification, RFC 3377, in its entirety.
78    This document replaces RFC 2254.  Changes to RFC 2254 are summarized
79    in Appendix A.
81    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
82    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
83    document are to be interpreted as described in BCP 14 [RFC2119].
85 2.  LDAP Search Filter Definition
87    An LDAP search filter is defined in Section 4.5.1 of [RFC4511] as
88    follows:
90         Filter ::= CHOICE {
91             and                [0] SET SIZE (1..MAX) OF filter Filter,
92             or                 [1] SET SIZE (1..MAX) OF filter Filter,
93             not                [2] Filter,
94             equalityMatch      [3] AttributeValueAssertion,
95             substrings         [4] SubstringFilter,
96             greaterOrEqual     [5] AttributeValueAssertion,
97             lessOrEqual        [6] AttributeValueAssertion,
98             present            [7] AttributeDescription,
99             approxMatch        [8] AttributeValueAssertion,
100             extensibleMatch    [9] MatchingRuleAssertion }
102         SubstringFilter ::= SEQUENCE {
103             type    AttributeDescription,
104             -- initial and final can occur at most once
105             substrings    SEQUENCE SIZE (1..MAX) OF substring CHOICE {
106              initial        [0] AssertionValue,
107              any            [1] AssertionValue,
108              final          [2] AssertionValue } }
114 Smith and Howes             Standards Track                     [Page 2]
116 RFC 4515     LDAP: String Representation of Search Filters     June 2006
119         AttributeValueAssertion ::= SEQUENCE {
120             attributeDesc   AttributeDescription,
121             assertionValue  AssertionValue }
123         MatchingRuleAssertion ::= SEQUENCE {
124             matchingRule    [1] MatchingRuleId OPTIONAL,
125             type            [2] AttributeDescription OPTIONAL,
126             matchValue      [3] AssertionValue,
127             dnAttributes    [4] BOOLEAN DEFAULT FALSE }
129         AttributeDescription ::= LDAPString
130                         -- Constrained to <attributedescription>
131                         -- [RFC4512]
133         AttributeValue ::= OCTET STRING
135         MatchingRuleId ::= LDAPString
137         AssertionValue ::= OCTET STRING
139         LDAPString ::= OCTET STRING -- UTF-8 encoded,
140                                     -- [Unicode] characters
142    The AttributeDescription, as defined in [RFC4511], is a string
143    representation of the attribute description that is discussed in
144    [RFC4512].  The AttributeValue and AssertionValue OCTET STRING have
145    the form defined in [RFC4517].  The Filter is encoded for
146    transmission over a network using the Basic Encoding Rules (BER)
147    defined in [X.690], with simplifications described in [RFC4511].
149 3.  String Search Filter Definition
151    The string representation of an LDAP search filter is a string of
152    UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined
153    by the following grammar, following the ABNF notation defined in
154    [RFC4234].  The productions used that are not defined here are
155    defined in Section 1.4 (Common ABNF Productions) of [RFC4512] unless
156    otherwise noted.  The filter format uses a prefix notation.
158       filter         = LPAREN filtercomp RPAREN
159       filtercomp     = and / or / not / item
160       and            = AMPERSAND filterlist
161       or             = VERTBAR filterlist
162       not            = EXCLAMATION filter
163       filterlist     = 1*filter
164       item           = simple / present / substring / extensible
165       simple         = attr filtertype assertionvalue
166       filtertype     = equal / approx / greaterorequal / lessorequal
170 Smith and Howes             Standards Track                     [Page 3]
172 RFC 4515     LDAP: String Representation of Search Filters     June 2006
175       equal          = EQUALS
176       approx         = TILDE EQUALS
177       greaterorequal = RANGLE EQUALS
178       lessorequal    = LANGLE EQUALS
179       extensible     = ( attr [dnattrs]
180                            [matchingrule] COLON EQUALS assertionvalue )
181                        / ( [dnattrs]
182                             matchingrule COLON EQUALS assertionvalue )
183       present        = attr EQUALS ASTERISK
184       substring      = attr EQUALS [initial] any [final]
185       initial        = assertionvalue
186       any            = ASTERISK *(assertionvalue ASTERISK)
187       final          = assertionvalue
188       attr           = attributedescription
189                          ; The attributedescription rule is defined in
190                          ; Section 2.5 of [RFC4512].
191       dnattrs        = COLON "dn"
192       matchingrule   = COLON oid
193       assertionvalue = valueencoding
194       ; The <valueencoding> rule is used to encode an <AssertionValue>
195       ; from Section 4.1.6 of [RFC4511].
196       valueencoding  = 0*(normal / escaped)
197       normal         = UTF1SUBSET / UTFMB
198       escaped        = ESC HEX HEX
199       UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F
200                           ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
201                           ; RPAREN, ASTERISK, and ESC.
202       EXCLAMATION    = %x21 ; exclamation mark ("!")
203       AMPERSAND      = %x26 ; ampersand (or AND symbol) ("&")
204       ASTERISK       = %x2A ; asterisk ("*")
205       COLON          = %x3A ; colon (":")
206       VERTBAR        = %x7C ; vertical bar (or pipe) ("|")
207       TILDE          = %x7E ; tilde ("~")
209    Note that although both the <substring> and <present> productions in
210    the grammar above can produce the "attr=*" construct, this construct
211    is used only to denote a presence filter.
213    The <valueencoding> rule ensures that the entire filter string is a
214    valid UTF-8 string and provides that the octets that represent the
215    ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII
216    0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a
217    backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits
218    representing the value of the encoded octet.
226 Smith and Howes             Standards Track                     [Page 4]
228 RFC 4515     LDAP: String Representation of Search Filters     June 2006
231    This simple escaping mechanism eliminates filter-parsing ambiguities
232    and allows any filter that can be represented in LDAP to be
233    represented as a NUL-terminated string.  Other octets that are part
234    of the <normal> set may be escaped using this mechanism, for example,
235    non-printing ASCII characters.
237    For AssertionValues that contain UTF-8 character data, each octet of
238    the character to be escaped is replaced by a backslash and two hex
239    digits, which form a single octet in the code of the character.  For
240    example, the filter checking whether the "cn" attribute contained a
241    value with the character "*" anywhere in it would be represented as
242    "(cn=*\2a*)".
244    As indicated by the <valueencoding> rule, implementations MUST escape
245    all octets greater than 0x7F that are not part of a valid UTF-8
246    encoding sequence when they generate a string representation of a
247    search filter.  Implementations SHOULD accept as input strings that
248    are not valid UTF-8 strings.  This is necessary because RFC 2254 did
249    not clearly define the term "string representation" (and in
250    particular did not mention that the string representation of an LDAP
251    search filter is a string of UTF-8-encoded Unicode characters).
253 4.  Examples
255    This section gives a few examples of search filters written using
256    this notation.
258         (cn=Babs Jensen)
259         (!(cn=Tim Howes))
260         (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
261         (o=univ*of*mich*)
262         (seeAlso=)
264    The following examples illustrate the use of extensible matching.
266         (cn:caseExactMatch:=Fred Flintstone)
267         (cn:=Betty Rubble)
268         (sn:dn:2.4.6.8.10:=Barney Rubble)
269         (o:dn:=Ace Industry)
270         (:1.2.3:=Wilma Flintstone)
271         (:DN:2.4.6.8.10:=Dino)
273    The first example shows use of the matching rule "caseExactMatch."
275    The second example demonstrates use of a MatchingRuleAssertion form
276    without a matchingRule.
282 Smith and Howes             Standards Track                     [Page 5]
284 RFC 4515     LDAP: String Representation of Search Filters     June 2006
287    The third example illustrates the use of the ":oid" notation to
288    indicate that the matching rule identified by the OID "2.4.6.8.10"
289    should be used when making comparisons, and that the attributes of an
290    entry's distinguished name should be considered part of the entry
291    when evaluating the match (indicated by the use of ":dn").
293    The fourth example denotes an equality match, except that DN
294    components should be considered part of the entry when doing the
295    match.
297    The fifth example is a filter that should be applied to any attribute
298    supporting the matching rule given (since the <attr> has been
299    omitted).
301    The sixth and final example is also a filter that should be applied
302    to any attribute supporting the matching rule given.  Attributes
303    supporting the matching rule contained in the DN should also be
304    considered.
306    The following examples illustrate the use of the escaping mechanism.
308         (o=Parens R Us \28for all your parenthetical needs\29)
309         (cn=*\2A*)
310         (filename=C:\5cMyFile)
311         (bin=\00\00\00\04)
312         (sn=Lu\c4\8di\c4\87)
313         (1.3.6.1.4.1.1466.0=\04\02\48\69)
315    The first example shows the use of the escaping mechanism to
316    represent parenthesis characters.  The second shows how to represent
317    a "*" in an assertion value, preventing it from being interpreted as
318    a substring indicator.  The third illustrates the escaping of the
319    backslash character.
321    The fourth example shows a filter searching for the four-octet value
322    00 00 00 04 (hex), illustrating the use of the escaping mechanism to
323    represent arbitrary data, including NUL characters.
325    The fifth example illustrates the use of the escaping mechanism to
326    represent various non-ASCII UTF-8 characters.  Specifically, there
327    are 5 characters in the <assertionvalue> portion of this example:
328    LATIN CAPITAL LETTER L (U+004C), LATIN SMALL LETTER U (U+0075), LATIN
329    SMALL LETTER C WITH CARON (U+010D), LATIN SMALL LETTER I (U+0069),
330    and LATIN SMALL LETTER C WITH ACUTE (U+0107).
332    The sixth and final example demonstrates assertion of a BER-encoded
333    value.
338 Smith and Howes             Standards Track                     [Page 6]
340 RFC 4515     LDAP: String Representation of Search Filters     June 2006
343 5.  Security Considerations
345    This memo describes a string representation of LDAP search filters.
346    While the representation itself has no known security implications,
347    LDAP search filters do.  They are interpreted by LDAP servers to
348    select entries from which data is retrieved.  LDAP servers should
349    take care to protect the data they maintain from unauthorized access.
351    Please refer to the Security Considerations sections of [RFC4511] and
352    [RFC4513] for more information.
354 6.  Normative References
356    [RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
357                Requirement Levels", BCP 14, RFC 2119, March 1997.
359    [RFC3629]   Yergeau, F., "UTF-8, a transformation format of ISO
360                10646", STD 63, RFC 3629, November 2003.
362    [RFC4234]   Crocker, D. and P. Overell, "Augmented BNF for Syntax
363                Specifications: ABNF", RFC 4234, October 2005.
365    [RFC4510]   Zeilenga, K., Ed., "Lightweight Directory Access Protocol
366                (LDAP): Technical Specification Road Map", RFC 4510, June
367                2006.
369    [RFC4511]   Sermersheim, J., Ed., "Lightweight Directory Access
370                Protocol (LDAP): The Protocol", RFC 4511, June 2006.
372    [RFC4512]   Zeilenga, K., "Lightweight Directory Access Protocol
373                (LDAP): Directory Information Models", RFC 4512, June
374                2006.
376    [RFC4513]   Harrison, R., Ed., "Lightweight Directory Access Protocol
377                (LDAP): Authentication Methods and Security Mechanisms",
378                RFC 4513, June 2006.
380    [RFC4517]   Legg, S., Ed., "Lightweight Directory Access Protocol
381                (LDAP): Syntaxes and Matching Rules", RFC 4517, June
382                2006.
384    [Unicode]   The Unicode Consortium, "The Unicode Standard, Version
385                3.2.0" is defined by "The Unicode Standard, Version 3.0"
386                (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
387                as amended by the "Unicode Standard Annex #27: Unicode
388                3.1" (http://www.unicode.org/reports/tr27/) and by the
389                "Unicode Standard Annex #28: Unicode 3.2."
394 Smith and Howes             Standards Track                     [Page 7]
396 RFC 4515     LDAP: String Representation of Search Filters     June 2006
399 7.  Informative References
401    [RFC4516]   Smith, M., Ed. and T. Howes, "Lightweight Directory
402                Access Protocol (LDAP): Uniform Resource Locator", RFC
403                4516, June 2006.
405    [X.690]     Specification of ASN.1 encoding rules: Basic, Canonical,
406                and Distinguished Encoding Rules, ITU-T Recommendation
407                X.690, 1994.
409 8.  Acknowledgements
411    This document replaces RFC 2254 by Tim Howes.  RFC 2254 was a product
412    of the IETF ASID Working Group.
414    Changes included in this revised specification are based upon
415    discussions among the authors, discussions within the LDAP (v3)
416    Revision Working Group (ldapbis), and discussions within other IETF
417    Working Groups.  The contributions of individuals in these working
418    groups is gratefully acknowledged.
450 Smith and Howes             Standards Track                     [Page 8]
452 RFC 4515     LDAP: String Representation of Search Filters     June 2006
455 Appendix A: Changes Since RFC 2254
457 A.1.  Technical Changes
459    Replaced [ISO 10646] reference with [Unicode].
461    The following technical changes were made to the contents of the
462    "String Search Filter Definition" section:
464    Added statement that the string representation is a string of UTF-8-
465    encoded Unicode characters.
467    Revised all of the ABNF to use common productions from [RFC4512].
469    Replaced the "value" rule with a new "assertionvalue" rule within the
470    "simple", "extensible", and "substring" ("initial", "any", and
471    "final") rules.  This matches a change made in [RFC4517].
473    Added "(" and ")" around the components of the <extensible>
474    subproductions for clarity.
476    Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
477    precisely reference productions from the [RFC4512] and [RFC4511]
478    documents.
480    "String Search Filter Definition" section: replaced "greater" and
481    "less" with "greaterorequal" and "lessorequal" to avoid confusion.
483    Introduced the "valueencoding" and associated "normal" and "escaped"
484    rules to reduce the dependence on descriptive text.  The "normal"
485    production restricts filter strings to valid UTF-8 sequences.
487    Added a statement about expected behavior in light of RFC 2254's lack
488    of a clear definition of "string representation."
490 A.2.  Editorial Changes
492    Changed document title to include "LDAP:" prefix.
494    IESG Note: removed note about lack of satisfactory mandatory
495    authentication mechanisms.
497    Header and "Authors' Addresses" sections: added Mark Smith as the
498    document editor and updated affiliation and contact information.
500    "Table of Contents" and "Intellectual Property" sections: added.
502    Copyright: updated per latest IETF guidelines.
506 Smith and Howes             Standards Track                     [Page 9]
508 RFC 4515     LDAP: String Representation of Search Filters     June 2006
511    "Abstract" section: separated from introductory material.
513    "Introduction" section: new section; separated from the Abstract.
514    Updated second paragraph to indicate that RFC 2254 is replaced by
515    this document (instead of RFC 1960).  Added reference to the
516    [RFC4510] document.
518    "LDAP Search Filter Definition" section: made corrections to the LDAP
519    search filter ABNF so it matches that used in [RFC4511].
521    Clarified the definition of 'value' (now 'assertionvalue') to take
522    into account the fact that it is not precisely an AttributeAssertion
523    from [RFC4511] Section 4.1.6 (special handling is required for some
524    characters).  Added a note that each octet of a character to be
525    escaped is replaced by a backslash and two hex digits, which
526    represent a single octet.
528    "Examples" section: added four additional examples: (seeAlso=),
529    (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and
530    (1.3.6.1.4.1.1466.0=\04\02\48\69).  Replaced one occurrence of "a
531    value" with "an assertion value".  Corrected the description of this
532    example: (sn:dn:2.4.6.8.10:=Barney Rubble).  Replaced the numeric OID
533    in the first extensible match example with "caseExactMatch" to
534    demonstrate use of the descriptive form.  Used "DN" (uppercase) in
535    the last extensible match example to remind the reader to treat the
536    <dnattrs> production as case insensitive.  Reworded the description
537    of the fourth escaping mechanism example to avoid making assumptions
538    about byte order.  Added text to the fifth escaping mechanism example
539    to spell out what the non-ASCII characters are in Unicode terms.
541    "Security Considerations" section: added references to [RFC4511] and
542    [RFC4513].
544    "Normative References" section: renamed from "References" per new RFC
545    guidelines.  Changed from [1] style to [RFC4511] style throughout the
546    document.  Added entries for [Unicode], [RFC2119], [RFC4513],
547    [RFC4512], and [RFC4510] and updated the UTF-8 reference.  Replaced
548    RFC 822 reference with a reference to RFC 4234.
550    "Informative References" section: (new section) moved [X.690] to this
551    section.  Added a reference to [RFC4516].
553    "Acknowledgements" section: added.
555    "Appendix A: Changes Since RFC 2254" section: added.
557    Surrounded the names of all ABNF productions with "<" and ">" where
558    they are used in descriptive text.
562 Smith and Howes             Standards Track                    [Page 10]
564 RFC 4515     LDAP: String Representation of Search Filters     June 2006
567    Replaced all occurrences of "LDAPv3" with "LDAP."
569 Authors' Addresses
571    Mark Smith, Editor
572    Pearl Crescent, LLC
573    447 Marlpool Dr.
574    Saline, MI 48176
575    USA
577    Phone: +1 734 944-2856
578    EMail: mcs@pearlcrescent.com
581    Tim Howes
582    Opsware, Inc.
583    599 N. Mathilda Ave.
584    Sunnyvale, CA 94085
585    USA
587    Phone: +1 408 744-7509
588    EMail: howes@opsware.com
618 Smith and Howes             Standards Track                    [Page 11]
620 RFC 4515     LDAP: String Representation of Search Filters     June 2006
623 Full Copyright Statement
625    Copyright (C) The Internet Society (2006).
627    This document is subject to the rights, licenses and restrictions
628    contained in BCP 78, and except as set forth therein, the authors
629    retain all their rights.
631    This document and the information contained herein are provided on an
632    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
633    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
634    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
635    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
636    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
637    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
639 Intellectual Property
641    The IETF takes no position regarding the validity or scope of any
642    Intellectual Property Rights or other rights that might be claimed to
643    pertain to the implementation or use of the technology described in
644    this document or the extent to which any license under such rights
645    might or might not be available; nor does it represent that it has
646    made any independent effort to identify any such rights.  Information
647    on the procedures with respect to rights in RFC documents can be
648    found in BCP 78 and BCP 79.
650    Copies of IPR disclosures made to the IETF Secretariat and any
651    assurances of licenses to be made available, or the result of an
652    attempt made to obtain a general license or permission for the use of
653    such proprietary rights by implementers or users of this
654    specification can be obtained from the IETF on-line IPR repository at
655    http://www.ietf.org/ipr.
657    The IETF invites any interested party to bring to its attention any
658    copyrights, patents or patent applications, or other proprietary
659    rights that may cover technology that may be required to implement
660    this standard.  Please address the information to the IETF at
661    ietf-ipr@ietf.org.
663 Acknowledgement
665    Funding for the RFC Editor function is provided by the IETF
666    Administrative Support Activity (IASA).
674 Smith and Howes             Standards Track                    [Page 12]