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.
14 Lightweight Directory Access Protocol (LDAP):
15 String Representation of Search Filters
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.
27 Copyright (C) The Internet Society (2006).
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
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
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
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
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
91 and [0] SET SIZE (1..MAX) OF filter Filter,
92 or [1] SET SIZE (1..MAX) OF filter 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>
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
176 approx = TILDE EQUALS
177 greaterorequal = RANGLE EQUALS
178 lessorequal = LANGLE EQUALS
179 extensible = ( attr [dnattrs]
180 [matchingrule] COLON EQUALS assertionvalue )
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].
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
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).
255 This section gives a few examples of search filters written using
260 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
264 The following examples illustrate the use of extensible matching.
266 (cn:caseExactMatch:=Fred Flintstone)
268 (sn:dn:2.4.6.8.10:=Barney Rubble)
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
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
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
306 The following examples illustrate the use of the escaping mechanism.
308 (o=Parens R Us \28for all your parenthetical needs\29)
310 (filename=C:\5cMyFile)
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
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
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
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
376 [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol
377 (LDAP): Authentication Methods and Security Mechanisms",
380 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol
381 (LDAP): Syntaxes and Matching Rules", RFC 4517, June
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
405 [X.690] Specification of ASN.1 encoding rules: Basic, Canonical,
406 and Distinguished Encoding Rules, ITU-T Recommendation
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]
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
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
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."
577 Phone: +1 734 944-2856
578 EMail: mcs@pearlcrescent.com
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
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]