]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc4515.txt
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / rfc / rfc4515.txt
1
2
3
4
5
6
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
12
13
14              Lightweight Directory Access Protocol (LDAP):
15                 String Representation of Search Filters
16
17 Status of This Memo
18
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.
24
25 Copyright Notice
26
27    Copyright (C) The Internet Society (2006).
28
29 Abstract
30
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.
37
38 Table of Contents
39
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
51
52
53
54
55
56
57
58 Smith and Howes             Standards Track                     [Page 1]
59 \f
60 RFC 4515     LDAP: String Representation of Search Filters     June 2006
61
62
63 1.  Introduction
64
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.
73
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.
77
78    This document replaces RFC 2254.  Changes to RFC 2254 are summarized
79    in Appendix A.
80
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].
84
85 2.  LDAP Search Filter Definition
86
87    An LDAP search filter is defined in Section 4.5.1 of [RFC4511] as
88    follows:
89
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 }
101
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 } }
109
110
111
112
113
114 Smith and Howes             Standards Track                     [Page 2]
115 \f
116 RFC 4515     LDAP: String Representation of Search Filters     June 2006
117
118
119         AttributeValueAssertion ::= SEQUENCE {
120             attributeDesc   AttributeDescription,
121             assertionValue  AssertionValue }
122
123         MatchingRuleAssertion ::= SEQUENCE {
124             matchingRule    [1] MatchingRuleId OPTIONAL,
125             type            [2] AttributeDescription OPTIONAL,
126             matchValue      [3] AssertionValue,
127             dnAttributes    [4] BOOLEAN DEFAULT FALSE }
128
129         AttributeDescription ::= LDAPString
130                         -- Constrained to <attributedescription>
131                         -- [RFC4512]
132
133         AttributeValue ::= OCTET STRING
134
135         MatchingRuleId ::= LDAPString
136
137         AssertionValue ::= OCTET STRING
138
139         LDAPString ::= OCTET STRING -- UTF-8 encoded,
140                                     -- [Unicode] characters
141
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].
148
149 3.  String Search Filter Definition
150
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.
157
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
167
168
169
170 Smith and Howes             Standards Track                     [Page 3]
171 \f
172 RFC 4515     LDAP: String Representation of Search Filters     June 2006
173
174
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 ("~")
208
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.
212
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.
219
220
221
222
223
224
225
226 Smith and Howes             Standards Track                     [Page 4]
227 \f
228 RFC 4515     LDAP: String Representation of Search Filters     June 2006
229
230
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.
236
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*)".
243
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).
252
253 4.  Examples
254
255    This section gives a few examples of search filters written using
256    this notation.
257
258         (cn=Babs Jensen)
259         (!(cn=Tim Howes))
260         (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
261         (o=univ*of*mich*)
262         (seeAlso=)
263
264    The following examples illustrate the use of extensible matching.
265
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)
272
273    The first example shows use of the matching rule "caseExactMatch."
274
275    The second example demonstrates use of a MatchingRuleAssertion form
276    without a matchingRule.
277
278
279
280
281
282 Smith and Howes             Standards Track                     [Page 5]
283 \f
284 RFC 4515     LDAP: String Representation of Search Filters     June 2006
285
286
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").
292
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.
296
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).
300
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.
305
306    The following examples illustrate the use of the escaping mechanism.
307
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)
314
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.
320
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.
324
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).
331
332    The sixth and final example demonstrates assertion of a BER-encoded
333    value.
334
335
336
337
338 Smith and Howes             Standards Track                     [Page 6]
339 \f
340 RFC 4515     LDAP: String Representation of Search Filters     June 2006
341
342
343 5.  Security Considerations
344
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.
350
351    Please refer to the Security Considerations sections of [RFC4511] and
352    [RFC4513] for more information.
353
354 6.  Normative References
355
356    [RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
357                Requirement Levels", BCP 14, RFC 2119, March 1997.
358
359    [RFC3629]   Yergeau, F., "UTF-8, a transformation format of ISO
360                10646", STD 63, RFC 3629, November 2003.
361
362    [RFC4234]   Crocker, D. and P. Overell, "Augmented BNF for Syntax
363                Specifications: ABNF", RFC 4234, October 2005.
364
365    [RFC4510]   Zeilenga, K., Ed., "Lightweight Directory Access Protocol
366                (LDAP): Technical Specification Road Map", RFC 4510, June
367                2006.
368
369    [RFC4511]   Sermersheim, J., Ed., "Lightweight Directory Access
370                Protocol (LDAP): The Protocol", RFC 4511, June 2006.
371
372    [RFC4512]   Zeilenga, K., "Lightweight Directory Access Protocol
373                (LDAP): Directory Information Models", RFC 4512, June
374                2006.
375
376    [RFC4513]   Harrison, R., Ed., "Lightweight Directory Access Protocol
377                (LDAP): Authentication Methods and Security Mechanisms",
378                RFC 4513, June 2006.
379
380    [RFC4517]   Legg, S., Ed., "Lightweight Directory Access Protocol
381                (LDAP): Syntaxes and Matching Rules", RFC 4517, June
382                2006.
383
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."
390
391
392
393
394 Smith and Howes             Standards Track                     [Page 7]
395 \f
396 RFC 4515     LDAP: String Representation of Search Filters     June 2006
397
398
399 7.  Informative References
400
401    [RFC4516]   Smith, M., Ed. and T. Howes, "Lightweight Directory
402                Access Protocol (LDAP): Uniform Resource Locator", RFC
403                4516, June 2006.
404
405    [X.690]     Specification of ASN.1 encoding rules: Basic, Canonical,
406                and Distinguished Encoding Rules, ITU-T Recommendation
407                X.690, 1994.
408
409 8.  Acknowledgements
410
411    This document replaces RFC 2254 by Tim Howes.  RFC 2254 was a product
412    of the IETF ASID Working Group.
413
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.
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450 Smith and Howes             Standards Track                     [Page 8]
451 \f
452 RFC 4515     LDAP: String Representation of Search Filters     June 2006
453
454
455 Appendix A: Changes Since RFC 2254
456
457 A.1.  Technical Changes
458
459    Replaced [ISO 10646] reference with [Unicode].
460
461    The following technical changes were made to the contents of the
462    "String Search Filter Definition" section:
463
464    Added statement that the string representation is a string of UTF-8-
465    encoded Unicode characters.
466
467    Revised all of the ABNF to use common productions from [RFC4512].
468
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].
472
473    Added "(" and ")" around the components of the <extensible>
474    subproductions for clarity.
475
476    Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
477    precisely reference productions from the [RFC4512] and [RFC4511]
478    documents.
479
480    "String Search Filter Definition" section: replaced "greater" and
481    "less" with "greaterorequal" and "lessorequal" to avoid confusion.
482
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.
486
487    Added a statement about expected behavior in light of RFC 2254's lack
488    of a clear definition of "string representation."
489
490 A.2.  Editorial Changes
491
492    Changed document title to include "LDAP:" prefix.
493
494    IESG Note: removed note about lack of satisfactory mandatory
495    authentication mechanisms.
496
497    Header and "Authors' Addresses" sections: added Mark Smith as the
498    document editor and updated affiliation and contact information.
499
500    "Table of Contents" and "Intellectual Property" sections: added.
501
502    Copyright: updated per latest IETF guidelines.
503
504
505
506 Smith and Howes             Standards Track                     [Page 9]
507 \f
508 RFC 4515     LDAP: String Representation of Search Filters     June 2006
509
510
511    "Abstract" section: separated from introductory material.
512
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.
517
518    "LDAP Search Filter Definition" section: made corrections to the LDAP
519    search filter ABNF so it matches that used in [RFC4511].
520
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.
527
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.
540
541    "Security Considerations" section: added references to [RFC4511] and
542    [RFC4513].
543
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.
549
550    "Informative References" section: (new section) moved [X.690] to this
551    section.  Added a reference to [RFC4516].
552
553    "Acknowledgements" section: added.
554
555    "Appendix A: Changes Since RFC 2254" section: added.
556
557    Surrounded the names of all ABNF productions with "<" and ">" where
558    they are used in descriptive text.
559
560
561
562 Smith and Howes             Standards Track                    [Page 10]
563 \f
564 RFC 4515     LDAP: String Representation of Search Filters     June 2006
565
566
567    Replaced all occurrences of "LDAPv3" with "LDAP."
568
569 Authors' Addresses
570
571    Mark Smith, Editor
572    Pearl Crescent, LLC
573    447 Marlpool Dr.
574    Saline, MI 48176
575    USA
576
577    Phone: +1 734 944-2856
578    EMail: mcs@pearlcrescent.com
579
580
581    Tim Howes
582    Opsware, Inc.
583    599 N. Mathilda Ave.
584    Sunnyvale, CA 94085
585    USA
586
587    Phone: +1 408 744-7509
588    EMail: howes@opsware.com
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618 Smith and Howes             Standards Track                    [Page 11]
619 \f
620 RFC 4515     LDAP: String Representation of Search Filters     June 2006
621
622
623 Full Copyright Statement
624
625    Copyright (C) The Internet Society (2006).
626
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.
630
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.
638
639 Intellectual Property
640
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.
649
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.
656
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.
662
663 Acknowledgement
664
665    Funding for the RFC Editor function is provided by the IETF
666    Administrative Support Activity (IASA).
667
668
669
670
671
672
673
674 Smith and Howes             Standards Track                    [Page 12]
675 \f