3 Network Working Group M. Smith, Editor
4 Request for Comments: DRAFT Pearl Crescent, LLC
5 Obsoletes: RFC 2254 T. Howes
6 Expires: 24 April 2005 Opsware, Inc.
10 LDAP: String Representation of Search Filters
11 <draft-ietf-ldapbis-filter-08.txt>
17 By submitting this Internet-Draft, each author represents that any
18 applicable patent or other IPR claims of which he or she is aware
19 have been or will be disclosed, and any of which he or she become
20 aware will be disclosed, in accordance with RFC 3668.
22 This document is intended to be published as a Standards Track RFC,
23 replacing RFC 2254. Distribution of this memo is unlimited.
24 Technical discussion of this document will take place on the IETF
25 LDAP (v3) Revision (ldapbis) Working Group mailing list
26 <ietf-ldapbis@openldap.org>. Please send editorial comments directly
27 to the editor <mcs@pearlcrescent.com>.
29 Internet-Drafts are working documents of the Internet Engineering
30 Task Force (IETF), its areas, and its working groups. Note that
31 other groups may also distribute working documents as
34 Internet-Drafts are draft documents valid for a maximum of six months
35 and may be updated, replaced, or obsoleted by other documents at any
36 time. It is inappropriate to use Internet-Drafts as reference
37 material or to cite them other than a "work in progress."
39 The list of current Internet-Drafts can be accessed at
40 http://www.ietf.org/1id-abstracts.html
42 The list of Internet-Draft Shadow Directories can be accessed at
43 http://www.ietf.org/shadow.html
45 Copyright (C) The Internet Society (2004). All Rights Reserved.
46 Please see the Full Copyright section near the end of this document
54 Smith & Howes Intended Category: Standards Track [Page 1]
56 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
61 LDAP search filters are transmitted in the LDAP protocol using a
62 binary representation that is appropriate for use on the network.
63 This document defines a human-readable string representation of LDAP
64 search filters that is appropriate for use in LDAP URLs and in other
69 Status of this Memo............................................1
70 Abstract.......................................................2
71 Table of Contents..............................................2
72 1. Introduction...................................................2
73 2. LDAP Search Filter Definition..................................3
74 3. String Search Filter Definition................................4
75 4. Examples.......................................................6
76 5. Security Considerations........................................7
77 6. IANA Considerations............................................7
78 7. Normative References...........................................7
79 8. Informative References.........................................8
80 9. Acknowledgments................................................8
81 10. Authors' Addresses.............................................8
82 11. Appendix A: Changes Since RFC 2254.............................9
83 11.1. Technical Changes...........................................9
84 11.2. Editorial Changes...........................................10
85 12. Appendix B: Changes Since Previous Document Revision...........11
86 12.1. Editorial Changes...........................................11
87 13. Intellectual Property Rights...................................11
88 14. Full Copyright.................................................12
92 The Lightweight Directory Access Protocol (LDAP) [Protocol] defines a
93 network representation of a search filter transmitted to an LDAP
94 server. Some applications may find it useful to have a common way of
95 representing these search filters in a human-readable form; LDAP URLs
96 are an example of one such application. This document defines a
97 human-readable string format for representing the full range of
98 possible LDAP version 3 search filters, including extended match
101 This document is an integral part of the LDAP Technical Specification
104 This document replaces RFC 2254. Changes to RFC 2254 are summarized
110 Smith & Howes Intended Category: Standards Track [Page 2]
112 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
117 document are to be interpreted as described in BCP 14 [RFC2119].
119 2. LDAP Search Filter Definition
121 An LDAPv3 search filter is defined in Section 4.5.1 of [Protocol] as
125 and [0] SET SIZE (1..MAX) OF filter Filter,
126 or [1] SET SIZE (1..MAX) OF filter Filter,
128 equalityMatch [3] AttributeValueAssertion,
129 substrings [4] SubstringFilter,
130 greaterOrEqual [5] AttributeValueAssertion,
131 lessOrEqual [6] AttributeValueAssertion,
132 present [7] AttributeDescription,
133 approxMatch [8] AttributeValueAssertion,
134 extensibleMatch [9] MatchingRuleAssertion }
136 SubstringFilter ::= SEQUENCE {
137 type AttributeDescription,
138 -- initial and final can occur at most once
139 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
140 initial [0] AssertionValue,
141 any [1] AssertionValue,
142 final [2] AssertionValue } }
144 AttributeValueAssertion ::= SEQUENCE {
145 attributeDesc AttributeDescription,
146 assertionValue AssertionValue }
148 MatchingRuleAssertion ::= SEQUENCE {
149 matchingRule [1] MatchingRuleId OPTIONAL,
150 type [2] AttributeDescription OPTIONAL,
151 matchValue [3] AssertionValue,
152 dnAttributes [4] BOOLEAN DEFAULT FALSE }
154 AttributeDescription ::= LDAPString
155 -- Constrained to <attributedescription>
158 AttributeValue ::= OCTET STRING
160 MatchingRuleId ::= LDAPString
162 AssertionValue ::= OCTET STRING
166 Smith & Howes Intended Category: Standards Track [Page 3]
168 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
171 LDAPString ::= OCTET STRING -- UTF-8 encoded,
172 -- [Unicode] characters
174 The AttributeDescription is a string representation of the attribute
175 description and is defined in [Protocol]. The AttributeValue and
176 AssertionValue OCTET STRING have the form defined in [Syntaxes]. The
177 Filter is encoded for transmission over a network using the Basic
178 Encoding Rules (BER) defined in [X.690], with simplifications
179 described in [Protocol].
181 3. String Search Filter Definition
183 The string representation of an LDAP search filter is a string of
184 UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined
185 by the following grammar, following the ABNF notation defined in
186 [RFC2234]. The productions used that are not defined here are
187 defined in section 1.4 (Common ABNF Productions) of [Models] unless
188 otherwise noted. The filter format uses a prefix notation.
190 filter = LPAREN filtercomp RPAREN
191 filtercomp = and / or / not / item
192 and = AMPERSAND filterlist
193 or = VERTBAR filterlist
194 not = EXCLAMATION filter
195 filterlist = 1*filter
196 item = simple / present / substring / extensible
197 simple = attr filtertype assertionvalue
198 filtertype = equal / approx / greaterorequal / lessorequal
200 approx = TILDE EQUALS
201 greaterorequal = RANGLE EQUALS
202 lessorequal = LANGLE EQUALS
203 extensible = attr [dnattrs]
204 [matchingrule] COLON EQUALS assertionvalue
206 matchingrule COLON EQUALS assertionvalue
207 / COLON EQUALS assertionvalue
208 present = attr EQUALS ASTERISK
209 substring = attr EQUALS [initial] any [final]
210 initial = assertionvalue
211 any = ASTERISK *(assertionvalue ASTERISK)
212 final = assertionvalue
213 attr = attributedescription
214 ; The attributedescription rule is defined in
215 ; Section 2.5 of [Models].
217 matchingrule = COLON oid
218 assertionvalue = valueencoding
222 Smith & Howes Intended Category: Standards Track [Page 4]
224 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
227 ; The <valueencoding> rule is used to encode an <AssertionValue>
228 ; from Section 4.1.6 of [Protocol].
229 valueencoding = 0*(normal / escaped)
230 normal = UTF1SUBSET / UTFMB
231 escaped = ESC HEX HEX
232 UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F
233 ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
234 ; RPAREN, ASTERISK, and ESC.
235 EXCLAMATION = %x21 ; exclamation mark ("!")
236 AMPERSAND = %x26 ; ampersand (or AND symbol) ("&")
237 ASTERISK = %x2A ; asterisk ("*")
238 COLON = %x3A ; colon (":")
239 VERTBAR = %x7C ; vertical bar (or pipe) ("|")
240 TILDE = %x7E ; tilde ("~")
243 Note that although both the <substring> and <present> productions in
244 the grammar above can produce the "attr=*" construct, this construct
245 is used only to denote a presence filter.
247 The <valueencoding> rule ensures that the entire filter string is a
248 valid UTF-8 string and provides that the octets that represent the
249 ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII
250 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a
251 backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits
252 representing the value of the encoded octet.
254 This simple escaping mechanism eliminates filter-parsing ambiguities
255 and allows any filter that can be represented in LDAP to be
256 represented as a NUL-terminated string. Other octets that are part of
257 the <normal> set may be escaped using this mechanism, for example,
258 non-printing ASCII characters.
260 For AssertionValues that contain UTF-8 character data, each octet of
261 the character to be escaped is replaced by a backslash and two hex
262 digits, which form a single octet in the code of the character.
264 For example, the filter checking whether the "cn" attribute contained
265 a 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
273 not clearly define the term "string representation" (and in
274 particular did not mention that the string representation of an LDAP
278 Smith & Howes Intended Category: Standards Track [Page 5]
280 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
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:1.2.3.4.5:=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 "1.2.3.4.5".
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 "2.4.6.8.10" should be used when making
312 comparisons, and that the attributes of an entry's distinguished name
313 should be considered part of the entry when evaluating the match
314 (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 omitted).
323 The sixth and final example is also a filter that should be applied
324 to any attribute supporting the matching rule given. Attributes
325 supporting the matching rule contained in the DN should also be
328 The following examples illustrate the use of the escaping mechanism.
330 (o=Parens R Us \28for all your parenthetical needs\29)
334 Smith & Howes Intended Category: Standards Track [Page 6]
336 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
340 (filename=C:\5cMyFile)
343 (1.3.6.1.4.1.1466.0=\04\02\48\69)
345 The first example shows the use of the escaping mechanism to
346 represent parenthesis characters. The second shows how to represent a
347 "*" in an assertion value, preventing it from being interpreted as a
348 substring indicator. The third illustrates the escaping of the
351 The fourth example shows a filter searching for the four-byte value
352 0x00000004, illustrating the use of the escaping mechanism to
353 represent arbitrary data, including NUL characters.
355 The fifth example illustrates the use of the escaping mechanism to
356 represent various non-ASCII UTF-8 characters.
358 The sixth and final example demonstrates assertion of a BER encoded
361 5. Security Considerations
363 This memo describes a string representation of LDAP search filters.
364 While the representation itself has no known security implications,
365 LDAP search filters do. They are interpreted by LDAP servers to
366 select entries from which data is retrieved. LDAP servers should
367 take care to protect the data they maintain from unauthorized access.
369 Please refer to the Security Considerations sections of [Protocol]
370 and [AuthMeth] for more information.
372 6. IANA Considerations
374 This document has no actions for IANA.
376 7. Normative References
378 [AuthMeth] Harrison, R. (editor), "LDAP: Authentication Methods and
379 Connection Level Security Mechanisms",
380 draft-ietf-ldapbis-authmeth-xx.txt, a work in progress.
382 [Models] Zeilenga, K. (editor), "LDAP: Directory Information Models",
383 draft-ietf-ldapbis-models-xx.txt, a work in progress.
385 [Protocol] draft-ietf-ldapbis-protocol-xx.txt, a work in progress.
390 Smith & Howes Intended Category: Standards Track [Page 7]
392 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
395 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
396 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
398 [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax
399 Specifications: ABNF", RFC 2234, November 1997.
401 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
402 RFC 3629, November 2003.
404 [Roadmap] Zeilenga, K. (editor), "LDAP: Technical Specification Road
405 Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in progress.
407 [Syntaxes] Dally, K. (editor), "LDAP: Syntaxes",
408 draft-ietf-ldapbis-syntaxes-xx.txt, a work in progress.
410 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
411 3.2.0" is defined by "The Unicode Standard, Version 3.0"
412 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as
413 amended by the "Unicode Standard Annex #27: Unicode 3.1"
414 (http://www.unicode.org/reports/tr27/) and by the "Unicode
415 Standard Annex #28: Unicode 3.2."
417 [X.690] Specification of ASN.1 encoding rules: Basic, Canonical, and
418 Distinguished Encoding Rules, ITU-T Recommendation X.690,
421 8. Informative References
427 This document replaces RFC 2254 by Tim Howes. Changes included in
428 this revised specification are based upon discussions among the
429 authors, discussions within the LDAP (v3) Revision Working Group
430 (ldapbis), and discussions within other IETF Working Groups. The
431 contributions of individuals in these working groups is gratefully
435 10. Authors' Addresses
446 Smith & Howes Intended Category: Standards Track [Page 8]
448 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
451 mcs@pearlcrescent.com
462 11. Appendix A: Changes Since RFC 2254
464 11.1. Technical Changes
466 Replaced [ISO 10646] reference with [Unicode].
468 The following technical changes were made to the contents of the
469 "String Search Filter Definition" section:
471 Added statement that the string representation is a string of UTF-8
472 encoded Unicode characters.
474 Revised all of the ABNF to use common productions from [Models].
476 Replaced the "value" rule with a new "assertionvalue" rule within the
477 "simple", "extensible", and "substring" ("initial", "any", and
478 "final") rules. This matches a change made in [Syntaxes].
480 Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
481 precisely reference productions from the [Models] and [Protocol]
484 "String Search Filter Definition" section: replaced "greater" and
485 "less" with "greaterorequal" and "lessorequal" to avoid confusion.
487 Introduced the "valueencoding" and associated "normal" and "escaped"
488 rules to reduce the dependence on descriptive text. The "normal"
489 production restricts filter strings to valid UTF-8 sequences.
491 Added a third option to the "extensible" production to allow creation
492 of a MatchingRuleAssertion that only has a matchValue.
494 Added a statement about expected behavior in light of RFC 2254's lack
495 of a clear definition of "string representation."
502 Smith & Howes Intended Category: Standards Track [Page 9]
504 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
507 11.2. Editorial Changes
509 Changed document title to include "LDAP:" prefix.
511 IESG Note: removed note about lack of satisfactory mandatory
512 authentication mechanisms.
514 Header and "Authors' Addresses" sections: added Mark Smith as the
515 document editor and updated affiliation and contact information.
517 "Table of Contents", "IANA Considerations", and "Intellectual
518 Property Rights" sections: added.
520 Copyright: updated per latest IETF guidelines.
522 "Abstract" section: separated from introductory material.
524 "Introduction" section: new section; separated from the Abstract.
525 Updated second paragraph to indicate that RFC 2254 is replaced by
526 this document (instead of RFC 1960). Added reference to the [Roadmap]
529 "LDAP Search Filter Definition" section: made corrections to the
530 LDAPv3 search filter ABNF so it matches that used in [Protocol].
532 Clarified the definition of 'value' (now 'assertionvalue') to take
533 into account the fact that it is not precisely an AttributeAssertion
534 from [Protocol] section 4.1.6 (special handling is required for some
535 characters). Added a note that each octet of a character to be
536 escaped is replaced by a backslash and two hex digits, which
537 represent a single octet.
539 "Examples" section: added four additional examples: (seeAlso=),
540 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and
541 (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a
542 value" with "an assertion value". Corrected the description of this
543 example: (sn:dn:2.4.6.8.10:=Barney Rubble).
545 "Security Considerations" section: added references to [Protocol] and
548 "Normative References" section: renamed from "References" per new RFC
549 guidelines. Changed from [1] style to [Protocol] style throughout the
550 document. Added entries for [Unicode], [RFC2119], [AuthMeth],
551 [Models], and [Roadmap] and updated the UTF-8 reference. Replaced
552 RFC 822 reference with a reference to RFC 2234.
558 Smith & Howes Intended Category: Standards Track [Page 10]
560 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
563 "Informative References" section: added for clarity.
565 "Acknowledgments" section: added.
567 "Appendix A: Changes Since RFC 2254" section: added.
569 "Appendix B: Changes Since Previous Document Revision" section:
573 12. Appendix B: Changes Since Previous Document Revision
575 This appendix lists all changes relative to the previously published
576 revision, draft-ietf-ldapbis-filter-07.txt. Note that when
577 appropriate these changes are also included in Appendix A, but are
578 also included here for the benefit of the people who have already
579 reviewed draft-ietf-ldapbis-filter-07.txt. This section will be
580 removed before this document is published as an RFC.
583 12.1. Editorial Changes
585 "Status of this Memo" section: replaced RFC 3668 (IPR) boilerplate
586 paragraph with the version that says "each author" instead of "I."
588 "Status of this Memo" section: added 2 paragraphs that were
589 accidently removed from the -07 revision (one begins with "The list
590 of current Internet-Drafts..." and the other begins with "The list of
591 Internet-Draft Shadow Directories...."
594 13. Intellectual Property Rights
596 The IETF takes no position regarding the validity or scope of any
597 Intellectual Property Rights or other rights that might be claimed to
598 pertain to the implementation or use of the technology described in
599 this document or the extent to which any license under such rights
600 might or might not be available; nor does it represent that it has
601 made any independent effort to identify any such rights. Information
602 on the procedures with respect to rights in RFC documents can be
603 found in BCP 78 and BCP 79.
605 Copies of IPR disclosures made to the IETF Secretariat and any
606 assurances of licenses to be made available, or the result of an
607 attempt made to obtain a general license or permission for the use of
608 such proprietary rights by implementers or users of this
609 specification can be obtained from the IETF on-line IPR repository at
610 http://www.ietf.org/ipr.
614 Smith & Howes Intended Category: Standards Track [Page 11]
616 INTERNET-DRAFT LDAP: String Repres. of Search Filters 24 October 2004
619 The IETF invites any interested party to bring to its attention any
620 copyrights, patents or patent applications, or other proprietary
621 rights that may cover technology that may be required to implement
622 this standard. Please address the information to the IETF at
627 Copyright (C) The Internet Society (2004). This document is subject
628 to the rights, licenses and restrictions contained in BCP 78, and
629 except as set forth therein, the authors 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.
640 This Internet Draft expires on 24 April 2005.
670 Smith & Howes Intended Category: Standards Track [Page 12]