source: branches/samba-3.5.x/source4/ldap_server/devdocs/rfc4515.txt

Last change on this file was 414, checked in by Herwig Bauernfeind, 15 years ago

Samba 3.5.0: Initial import
File size: 23.3 KB
Line 
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
60
61RFC 4515 LDAP: String Representation of Search Filters June 2006
62
63
641. Introduction
65
66 The Lightweight Directory Access Protocol (LDAP) [RFC4510] defines a
67 network representation of a search filter transmitted to an LDAP
68 server. Some applications may find it useful to have a common way of
69 representing these search filters in a human-readable form; LDAP URLs
70 [RFC4516] are an example of one such application. This document
71 defines a human-readable string format for representing the full
72 range of possible LDAP version 3 search filters, including extended
73 match filters.
74
75 This document is a integral part of the LDAP technical specification
76 [RFC4510], which obsoletes the previously defined LDAP technical
77 specification, RFC 3377, in its entirety.
78
79 This document replaces RFC 2254. Changes to RFC 2254 are summarized
80 in Appendix A.
81
82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
84 document are to be interpreted as described in BCP 14 [RFC2119].
85
862. LDAP Search Filter Definition
87
88 An LDAP search filter is defined in Section 4.5.1 of [RFC4511] as
89 follows:
90
91 Filter ::= CHOICE {
92 and [0] SET SIZE (1..MAX) OF filter Filter,
93 or [1] SET SIZE (1..MAX) OF filter Filter,
94 not [2] Filter,
95 equalityMatch [3] AttributeValueAssertion,
96 substrings [4] SubstringFilter,
97 greaterOrEqual [5] AttributeValueAssertion,
98 lessOrEqual [6] AttributeValueAssertion,
99 present [7] AttributeDescription,
100 approxMatch [8] AttributeValueAssertion,
101 extensibleMatch [9] MatchingRuleAssertion }
102
103 SubstringFilter ::= SEQUENCE {
104 type AttributeDescription,
105 -- initial and final can occur at most once
106 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
107 initial [0] AssertionValue,
108 any [1] AssertionValue,
109 final [2] AssertionValue } }
110
111
112
113
114
115Smith and Howes Standards Track [Page 2]
116
117
118RFC 4515 LDAP: String Representation of Search Filters June 2006
119
120
121 AttributeValueAssertion ::= SEQUENCE {
122 attributeDesc AttributeDescription,
123 assertionValue AssertionValue }
124
125 MatchingRuleAssertion ::= SEQUENCE {
126 matchingRule [1] MatchingRuleId OPTIONAL,
127 type [2] AttributeDescription OPTIONAL,
128 matchValue [3] AssertionValue,
129 dnAttributes [4] BOOLEAN DEFAULT FALSE }
130
131 AttributeDescription ::= LDAPString
132 -- Constrained to <attributedescription>
133 -- [RFC4512]
134
135 AttributeValue ::= OCTET STRING
136
137 MatchingRuleId ::= LDAPString
138
139 AssertionValue ::= OCTET STRING
140
141 LDAPString ::= OCTET STRING -- UTF-8 encoded,
142 -- [Unicode] characters
143
144 The AttributeDescription, as defined in [RFC4511], is a string
145 representation of the attribute description that is discussed in
146 [RFC4512]. The AttributeValue and AssertionValue OCTET STRING have
147 the form defined in [RFC4517]. The Filter is encoded for
148 transmission over a network using the Basic Encoding Rules (BER)
149 defined in [X.690], with simplifications described in [RFC4511].
150
1513. String Search Filter Definition
152
153 The string representation of an LDAP search filter is a string of
154 UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined
155 by the following grammar, following the ABNF notation defined in
156 [RFC4234]. The productions used that are not defined here are
157 defined in Section 1.4 (Common ABNF Productions) of [RFC4512] unless
158 otherwise noted. The filter format uses a prefix notation.
159
160 filter = LPAREN filtercomp RPAREN
161 filtercomp = and / or / not / item
162 and = AMPERSAND filterlist
163 or = VERTBAR filterlist
164 not = EXCLAMATION filter
165 filterlist = 1*filter
166 item = simple / present / substring / extensible
167 simple = attr filtertype assertionvalue
168 filtertype = equal / approx / greaterorequal / lessorequal
169
170
171
172Smith and Howes Standards Track [Page 3]
173
174
175RFC 4515 LDAP: String Representation of Search Filters June 2006
176
177
178 equal = EQUALS
179 approx = TILDE EQUALS
180 greaterorequal = RANGLE EQUALS
181 lessorequal = LANGLE EQUALS
182 extensible = ( attr [dnattrs]
183 [matchingrule] COLON EQUALS assertionvalue )
184 / ( [dnattrs]
185 matchingrule COLON EQUALS assertionvalue )
186 present = attr EQUALS ASTERISK
187 substring = attr EQUALS [initial] any [final]
188 initial = assertionvalue
189 any = ASTERISK *(assertionvalue ASTERISK)
190 final = assertionvalue
191 attr = attributedescription
192 ; The attributedescription rule is defined in
193 ; Section 2.5 of [RFC4512].
194 dnattrs = COLON "dn"
195 matchingrule = COLON oid
196 assertionvalue = valueencoding
197 ; The <valueencoding> rule is used to encode an <AssertionValue>
198 ; from Section 4.1.6 of [RFC4511].
199 valueencoding = 0*(normal / escaped)
200 normal = UTF1SUBSET / UTFMB
201 escaped = ESC HEX HEX
202 UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F
203 ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
204 ; RPAREN, ASTERISK, and ESC.
205 EXCLAMATION = %x21 ; exclamation mark ("!")
206 AMPERSAND = %x26 ; ampersand (or AND symbol) ("&")
207 ASTERISK = %x2A ; asterisk ("*")
208 COLON = %x3A ; colon (":")
209 VERTBAR = %x7C ; vertical bar (or pipe) ("|")
210 TILDE = %x7E ; tilde ("~")
211
212 Note that although both the <substring> and <present> productions in
213 the grammar above can produce the "attr=*" construct, this construct
214 is used only to denote a presence filter.
215
216 The <valueencoding> rule ensures that the entire filter string is a
217 valid UTF-8 string and provides that the octets that represent the
218 ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII
219 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a
220 backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits
221 representing the value of the encoded octet.
222
223
224
225
226
227
228
229Smith and Howes Standards Track [Page 4]
230
231
232RFC 4515 LDAP: String Representation of Search Filters June 2006
233
234
235 This simple escaping mechanism eliminates filter-parsing ambiguities
236 and allows any filter that can be represented in LDAP to be
237 represented as a NUL-terminated string. Other octets that are part
238 of the <normal> set may be escaped using this mechanism, for example,
239 non-printing ASCII characters.
240
241 For AssertionValues that contain UTF-8 character data, each octet of
242 the character to be escaped is replaced by a backslash and two hex
243 digits, which form a single octet in the code of the character. For
244 example, the filter checking whether the "cn" attribute contained a
245 value with the character "*" anywhere in it would be represented as
246 "(cn=*\2a*)".
247
248 As indicated by the <valueencoding> rule, implementations MUST escape
249 all octets greater than 0x7F that are not part of a valid UTF-8
250 encoding sequence when they generate a string representation of a
251 search filter. Implementations SHOULD accept as input strings that
252 are not valid UTF-8 strings. This is necessary because RFC 2254 did
253 not clearly define the term "string representation" (and in
254 particular did not mention that the string representation of an LDAP
255 search filter is a string of UTF-8-encoded Unicode characters).
256
2574. Examples
258
259 This section gives a few examples of search filters written using
260 this notation.
261
262 (cn=Babs Jensen)
263 (!(cn=Tim Howes))
264 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
265 (o=univ*of*mich*)
266 (seeAlso=)
267
268 The following examples illustrate the use of extensible matching.
269
270 (cn:caseExactMatch:=Fred Flintstone)
271 (cn:=Betty Rubble)
272 (sn:dn:2.4.6.8.10:=Barney Rubble)
273 (o:dn:=Ace Industry)
274 (:1.2.3:=Wilma Flintstone)
275 (:DN:2.4.6.8.10:=Dino)
276
277 The first example shows use of the matching rule "caseExactMatch."
278
279 The second example demonstrates use of a MatchingRuleAssertion form
280 without a matchingRule.
281
282
283
284
285
286Smith and Howes Standards Track [Page 5]
287
288
289RFC 4515 LDAP: String Representation of Search Filters June 2006
290
291
292 The third example illustrates the use of the ":oid" notation to
293 indicate that the matching rule identified by the OID "2.4.6.8.10"
294 should be used when making comparisons, and that the attributes of an
295 entry's distinguished name should be considered part of the entry
296 when evaluating the match (indicated by the use of ":dn").
297
298 The fourth example denotes an equality match, except that DN
299 components should be considered part of the entry when doing the
300 match.
301
302 The fifth example is a filter that should be applied to any attribute
303 supporting the matching rule given (since the <attr> has been
304 omitted).
305
306 The sixth and final example is also a filter that should be applied
307 to any attribute supporting the matching rule given. Attributes
308 supporting the matching rule contained in the DN should also be
309 considered.
310
311 The following examples illustrate the use of the escaping mechanism.
312
313 (o=Parens R Us \28for all your parenthetical needs\29)
314 (cn=*\2A*)
315 (filename=C:\5cMyFile)
316 (bin=\00\00\00\04)
317 (sn=Lu\c4\8di\c4\87)
318 (1.3.6.1.4.1.1466.0=\04\02\48\69)
319
320 The first example shows the use of the escaping mechanism to
321 represent parenthesis characters. The second shows how to represent
322 a "*" in an assertion value, preventing it from being interpreted as
323 a substring indicator. The third illustrates the escaping of the
324 backslash character.
325
326 The fourth example shows a filter searching for the four-octet value
327 00 00 00 04 (hex), illustrating the use of the escaping mechanism to
328 represent arbitrary data, including NUL characters.
329
330 The fifth example illustrates the use of the escaping mechanism to
331 represent various non-ASCII UTF-8 characters. Specifically, there
332 are 5 characters in the <assertionvalue> portion of this example:
333 LATIN CAPITAL LETTER L (U+004C), LATIN SMALL LETTER U (U+0075), LATIN
334 SMALL LETTER C WITH CARON (U+010D), LATIN SMALL LETTER I (U+0069),
335 and LATIN SMALL LETTER C WITH ACUTE (U+0107).
336
337 The sixth and final example demonstrates assertion of a BER-encoded
338 value.
339
340
341
342
343Smith and Howes Standards Track [Page 6]
344
345
346RFC 4515 LDAP: String Representation of Search Filters June 2006
347
348
3495. Security Considerations
350
351 This memo describes a string representation of LDAP search filters.
352 While the representation itself has no known security implications,
353 LDAP search filters do. They are interpreted by LDAP servers to
354 select entries from which data is retrieved. LDAP servers should
355 take care to protect the data they maintain from unauthorized access.
356
357 Please refer to the Security Considerations sections of [RFC4511] and
358 [RFC4513] for more information.
359
3606. Normative References
361
362 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
363 Requirement Levels", BCP 14, RFC 2119, March 1997.
364
365 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
366 10646", STD 63, RFC 3629, November 2003.
367
368 [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
369 Specifications: ABNF", RFC 4234, October 2005.
370
371 [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
372 (LDAP): Technical Specification Road Map", RFC 4510, June
373 2006.
374
375 [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access
376 Protocol (LDAP): The Protocol", RFC 4511, June 2006.
377
378 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol
379 (LDAP): Directory Information Models", RFC 4512, June
380 2006.
381
382 [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol
383 (LDAP): Authentication Methods and Security Mechanisms",
384 RFC 4513, June 2006.
385
386 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol
387 (LDAP): Syntaxes and Matching Rules", RFC 4517, June
388 2006.
389
390 [Unicode] The Unicode Consortium, "The Unicode Standard, Version
391 3.2.0" is defined by "The Unicode Standard, Version 3.0"
392 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
393 as amended by the "Unicode Standard Annex #27: Unicode
394 3.1" (http://www.unicode.org/reports/tr27/) and by the
395 "Unicode Standard Annex #28: Unicode 3.2."
396
397
398
399
400Smith and Howes Standards Track [Page 7]
401
402
403RFC 4515 LDAP: String Representation of Search Filters June 2006
404
405
4067. Informative References
407
408 [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory
409 Access Protocol (LDAP): Uniform Resource Locator", RFC
410 4516, June 2006.
411
412 [X.690] Specification of ASN.1 encoding rules: Basic, Canonical,
413 and Distinguished Encoding Rules, ITU-T Recommendation
414 X.690, 1994.
415
4168. Acknowledgements
417
418 This document replaces RFC 2254 by Tim Howes. RFC 2254 was a product
419 of the IETF ASID Working Group.
420
421 Changes included in this revised specification are based upon
422 discussions among the authors, discussions within the LDAP (v3)
423 Revision Working Group (ldapbis), and discussions within other IETF
424 Working Groups. The contributions of individuals in these working
425 groups is gratefully acknowledged.
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457Smith and Howes Standards Track [Page 8]
458
459
460RFC 4515 LDAP: String Representation of Search Filters June 2006
461
462
463Appendix A: Changes Since RFC 2254
464
465A.1. Technical Changes
466
467 Replaced [ISO 10646] reference with [Unicode].
468
469 The following technical changes were made to the contents of the
470 "String Search Filter Definition" section:
471
472 Added statement that the string representation is a string of UTF-8-
473 encoded Unicode characters.
474
475 Revised all of the ABNF to use common productions from [RFC4512].
476
477 Replaced the "value" rule with a new "assertionvalue" rule within the
478 "simple", "extensible", and "substring" ("initial", "any", and
479 "final") rules. This matches a change made in [RFC4517].
480
481 Added "(" and ")" around the components of the <extensible>
482 subproductions for clarity.
483
484 Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
485 precisely reference productions from the [RFC4512] and [RFC4511]
486 documents.
487
488 "String Search Filter Definition" section: replaced "greater" and
489 "less" with "greaterorequal" and "lessorequal" to avoid confusion.
490
491 Introduced the "valueencoding" and associated "normal" and "escaped"
492 rules to reduce the dependence on descriptive text. The "normal"
493 production restricts filter strings to valid UTF-8 sequences.
494
495 Added a statement about expected behavior in light of RFC 2254's lack
496 of a clear definition of "string representation."
497
498A.2. Editorial Changes
499
500 Changed document title to include "LDAP:" prefix.
501
502 IESG Note: removed note about lack of satisfactory mandatory
503 authentication mechanisms.
504
505 Header and "Authors' Addresses" sections: added Mark Smith as the
506 document editor and updated affiliation and contact information.
507
508 "Table of Contents" and "Intellectual Property" sections: added.
509
510 Copyright: updated per latest IETF guidelines.
511
512
513
514Smith and Howes Standards Track [Page 9]
515
516
517RFC 4515 LDAP: String Representation of Search Filters June 2006
518
519
520 "Abstract" section: separated from introductory material.
521
522 "Introduction" section: new section; separated from the Abstract.
523 Updated second paragraph to indicate that RFC 2254 is replaced by
524 this document (instead of RFC 1960). Added reference to the
525 [RFC4510] document.
526
527 "LDAP Search Filter Definition" section: made corrections to the LDAP
528 search filter ABNF so it matches that used in [RFC4511].
529
530 Clarified the definition of 'value' (now 'assertionvalue') to take
531 into account the fact that it is not precisely an AttributeAssertion
532 from [RFC4511] Section 4.1.6 (special handling is required for some
533 characters). Added a note that each octet of a character to be
534 escaped is replaced by a backslash and two hex digits, which
535 represent a single octet.
536
537 "Examples" section: added four additional examples: (seeAlso=),
538 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and
539 (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a
540 value" with "an assertion value". Corrected the description of this
541 example: (sn:dn:2.4.6.8.10:=Barney Rubble). Replaced the numeric OID
542 in the first extensible match example with "caseExactMatch" to
543 demonstrate use of the descriptive form. Used "DN" (uppercase) in
544 the last extensible match example to remind the reader to treat the
545 <dnattrs> production as case insensitive. Reworded the description
546 of the fourth escaping mechanism example to avoid making assumptions
547 about byte order. Added text to the fifth escaping mechanism example
548 to spell out what the non-ASCII characters are in Unicode terms.
549
550 "Security Considerations" section: added references to [RFC4511] and
551 [RFC4513].
552
553 "Normative References" section: renamed from "References" per new RFC
554 guidelines. Changed from [1] style to [RFC4511] style throughout the
555 document. Added entries for [Unicode], [RFC2119], [RFC4513],
556 [RFC4512], and [RFC4510] and updated the UTF-8 reference. Replaced
557 RFC 822 reference with a reference to RFC 4234.
558
559 "Informative References" section: (new section) moved [X.690] to this
560 section. Added a reference to [RFC4516].
561
562 "Acknowledgements" section: added.
563
564 "Appendix A: Changes Since RFC 2254" section: added.
565
566 Surrounded the names of all ABNF productions with "<" and ">" where
567 they are used in descriptive text.
568
569
570
571Smith and Howes Standards Track [Page 10]
572
573
574RFC 4515 LDAP: String Representation of Search Filters June 2006
575
576
577 Replaced all occurrences of "LDAPv3" with "LDAP."
578
579Authors' Addresses
580
581 Mark Smith, Editor
582 Pearl Crescent, LLC
583 447 Marlpool Dr.
584 Saline, MI 48176
585 USA
586
587 Phone: +1 734 944-2856
588 EMail: mcs@pearlcrescent.com
589
590
591 Tim Howes
592 Opsware, Inc.
593 599 N. Mathilda Ave.
594 Sunnyvale, CA 94085
595 USA
596
597 Phone: +1 408 744-7509
598 EMail: howes@opsware.com
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628Smith and Howes Standards Track [Page 11]
629
630
631RFC 4515 LDAP: String Representation of Search Filters June 2006
632
633
634Full Copyright Statement
635
636 Copyright (C) The Internet Society (2006).
637
638 This document is subject to the rights, licenses and restrictions
639 contained in BCP 78, and except as set forth therein, the authors
640 retain all their rights.
641
642 This document and the information contained herein are provided on an
643 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
644 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
645 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
646 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
647 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
648 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
649
650Intellectual Property
651
652 The IETF takes no position regarding the validity or scope of any
653 Intellectual Property Rights or other rights that might be claimed to
654 pertain to the implementation or use of the technology described in
655 this document or the extent to which any license under such rights
656 might or might not be available; nor does it represent that it has
657 made any independent effort to identify any such rights. Information
658 on the procedures with respect to rights in RFC documents can be
659 found in BCP 78 and BCP 79.
660
661 Copies of IPR disclosures made to the IETF Secretariat and any
662 assurances of licenses to be made available, or the result of an
663 attempt made to obtain a general license or permission for the use of
664 such proprietary rights by implementers or users of this
665 specification can be obtained from the IETF on-line IPR repository at
666 http://www.ietf.org/ipr.
667
668 The IETF invites any interested party to bring to its attention any
669 copyrights, patents or patent applications, or other proprietary
670 rights that may cover technology that may be required to implement
671 this standard. Please address the information to the IETF at
672 ietf-ipr@ietf.org.
673
674Acknowledgement
675
676 Funding for the RFC Editor function is provided by the IETF
677 Administrative Support Activity (IASA).
678
679
680
681
682
683
684
685Smith and Howes Standards Track [Page 12]
686
687
Note: See TracBrowser for help on using the repository browser.