]> git.sur5r.net Git - openldap/blob - doc/drafts/draft-ietf-ldapbis-filter-xx.txt
import drafts
[openldap] / doc / drafts / draft-ietf-ldapbis-filter-xx.txt
1
2
3
4
5
6
7 Network Working Group                                 M. Smith, Editor
8 Request for Comments: DRAFT              Netscape Communications Corp.
9 Obsoletes: RFC 2254                                           T. Howes
10 Expires: 28 August 2003                                  Opsware, Inc.
11                                                       28 February 2003
12
13
14              LDAP: String Representation of Search Filters
15                    <draft-ietf-ldapbis-filter-04.txt>
16
17
18
19 1.  Status of this Memo
20
21    This document is an Internet-Draft and is subject to all provisions
22    of Section 10 of RFC2026.
23
24    Internet-Drafts are working documents of the Internet Engineering
25    Task Force (IETF), its areas, and its working groups.  Note that
26    other groups may also distribute working documents as Internet-
27    Drafts.
28
29    Internet-Drafts are draft documents valid for a maximum of six months
30    and may be updated, replaced, or obsoleted by other documents at any
31    time.  It is inappropriate to use Internet- Drafts as reference
32    material or to cite them other than as "work in progress."
33
34    The list of current Internet-Drafts can be accessed at
35    http://www.ietf.org/1id-abstracts.html
36
37    The list of Internet-Draft Shadow Directories can be accessed at
38    http://www.ietf.org/shadow.html
39
40    Discussion of this document should take place on the LDAP (v3)
41    Revision (ldapbis) Working Group mailing list <ietf-
42    ldapbis@openldap.org>.
43
44    Copyright (C) The Internet Society (2003).  All Rights Reserved.
45
46 2.  Abstract
47
48    LDAP search filters are transmitted in the LDAP protocol using a
49    binary representation that is appropriate for use on the network.
50    This document defines a human-readable string representation of LDAP
51    search filters that is appropriate for use in LDAP URLs and in other
52    applications.
53
54
55
56
57
58 Smith & Howes      Intended Category: Standards Track           [Page 1]
59 \f
60 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
61
62
63 3.  Table of Contents
64
65 1.     Status of this Memo............................................1
66 2.     Abstract.......................................................1
67 3.     Table of Contents..............................................2
68 4.     Introduction...................................................2
69 5.     LDAP Search Filter Definition..................................2
70 6.     String Search Filter Definition................................4
71 7.     Examples.......................................................5
72 8.     Security Considerations........................................7
73 9.     Normative References...........................................7
74 10.    Informative References.........................................8
75 11.    Acknowledgments................................................8
76 12.    Authors' Address...............................................8
77 13.    Full Copyright Statement.......................................9
78 14.    Appendix A: Changes Since RFC 2254.............................9
79 14.1.     Technical Changes...........................................9
80 14.2.     Editorial Changes...........................................10
81 15.    Appendix B: Changes Since Previous Document Revision...........11
82 15.1.     Technical Changes...........................................11
83 15.2.     Editorial Changes...........................................11
84
85 4.  Introduction
86
87    The Lightweight Directory Access Protocol (LDAP) [Protocol] defines a
88    network representation of a search filter transmitted to an LDAP
89    server.  Some applications may find it useful to have a common way of
90    representing these search filters in a human-readable form; LDAP URLs
91    are an example of one such application.  This document defines a
92    human-readable string format for representing the full range of
93    possible LDAP version 3 search filters, including extended match
94    filters.
95
96     This document is an integral part of the LDAP Technical
97    Specification [Roadmap].
98
99    This document replaces RFC 2254.  Changes to RFC 2254 are summarized
100    in Appendix A.
101
102    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
103    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
104    document are to be interpreted as described in BCP 14 [RFC2119].
105
106 5.  LDAP Search Filter Definition
107
108    An LDAPv3 search filter is defined in Section 4.5.1 of [Protocol] as
109    follows:
110
111
112
113
114 Smith & Howes      Intended Category: Standards Track           [Page 2]
115 \f
116 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
117
118
119         Filter ::= CHOICE {
120                 and                [0] SET SIZE (1..MAX) OF Filter,
121                 or                 [1] SET SIZE (1..MAX) OF Filter,
122                 not                [2] Filter,
123                 equalityMatch      [3] AttributeValueAssertion,
124                 substrings         [4] SubstringFilter,
125                 greaterOrEqual     [5] AttributeValueAssertion,
126                 lessOrEqual        [6] AttributeValueAssertion,
127                 present            [7] AttributeDescription,
128                 approxMatch        [8] AttributeValueAssertion,
129                 extensibleMatch    [9] MatchingRuleAssertion }
130
131         SubstringFilter ::= SEQUENCE {
132                 type    AttributeDescription,
133                 -- at least one must be present,
134                 -- initial and final can occur at most once
135                 substrings    SEQUENCE OF CHOICE {
136                         initial        [0] AssertionValue,
137                         any            [1] AssertionValue,
138                         final          [2] AssertionValue } }
139
140         AttributeValueAssertion ::= SEQUENCE {
141                 attributeDesc   AttributeDescription,
142                 assertionValue  AssertionValue }
143
144         MatchingRuleAssertion ::= SEQUENCE {
145                 matchingRule    [1] MatchingRuleId OPTIONAL,
146                 type            [2] AttributeDescription OPTIONAL,
147                 matchValue      [3] AssertionValue,
148                 dnAttributes    [4] BOOLEAN DEFAULT FALSE }
149
150         AttributeDescription ::= LDAPString
151                                  -- Constrained to attributedescription
152                                  -- [Models]
153
154         AttributeValue ::= OCTET STRING
155
156         MatchingRuleId ::= LDAPString
157
158         AssertionValue ::= OCTET STRING
159
160         LDAPString ::= OCTET STRING -- UTF-8 encoded,
161                                     -- ISO 10646 characters
162
163    where the LDAPString above is limited to the UTF-8 encoding [RFC2279]
164    of the ISO 10646 character set [ISO10646].  The AttributeDescription
165    is a string representation of the attribute description and is
166    defined in [Protocol].  The AttributeValue and AssertionValue OCTET
167
168
169
170 Smith & Howes      Intended Category: Standards Track           [Page 3]
171 \f
172 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
173
174
175    STRING have the form defined in [Syntaxes].  The Filter is encoded
176    for transmission over a network using the Basic Encoding Rules
177    defined in [ASN.1], with simplifications described in [Protocol].
178
179 6.  String Search Filter Definition
180
181    The string representation of an LDAP search filter is a string of
182    UTF-8 encoded ISO 10646-1 characters that is defined by the following
183    grammar, following the ABNF notation defined in [RFC2234].  The
184    productions used that are not defined here are defined in section 1.3
185    (Common ABNF Productions) of [Models] unless otherwise noted.  The
186    filter format uses a prefix notation.
187
188       filter         = LPAREN filtercomp RPAREN
189       filtercomp     = and / or / not / item
190       and            = AMPERSAND filterlist
191       or             = VERTBAR filterlist
192       not            = EXCLAMATION filter
193       filterlist     = 1*filter
194       item           = simple / present / substring / extensible
195       simple         = attr filtertype assertionvalue
196       filtertype     = equal / approx / greater / less
197       equal          = EQUALS
198       approx         = TILDE EQUALS
199       greater        = RANGLE EQUALS
200       less           = LANGLE EQUALS
201       extensible     = attr [dnattrs] [matchingrule] COLON EQUALS assertionvalue
202                        / [dnattrs] matchingrule COLON EQUALS assertionvalue
203                        / COLON EQUALS assertionvalue
204       present        = attr EQUALS ASTERIX
205       substring      = attr EQUALS [initial] any [final]
206       initial        = assertionvalue
207       any            = ASTERIX *(assertionvalue ASTERIX)
208       final          = assertionvalue
209       attr           = attributedescription
210                          ; The attributedescription rule is defined in
211                          ; Section 2.5 of [Models].
212       dnattrs        = COLON "dn"
213       matchingrule   = COLON oid
214       assertionvalue = valueencoding
215                          ; The <valueencoding> rule is used to encode an
216                          ; <AssertionValue> from Section 4.1.6 of [Protocol].
217       valueencoding  = 0*(normal / escaped)
218       normal         = UTF1SUBSET / UTFMB
219       escaped        = ESC HEX HEX
220       UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F
221                           ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
222                           ; RPAREN, ASTERIX, and ESC.
223
224
225
226 Smith & Howes      Intended Category: Standards Track           [Page 4]
227 \f
228 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
229
230
231       EXCLAMATION    = %x21 ; exclamation mark ("!")
232       AMPERSAND      = %x26 ; ampersand (or AND symbol) ("&")
233       ASTERIX        = %x2A ; asterix ("*")
234       COLON          = %x3A ; colon (":")
235       VERTBAR        = %x7C ; vertical bar (or pipe) ("|")
236       TILDE          = %x7E ; tilde ("~")
237
238
239    Note that although both the <substring> and <present> productions in
240    the grammar above can produce the "attr=*" construct, this construct
241    is used only to denote a presence filter.
242
243    The <valueencoding> rule ensures that the entire filter string is a
244    valid UTF-8 string and provides that the octets that represent the
245    ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII
246    0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a
247    backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits
248    representing the value of the encoded octet.
249
250    This simple escaping mechanism eliminates filter-parsing ambiguities
251    and allows any filter that can be represented in LDAP to be
252    represented as a NUL-terminated string. Other octets that are part of
253    the <normal> set may be escaped using this mechanism, for example,
254    non-printing ASCII characters.
255
256    For AssertionValues that contain UTF-8 character data, each octet of
257    the character to be escaped is replaced by a backslash and two hex
258    digits, which form a single octet in the code of the character.
259
260    For example, the filter checking whether the "cn" attribute contained
261    a value with the character "*" anywhere in it would be represented as
262    "(cn=*\2a*)".
263
264    As indicated by the valueencoding rule, implementations MUST escape
265    all octets greater than 0x7F that are not part of a valid UTF-8
266    encoding sequence when they generate a string representation of a
267    search filter.  Since RFC 2254 does not clearly define the term
268    "string representation" (and in particular does mention that the
269    string representation of an LDAP search filter is a string of UTF-8
270    encoded ISO 10646-1 characters) implementations SHOULD accept as
271    input strings that include invalid UTF-8 octet sequences.
272
273 7.  Examples
274
275    This section gives a few examples of search filters written using
276    this notation.
277
278         (cn=Babs Jensen)
279
280
281
282 Smith & Howes      Intended Category: Standards Track           [Page 5]
283 \f
284 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
285
286
287         (!(cn=Tim Howes))
288         (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
289         (o=univ*of*mich*)
290         (seeAlso=)
291
292    The following examples illustrate the use of extensible matching.
293
294         (cn:1.2.3.4.5:=Fred Flintstone)
295         (cn:=Betty Rubble)
296         (sn:dn:2.4.6.8.10:=Barney Rubble)
297         (o:dn:=Ace Industry)
298         (:1.2.3:=Wilma Flintstone)
299         (:dn:2.4.6.8.10:=Dino)
300         (:=Fred Flintstone)
301
302    The first example shows use of the matching rule "1.2.3.4.5".
303
304    The second example demonstrates use of a MatchingRuleAssertion form
305    without a matchingRule.
306
307    The third example illustrates the use of the ":dn" notation to
308    indicate that matching rule "2.4.6.8.10" should be used when making
309    comparisons, and that the attributes of an entry's distinguished name
310    should be considered part of the entry when evaluating the match.
311
312    The fourth example denotes an equality match, except that DN
313    components should be considered part of the entry when doing the
314    match.
315
316    The fifth example is a filter that should be applied to any attribute
317    supporting the matching rule given (since the attr has been omitted).
318
319    The sixth example is also a filter that should be applied to any
320    attribute supporting the matching rule given.  Attributes supporting
321    the matching rule contained in the DN should also be considered.
322
323    The seventh and final example is a filter that should be applied to
324    any attribute (since both the attr and matching rule have been
325    omitted).
326
327    The following examples illustrate the use of the escaping mechanism.
328
329         (o=Parens R Us \28for all your parenthetical needs\29)
330         (cn=*\2A*)
331         (filename=C:\5cMyFile)
332         (bin=\00\00\00\04)
333         (sn=Lu\c4\8di\c4\87)
334         (1.3.6.1.4.1.1466.0=\04\02\48\69)
335
336
337
338 Smith & Howes      Intended Category: Standards Track           [Page 6]
339 \f
340 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
341
342
343    The first example shows the use of the escaping mechanism to
344    represent parenthesis characters. The second shows how to represent a
345    "*" in an assertion value, preventing it from being interpreted as a
346    substring indicator. The third illustrates the escaping of the
347    backslash character.
348
349    The fourth example shows a filter searching for the four-byte value
350    0x00000004, illustrating the use of the escaping mechanism to
351    represent arbitrary data, including NUL characters.
352
353    The fifth example illustrates the use of the escaping mechanism to
354    represent various non-ASCII UTF-8 characters.
355
356    The sixth and final example demonstrates assertion of a BER encoded
357    value.
358
359 8.  Security Considerations
360
361    This memo describes a string representation of LDAP search filters.
362    While the representation itself has no known security implications,
363    LDAP search filters do. They are interpreted by LDAP servers to
364    select entries from which data is retrieved.  LDAP servers should
365    take care to protect the data they maintain from unauthorized access.
366
367    Please refer to the Security Considerations sections of [Protocol]
368    and [AuthMeth] for more information.
369
370 9.  Normative References
371
372    [ASN.1] Specification of ASN.1 encoding rules: Basic, Canonical, and
373    Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994.
374
375    [AuthMeth] Harrison, R. (editor), "LDAP: Authentication Methods and
376    Connection Level Security Mechanisms", draft-ietf-ldapbis-authmeth-
377    xx.txt, a work in progress.
378
379    [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) -
380    Architecture and Basic Multilingual Plane, ISO/IEC 10646-1, 1993.
381
382    [Models] Zeilenga, K. (editor), "LDAP: Directory Information Models",
383    draft-ietf-ldapbis-models-xx.txt, a work in progress.
384
385    [Protocol] Sermersheim, J. (editor), "LDAP: The Protocol", draft-
386    ietf-ldapbis-protocol-xx.txt, a work in progress.
387
388    [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
389    Requirement Levels", BCP 14 (also RFC 2119), March 1997.
390
391
392
393
394 Smith & Howes      Intended Category: Standards Track           [Page 7]
395 \f
396 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
397
398
399    [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax
400    Specifications:  ABNF", RFC 2234, November 1997.
401
402    [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
403    RFC 2279, January 1998.
404
405    [Roadmap] Zeilenga, K. (editor), "LDAP: Technical Specification Road
406    Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in progress.
407
408    [Syntaxes] Dally, K. (editor), "LDAP: Syntaxes", draft-ietf-ldapbis-
409    syntaxes-xx.txt, a work in progress.
410
411
412 10.  Informative References
413
414    None.
415
416
417 11.  Acknowledgments
418
419    This document replaces RFC 2254 by Tim Howes.  Changes included in
420    this revised specification are based upon discussions among the
421    authors, discussions within the LDAP (v3) Revision Working Group
422    (ldapbis), and discussions within other IETF Working Groups.  The
423    contributions of individuals in these working groups is gratefully
424    acknowledged.
425
426
427 12.  Authors' Address
428
429    Mark Smith, Editor
430    Netscape Communications Corp.
431    360 W. Caribbean Drive
432    Sunnyvale, CA 94089
433    USA
434    +1 650 937-3477
435    mcs@netscape.com
436
437    Tim Howes
438    Opsware, Inc.
439    599 N. Mathilda Ave.
440    Sunnyvale, CA 94085
441    USA
442    +1 408 744-7509
443    howes@opsware.com
444
445
446
447
448
449
450 Smith & Howes      Intended Category: Standards Track           [Page 8]
451 \f
452 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
453
454
455 13.  Full Copyright Statement
456
457    Copyright (C) The Internet Society (2003).  All Rights Reserved.
458
459    This document and translations of it may be copied and furnished to
460    others, and derivative works that comment on or otherwise explain it
461    or assist in its implementation may be prepared, copied, published
462    and distributed, in whole or in part, without restriction of any
463    kind, provided that the above copyright notice and this paragraph are
464    included on all such copies and derivative works.  However, this
465    document itself may not be modified in any way, such as by removing
466    the copyright notice or references to the Internet Society or other
467    Internet organizations, except as needed for the purpose of
468    developing Internet standards in which case the procedures for
469    copyrights defined in the Internet Standards process must be
470    followed, or as required to translate it into languages other than
471    English.
472
473    The limited permissions granted above are perpetual and will not be
474    revoked by the Internet Society or its successors or assigns.
475
476    This document and the information contained herein is provided on an
477    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
478    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
479    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
480    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
481    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
482
483
484 14.  Appendix A: Changes Since RFC 2254
485
486 14.1.  Technical Changes
487
488    The following technical changes were made to the contents of the
489    "String Search Filter Definition" section:
490
491    Added statement that the string representation is a string of UTF-8
492    encoded ISO 10646-1 characters.
493
494    Revised all of the ABNF to use common productions from [Models].
495
496    Replaced the "value" rule with a new "assertionvalue" rule within the
497    "simple", "extensible", and "substring" ("initial", "any", and
498    "final") rules.  This matches a change made in [Syntaxes].
499
500    Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more
501    precisely reference productions from the [Models] and [Protocol]
502    documents.
503
504
505
506 Smith & Howes      Intended Category: Standards Track           [Page 9]
507 \f
508 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
509
510
511    Introduced the "valueencoding" and associated "normal" and "escaped"
512    rules to reduce the dependence on descriptive text. The "normal"
513    production restricts filter strings to valid UTF-8 sequences.
514
515    Added a third option to the "extensible" production to allow creation
516    of a MatchingRuleAssertion that only has a matchValue.
517
518    Added a statement about expected behavior in light of RFC 2254's lack
519    of a clear definition of "string representation."
520
521
522 14.2.  Editorial Changes
523
524    Changed document title to include "LDAP:" prefix.
525
526    IESG Note: removed note about lack of satisfactory mandatory
527    authentication mechanisms.
528
529    Header and "Authors' Addresses" sections: added Mark Smith as the
530    document editor and updated affiliation and contact information.
531
532    "Table of Contents" section: added.
533
534    Copyright: updated the year.
535
536    "Abstract" section: separated from introductory material.
537
538    "Introduction" section: new section; separated from the Abstract.
539    Updated second paragraph to indicate that RFC 2254 is replaced by
540    this document (instead of RFC 1960). Added reference to the [Roadmap]
541    document.
542
543    "LDAP Search Filter Definition" section: made corrections to the
544    LDAPv3 search filter ABNF so it matches that used in [Protocol].
545
546    Clarified the definition of 'value' (now 'assertionvalue') to take
547    into account the fact that it is not precisely an AttributeAssertion
548    from [Protocol] section 4.1.6 (special handling is required for some
549    characters).  Added a note that each octet of a character to be
550    escaped is replaced by a backslash and two hex digits, which
551    represent a single octet.
552
553    "Examples" section: added five additional examples: (seeAlso=),
554    (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), (:=Fred Flintstone),
555    and (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a
556    value" with "an assertion value".
557
558    "Security Considerations" section: added references to [Protocol] and
559
560
561
562 Smith & Howes      Intended Category: Standards Track          [Page 10]
563 \f
564 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
565
566
567    [AuthMeth].
568
569    "Normative References" section: renamed from "References" per new RFC
570    guidelines. Changed from [1] style to [Protocol] style throughout the
571    document.  Added entries for [ISO10646], [RFC2119], [AuthMeth],
572    [Models], and [Roadmap] and updated UTF-8 reference to RFC 2279.
573    Replaced RFC 822 reference with a reference to RFC 2234.
574
575    "Informative References" section: added for clarity.
576
577    "Acknowledgments" section: added.
578
579    "Appendix A: Changes Since RFC 2254" section: added.
580
581    "Appendix B: Changes Since Previous Document Revision" section:
582    added.
583
584
585 15.  Appendix B: Changes Since Previous Document Revision
586
587    This appendix lists all changes relative to the last published
588    revision, draft-ietf-ldapbis-filter-03.txt.  Note that when
589    appropriate these changes are also included in Appendix A, but are
590    also included here for the benefit of the people who have already
591    reviewed draft-ietf-ldapbis-filter-03.txt.  This section will be
592    removed before this document is published as an RFC.
593
594
595 15.1.  Technical Changes
596
597    "String Search Filter Definition" section: Added statement that the
598    string representation is a string of UTF-8 encoded ISO 10646-1
599    characters and statement about expected behavior in light of RFC
600    2254's lack of a clear definition of "string representation."
601
602    "String Search Filter Definition" section: Revised all of the ABNF to
603    use common productions from [Models].  Revised the "normal"
604    production to restrict filter strings to valid UTF-8 sequences.
605
606
607 15.2.  Editorial Changes
608
609    "Status of this Memo" section: updated boilerplate to match current
610    I-D guidelines.
611
612    "Examples" section: removed ;binary from an example.
613
614    "LDAP Search Filter Definition " section: updated section references
615
616
617
618 Smith & Howes      Intended Category: Standards Track          [Page 11]
619 \f
620 INTERNET-DRAFT   LDAP: String Repres. of Search Filters 28 February 2003
621
622
623    to match current LDAPBis drafts. Made minor changes to the ASN.1 so
624    it exactly matches that used in the Protocol document (added
625    comments).
626
627    "Normative References" section: added references to [ISO10646],
628    [RFC2119] and [Models].
629
630    "Informative References" section: added for clarity.
631
632    Updated copyright year to 2003.
633
634
635 This Internet Draft expires on 28 August 2003.
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674 Smith & Howes      Intended Category: Standards Track          [Page 12]
675 \f