1
2
3
4
5
6
7Network Working Group                                      M. Smith, Ed.
8Request for Comments: 4515                           Pearl Crescent, LLC
9Obsoletes: 2254                                                 T. Howes
10Category: Standards Track                                  Opsware, Inc.
11                                                               June 2006
12
13
14             Lightweight Directory Access Protocol (LDAP):
15                String Representation of Search Filters
16
17Status 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
25Copyright Notice
26
27   Copyright (C) The Internet Society (2006).
28
29Abstract
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
38Table 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
58Smith and Howes             Standards Track                     [Page 1]
59
60RFC 4515     LDAP: String Representation of Search Filters     June 2006
61
62
631.  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
852.  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
114Smith and Howes             Standards Track                     [Page 2]
115
116RFC 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
1493.  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
170Smith and Howes             Standards Track                     [Page 3]
171
172RFC 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
226Smith and Howes             Standards Track                     [Page 4]
227
228RFC 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
2534.  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
282Smith and Howes             Standards Track                     [Page 5]
283
284RFC 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
338Smith and Howes             Standards Track                     [Page 6]
339
340RFC 4515     LDAP: String Representation of Search Filters     June 2006
341
342
3435.  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
3546.  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
394Smith and Howes             Standards Track                     [Page 7]
395
396RFC 4515     LDAP: String Representation of Search Filters     June 2006
397
398
3997.  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
4098.  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
450Smith and Howes             Standards Track                     [Page 8]
451
452RFC 4515     LDAP: String Representation of Search Filters     June 2006
453
454
455Appendix A: Changes Since RFC 2254
456
457A.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
490A.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
506Smith and Howes             Standards Track                     [Page 9]
507
508RFC 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
562Smith and Howes             Standards Track                    [Page 10]
563
564RFC 4515     LDAP: String Representation of Search Filters     June 2006
565
566
567   Replaced all occurrences of "LDAPv3" with "LDAP."
568
569Authors' 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
618Smith and Howes             Standards Track                    [Page 11]
619
620RFC 4515     LDAP: String Representation of Search Filters     June 2006
621
622
623Full 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
639Intellectual 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
663Acknowledgement
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
674Smith and Howes             Standards Track                    [Page 12]
675
676