1 Network Working Group M. Smith, Editor
2 Request for Comments: DRAFT Pearl Crescent, LLC
3 Obsoletes: RFC 2254 T. Howes
4 Expires: 16 May 2005 Opsware, Inc.
8 LDAP: String Representation of Search Filters
9 <draft-ietf-ldapbis-filter-09.txt>
15 By submitting this Internet-Draft, each author represents that any
16 applicable patent or other IPR claims of which he or she is aware
17 have been or will be disclosed, and any of which he or she become
18 aware will be disclosed, in accordance with RFC 3668.
20 This document is intended to be published as a Standards Track RFC,
21 replacing RFC 2254. Distribution of this memo is unlimited.
22 Technical discussion of this document will take place on the IETF
23 LDAP (v3) Revision (ldapbis) Working Group mailing list
24 <ietf-ldapbis@openldap.org>. Please send editorial comments directly
25 to the editor <mcs@pearlcrescent.com>.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF), its areas, and its working groups. Note that
29 other groups may also distribute working documents as
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than a "work in progress."
37 The list of current Internet-Drafts can be accessed at
38 http://www.ietf.org/1id-abstracts.html
40 The list of Internet-Draft Shadow Directories can be accessed at
41 http://www.ietf.org/shadow.html
43 Copyright (C) The Internet Society (2004). All Rights Reserved.
44 Please see the Full Copyright section near the end of this document
52 Smith & Howes Intended Category: Standards Track [Page 1]
54 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
59 LDAP search filters are transmitted in the LDAP protocol using a
60 binary representation that is appropriate for use on the network.
61 This document defines a human-readable string representation of LDAP
62 search filters that is appropriate for use in LDAP URLs [LDAPURL] and
63 in other applications.
67 Status of this Memo............................................1
68 Abstract.......................................................2
69 Table of Contents..............................................2
70 1. Introduction...................................................2
71 2. LDAP Search Filter Definition..................................3
72 3. String Search Filter Definition................................4
73 4. Examples.......................................................6
74 5. Security Considerations........................................7
75 6. IANA Considerations............................................7
76 7. Normative References...........................................7
77 8. Informative References.........................................8
78 9. Acknowledgments................................................8
79 10. Authors' Addresses.............................................9
80 11. Appendix A: Changes Since RFC 2254.............................9
81 11.1. Technical Changes...........................................9
82 11.2. Editorial Changes...........................................10
83 12. Appendix B: Changes Since Previous Document Revision...........11
84 12.1. Technical Changes...........................................11
85 12.2. Editorial Changes...........................................12
86 Intellectual Property Rights...................................12
87 Full Copyright.................................................13
91 The Lightweight Directory Access Protocol (LDAP) [Roadmap] defines a
92 network representation of a search filter transmitted to an LDAP
93 server. Some applications may find it useful to have a common way of
94 representing these search filters in a human-readable form; LDAP URLs
95 are an example of one such application. This document defines a
96 human-readable string format for representing the full range of
97 possible LDAP version 3 search filters, including extended match
100 This document is a integral part of the LDAP technical specification
101 [Roadmap] which obsoletes the previously defined LDAP technical
102 specification, RFC 3377, in its entirety.
108 Smith & Howes Intended Category: Standards Track [Page 2]
110 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
113 This document replaces RFC 2254. Changes to RFC 2254 are summarized
116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
118 document are to be interpreted as described in BCP 14 [RFC2119].
120 2. LDAP Search Filter Definition
122 An LDAP search filter is defined in Section 4.5.1 of [Protocol] as
126 and [0] SET SIZE (1..MAX) OF filter Filter,
127 or [1] SET SIZE (1..MAX) OF filter Filter,
129 equalityMatch [3] AttributeValueAssertion,
130 substrings [4] SubstringFilter,
131 greaterOrEqual [5] AttributeValueAssertion,
132 lessOrEqual [6] AttributeValueAssertion,
133 present [7] AttributeDescription,
134 approxMatch [8] AttributeValueAssertion,
135 extensibleMatch [9] MatchingRuleAssertion }
137 SubstringFilter ::= SEQUENCE {
138 type AttributeDescription,
139 -- initial and final can occur at most once
140 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
141 initial [0] AssertionValue,
142 any [1] AssertionValue,
143 final [2] AssertionValue } }
145 AttributeValueAssertion ::= SEQUENCE {
146 attributeDesc AttributeDescription,
147 assertionValue AssertionValue }
149 MatchingRuleAssertion ::= SEQUENCE {
150 matchingRule [1] MatchingRuleId OPTIONAL,
151 type [2] AttributeDescription OPTIONAL,
152 matchValue [3] AssertionValue,
153 dnAttributes [4] BOOLEAN DEFAULT FALSE }
155 AttributeDescription ::= LDAPString
156 -- Constrained to <attributedescription>
159 AttributeValue ::= OCTET STRING
164 Smith & Howes Intended Category: Standards Track [Page 3]
166 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
169 MatchingRuleId ::= LDAPString
171 AssertionValue ::= OCTET STRING
173 LDAPString ::= OCTET STRING -- UTF-8 encoded,
174 -- [Unicode] characters
176 The AttributeDescription, as defined in [Protocol], is a string
177 representation of the attribute description that is discussed in
178 [Models]. The AttributeValue and AssertionValue OCTET STRING have
179 the form defined in [Syntaxes]. The Filter is encoded for
180 transmission over a network using the Basic Encoding Rules (BER)
181 defined in [X.690], with simplifications described in [Protocol].
183 3. String Search Filter Definition
185 The string representation of an LDAP search filter is a string of
186 UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined
187 by the following grammar, following the ABNF notation defined in
188 [RFC2234]. The productions used that are not defined here are
189 defined in section 1.4 (Common ABNF Productions) of [Models] unless
190 otherwise noted. The filter format uses a prefix notation.
192 filter = LPAREN filtercomp RPAREN
193 filtercomp = and / or / not / item
194 and = AMPERSAND filterlist
195 or = VERTBAR filterlist
196 not = EXCLAMATION filter
197 filterlist = 1*filter
198 item = simple / present / substring / extensible
199 simple = attr filtertype assertionvalue
200 filtertype = equal / approx / greaterorequal / lessorequal
202 approx = TILDE EQUALS
203 greaterorequal = RANGLE EQUALS
204 lessorequal = LANGLE EQUALS
205 extensible = ( attr [dnattrs]
206 [matchingrule] COLON EQUALS assertionvalue )
208 matchingrule COLON EQUALS assertionvalue )
209 present = attr EQUALS ASTERISK
210 substring = attr EQUALS [initial] any [final]
211 initial = assertionvalue
212 any = ASTERISK *(assertionvalue ASTERISK)
213 final = assertionvalue
214 attr = attributedescription
215 ; The attributedescription rule is defined in
216 ; Section 2.5 of [Models].
220 Smith & Howes Intended Category: Standards Track [Page 4]
222 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
226 matchingrule = COLON oid
227 assertionvalue = valueencoding
228 ; The <valueencoding> rule is used to encode an <AssertionValue>
229 ; from Section 4.1.6 of [Protocol].
230 valueencoding = 0*(normal / escaped)
231 normal = UTF1SUBSET / UTFMB
232 escaped = ESC HEX HEX
233 UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F
234 ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
235 ; RPAREN, ASTERISK, and ESC.
236 EXCLAMATION = %x21 ; exclamation mark ("!")
237 AMPERSAND = %x26 ; ampersand (or AND symbol) ("&")
238 ASTERISK = %x2A ; asterisk ("*")
239 COLON = %x3A ; colon (":")
240 VERTBAR = %x7C ; vertical bar (or pipe) ("|")
241 TILDE = %x7E ; tilde ("~")
244 Note that although both the <substring> and <present> productions in
245 the grammar above can produce the "attr=*" construct, this construct
246 is used only to denote a presence filter.
248 The <valueencoding> rule ensures that the entire filter string is a
249 valid UTF-8 string and provides that the octets that represent the
250 ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII
251 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a
252 backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits
253 representing the value of the encoded octet.
255 This simple escaping mechanism eliminates filter-parsing ambiguities
256 and allows any filter that can be represented in LDAP to be
257 represented as a NUL-terminated string. Other octets that are part of
258 the <normal> set may be escaped using this mechanism, for example,
259 non-printing ASCII characters.
261 For AssertionValues that contain UTF-8 character data, each octet of
262 the character to be escaped is replaced by a backslash and two hex
263 digits, which form a single octet in the code of the character. For
264 example, the filter checking whether the "cn" attribute contained a
265 value with the character "*" anywhere in it would be represented as
268 As indicated by the <valueencoding> rule, implementations MUST escape
269 all octets greater than 0x7F that are not part of a valid UTF-8
270 encoding sequence when they generate a string representation of a
271 search filter. Implementations SHOULD accept as input strings that
272 are not valid UTF-8 strings. This is necessary because RFC 2254 did
276 Smith & Howes Intended Category: Standards Track [Page 5]
278 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
281 not clearly define the term "string representation" (and in
282 particular did not mention that the string representation of an LDAP
283 search filter is a string of UTF-8 encoded Unicode characters).
287 This section gives a few examples of search filters written using
292 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
296 The following examples illustrate the use of extensible matching.
298 (cn:caseExactMatch:=Fred Flintstone)
300 (sn:dn:2.4.6.8.10:=Barney Rubble)
302 (:1.2.3:=Wilma Flintstone)
303 (:DN:2.4.6.8.10:=Dino)
305 The first example shows use of the matching rule "caseExactMatch."
307 The second example demonstrates use of a MatchingRuleAssertion form
308 without a matchingRule.
310 The third example illustrates the use of the ":oid" notation to
311 indicate that matching rule identified by the OID "2.4.6.8.10" should
312 be used when making comparisons, and that the attributes of an
313 entry's distinguished name should be considered part of the entry
314 when evaluating the match (indicated by the use of ":dn").
316 The fourth example denotes an equality match, except that DN
317 components should be considered part of the entry when doing the
320 The fifth example is a filter that should be applied to any attribute
321 supporting the matching rule given (since the <attr> has been
324 The sixth and final example is also a filter that should be applied
325 to any attribute supporting the matching rule given. Attributes
326 supporting the matching rule contained in the DN should also be
332 Smith & Howes Intended Category: Standards Track [Page 6]
334 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
337 The following examples illustrate the use of the escaping mechanism.
339 (o=Parens R Us \28for all your parenthetical needs\29)
341 (filename=C:\5cMyFile)
344 (1.3.6.1.4.1.1466.0=\04\02\48\69)
346 The first example shows the use of the escaping mechanism to
347 represent parenthesis characters. The second shows how to represent a
348 "*" in an assertion value, preventing it from being interpreted as a
349 substring indicator. The third illustrates the escaping of the
352 The fourth example shows a filter searching for the four octet value
353 00 00 00 04 (hex), illustrating the use of the escaping mechanism to
354 represent arbitrary data, including NUL characters.
356 The fifth example illustrates the use of the escaping mechanism to
357 represent various non-ASCII UTF-8 characters. Specifically, there are
358 5 characters in the <assertionvalue> portion of this example: LATIN
359 CAPITAL LETTER L (U+004C), LATIN SMALL LETTER U (U+0075), LATIN SMALL
360 LETTER C WITH CARON (U+010D), LATIN SMALL LETTER I (U+0069), and
361 LATIN SMALL LETTER C WITH ACUTE (U+0107).
363 The sixth and final example demonstrates assertion of a BER encoded
366 5. Security Considerations
368 This memo describes a string representation of LDAP search filters.
369 While the representation itself has no known security implications,
370 LDAP search filters do. They are interpreted by LDAP servers to
371 select entries from which data is retrieved. LDAP servers should
372 take care to protect the data they maintain from unauthorized access.
374 Please refer to the Security Considerations sections of [Protocol]
375 and [AuthMeth] for more information.
377 6. IANA Considerations
379 This document has no actions for IANA.
381 7. Normative References
383 [AuthMeth] Harrison, R. (editor), "LDAP: Authentication Methods and
384 Connection Level Security Mechanisms",
388 Smith & Howes Intended Category: Standards Track [Page 7]
390 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
393 draft-ietf-ldapbis-authmeth-xx.txt, a work in progress.
395 [Models] Zeilenga, K. (editor), "LDAP: Directory Information Models",
396 draft-ietf-ldapbis-models-xx.txt, a work in progress.
398 [Protocol] draft-ietf-ldapbis-protocol-xx.txt, a work in progress.
400 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
401 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
403 [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax
404 Specifications: ABNF", RFC 2234, November 1997.
406 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
407 RFC 3629, November 2003.
409 [Roadmap] Zeilenga, K. (editor), "LDAP: Technical Specification Road
410 Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in progress.
412 [Syntaxes] Dally, K. (editor), "LDAP: Syntaxes",
413 draft-ietf-ldapbis-syntaxes-xx.txt, a work in progress.
415 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
416 3.2.0" is defined by "The Unicode Standard, Version 3.0"
417 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as
418 amended by the "Unicode Standard Annex #27: Unicode 3.1"
419 (http://www.unicode.org/reports/tr27/) and by the "Unicode
420 Standard Annex #28: Unicode 3.2."
422 8. Informative References
424 [LDAPURL] Smith, M. (editor), "LDAP: Uniform Resource Locator",
425 draft-ietf-ldapbis-url-xx.txt, a work in progress.
427 [X.690] Specification of ASN.1 encoding rules: Basic, Canonical, and
428 Distinguished Encoding Rules, ITU-T Recommendation X.690,
433 This document replaces RFC 2254 by Tim Howes. RFC 2254 was a product
434 of the IETF ASID Working Group.
436 Changes included in this revised specification are based upon
437 discussions among the authors, discussions within the LDAP (v3)
438 Revision Working Group (ldapbis), and discussions within other IETF
439 Working Groups. The contributions of individuals in these working
440 groups is gratefully acknowledged.
444 Smith & Howes Intended Category: Standards Track [Page 8]
446 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
449 10. Authors' Addresses
457 mcs@pearlcrescent.com
468 11. Appendix A: Changes Since RFC 2254
470 11.1. Technical Changes
472 Replaced [ISO 10646] reference with [Unicode].
474 The following technical changes were made to the contents of the
475 "String Search Filter Definition" section:
477 Added statement that the string representation is a string of UTF-8
478 encoded Unicode characters.
480 Revised all of the ABNF to use common productions from [Models].
482 Replaced the "value" rule with a new "assertionvalue" rule within the
483 "simple", "extensible", and "substring" ("initial", "any", and
484 "final") rules. This matches a change made in [Syntaxes].
486 Added "(" and ")" around the components of the <extensible>
487 subproductions for clarity.
489 Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
490 precisely reference productions from the [Models] and [Protocol]
493 "String Search Filter Definition" section: replaced "greater" and
494 "less" with "greaterorequal" and "lessorequal" to avoid confusion.
500 Smith & Howes Intended Category: Standards Track [Page 9]
502 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
505 Introduced the "valueencoding" and associated "normal" and "escaped"
506 rules to reduce the dependence on descriptive text. The "normal"
507 production restricts filter strings to valid UTF-8 sequences.
509 Added a statement about expected behavior in light of RFC 2254's lack
510 of a clear definition of "string representation."
514 11.2. Editorial Changes
516 Changed document title to include "LDAP:" prefix.
518 IESG Note: removed note about lack of satisfactory mandatory
519 authentication mechanisms.
521 Header and "Authors' Addresses" sections: added Mark Smith as the
522 document editor and updated affiliation and contact information.
524 "Table of Contents", "IANA Considerations", and "Intellectual
525 Property Rights" sections: added.
527 Copyright: updated per latest IETF guidelines.
529 "Abstract" section: separated from introductory material.
531 "Introduction" section: new section; separated from the Abstract.
532 Updated second paragraph to indicate that RFC 2254 is replaced by
533 this document (instead of RFC 1960). Added reference to the [Roadmap]
536 "LDAP Search Filter Definition" section: made corrections to the LDAP
537 search filter ABNF so it matches that used in [Protocol].
539 Clarified the definition of 'value' (now 'assertionvalue') to take
540 into account the fact that it is not precisely an AttributeAssertion
541 from [Protocol] section 4.1.6 (special handling is required for some
542 characters). Added a note that each octet of a character to be
543 escaped is replaced by a backslash and two hex digits, which
544 represent a single octet.
546 "Examples" section: added four additional examples: (seeAlso=),
547 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and
548 (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a
549 value" with "an assertion value". Corrected the description of this
550 example: (sn:dn:2.4.6.8.10:=Barney Rubble). Replaced the numeric OID
551 in the first extensible match example with "caseExactMatch" to
552 demonstrate use of the descriptive form. Used "DN" (uppercase) in
556 Smith & Howes Intended Category: Standards Track [Page 10]
558 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
561 the last extensible match example to remind the reader to treat the
562 <dnattrs> production as case insensitive. Reworded the description
563 of the fourth escaping mechanism example to avoid making assumptions
564 about byte order. Added text to the fifth escaping mechanism example
565 to spell out what the non-ASCII characters are in Unicode terms.
567 "Security Considerations" section: added references to [Protocol] and
570 "Normative References" section: renamed from "References" per new RFC
571 guidelines. Changed from [1] style to [Protocol] style throughout the
572 document. Added entries for [Unicode], [RFC2119], [AuthMeth],
573 [Models], and [Roadmap] and updated the UTF-8 reference. Replaced
574 RFC 822 reference with a reference to RFC 2234.
576 "Informative References" section: (new section) moved [X.690] to this
577 section. Added a reference to [LDAPURL].
579 "Acknowledgments" section: added.
581 "Appendix A: Changes Since RFC 2254" section: added.
583 "Appendix B: Changes Since Previous Document Revision" section:
586 Surrounded the names of all ABNF productions with "<" and ">" where
587 they are used in descriptive text.
589 Replaced all occurrences of "LDAPv3" with "LDAP."
592 12. Appendix B: Changes Since Previous Document Revision
594 This appendix lists all changes relative to the previously published
595 revision, draft-ietf-ldapbis-filter-08.txt. Note that when
596 appropriate these changes are also included in Appendix A, but are
597 also included here for the benefit of the people who have already
598 reviewed draft-ietf-ldapbis-filter-08.txt. This section will be
599 removed before this document is published as an RFC.
602 12.1. Technical Changes
604 Removed the third option from the "extensible" production that
605 allowed creation of a MatchingRuleAssertion that only had a
606 matchValue (disallowed By [Protocol]). Added "(" and ")" around the
607 components of the <extensible> subproductions for clarity.
612 Smith & Howes Intended Category: Standards Track [Page 11]
614 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
617 12.2. Editorial Changes
619 "Introduction" section: referenced [Roadmap] upon first use of LDAP
620 and expanded the paragraph that begins "This document is an integral
621 part of the LDAP technical specification..." to match the text used
624 "LDAP Search Filter Definition" section: reworded the last paragraph
627 "Examples" section: Replaced the numeric OID in the first extensible
628 match example with "caseExactMatch" to demonstrate use of the
629 descriptive form. Used "DN" (uppercase) in the last extensible match
630 example to remind the reader to treat the <dnattrs> production as
631 case insensitive. Reworded the description of the fourth escaping
632 mechanism example to avoid making assumptions about byte order.
633 Added text to the fifth escaping mechanism example to spell out what
634 the non-ASCII characters are in Unicode terms.
636 References: added [LDAPURL] and moved [X.690] to "Informative
639 "Acknowledgements" section: added the sentence "RFC 2254 was a
640 product of the IETF ASID Working Group."
642 Changed these two sections to unnumbered ones: "Intellectual Property
643 Rights" and "Full Copyright."
645 Surrounded the names of all ABNF productions with "<" and ">" where
646 they are used in descriptive text.
648 Replaced all occurrences of "LDAPv3" with "LDAP."
651 Intellectual Property Rights
653 The IETF takes no position regarding the validity or scope of any
654 Intellectual Property Rights or other rights that might be claimed to
655 pertain to the implementation or use of the technology described in
656 this document or the extent to which any license under such rights
657 might or might not be available; nor does it represent that it has
658 made any independent effort to identify any such rights. Information
659 on the procedures with respect to rights in RFC documents can be
660 found in BCP 78 and BCP 79.
662 Copies of IPR disclosures made to the IETF Secretariat and any
663 assurances of licenses to be made available, or the result of an
664 attempt made to obtain a general license or permission for the use of
668 Smith & Howes Intended Category: Standards Track [Page 12]
670 INTERNET-DRAFT LDAP: String Repres. of Search Filters 16 November 2004
673 such proprietary rights by implementers or users of this
674 specification can be obtained from the IETF on-line IPR repository at
675 http://www.ietf.org/ipr.
677 The IETF invites any interested party to bring to its attention any
678 copyrights, patents or patent applications, or other proprietary
679 rights that may cover technology that may be required to implement
680 this standard. Please address the information to the IETF at
685 Copyright (C) The Internet Society (2004). This document is subject
686 to the rights, licenses and restrictions contained in BCP 78, and
687 except as set forth therein, the authors retain all their rights.
689 This document and the information contained herein are provided on an
690 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
691 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
692 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
693 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
694 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
695 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
698 This Internet Draft expires on 16 May 2005.
724 Smith & Howes Intended Category: Standards Track [Page 13]