idnits 2.17.1 draft-ietf-ldapbis-filter-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([RFC2251bis]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 87: '... matchingRule [1] MatchingRuleID OPTIONAL,...' RFC 2119 keyword, line 88: '... type [2] AttributeDescription OPTIONAL,...' == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (7 May 2001) is 8389 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 75 -- Looks like a reference, but probably isn't: '1' on line 378 -- Looks like a reference, but probably isn't: '2' on line 88 -- Looks like a reference, but probably isn't: '3' on line 89 -- Looks like a reference, but probably isn't: '4' on line 90 -- Looks like a reference, but probably isn't: '5' on line 64 -- Looks like a reference, but probably isn't: '6' on line 65 -- Looks like a reference, but probably isn't: '7' on line 66 -- Looks like a reference, but probably isn't: '8' on line 67 -- Looks like a reference, but probably isn't: '9' on line 68 == Missing Reference: 'RFC22521bis' is mentioned on line 333, but not defined == Missing Reference: 'RFC2253bis' is mentioned on line 421, but not defined ** Obsolete undefined reference: RFC 2253 (Obsoleted by RFC 4510, RFC 4514) ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2829 (Obsoleted by RFC 4510, RFC 4513) ** Obsolete normative reference: RFC 2830 (Obsoleted by RFC 4510, RFC 4511, RFC 4513) Summary: 18 errors (**), 0 flaws (~~), 6 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Smith, Editor 3 Request for Comments: DRAFT Netscape Communications Corp. 4 Obsoletes: RFC 2254 T. Howes 5 Expires: 7 November 2001 Loudcloud, Inc. 6 7 May 2001 8 The String Representation of LDAP Search Filters 9 11 1. Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. Internet-Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its areas, 16 and its working groups. Note that other groups may also distribute 17 working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet- Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Discussion of this document should take place on the LDAP (v3) 31 Revison (ldapbis) Working Group mailing list . After appropriate review and discussion, this 33 document will be submitted as a Standards Track replacement for RFC 34 2254. 36 Copyright Notice 38 Copyright (C) The Internet Society (2001). All Rights Reserved. 40 2. Abstract 42 The Lightweight Directory Access Protocol (LDAP) [RFC2251bis] defines 43 a network representation of a search filter transmitted to an LDAP 44 server. Some applications may find it useful to have a common way of 45 representing these search filters in a human-readable form. This 46 document defines a human-readable string format for representing the 47 full range of possible LDAP version 3 search filters, including 48 extended match filters. 50 This document replaces RFC 2254. See Appendix A for a list of 51 changes relative to RFC 2254. 53 3. LDAP Search Filter Definition 55 An LDAPv3 search filter is defined in Sections 4.5.1 of [RFC2251bis] 56 as follows: 58 Filter ::= CHOICE { 59 and [0] SET OF Filter, 60 or [1] SET OF Filter, 61 not [2] Filter, 62 equalityMatch [3] AttributeValueAssertion, 63 substrings [4] SubstringFilter, 64 greaterOrEqual [5] AttributeValueAssertion, 65 lessOrEqual [6] AttributeValueAssertion, 66 present [7] AttributeDescription, 67 approxMatch [8] AttributeValueAssertion, 68 extensibleMatch [9] MatchingRuleAssertion 69 } 71 SubstringFilter ::= SEQUENCE { 72 type AttributeDescription, 73 -- at least one must be present 74 substrings SEQUENCE OF CHOICE { 75 initial [0] AssertionValue, 76 any [1] AssertionValue, 77 final [2] AssertionValue 78 } 79 } 81 AttributeValueAssertion ::= SEQUENCE { 82 attributeDesc AttributeDescription, 83 assertionValue AssertionValue 84 } 86 MatchingRuleAssertion ::= SEQUENCE { 87 matchingRule [1] MatchingRuleID OPTIONAL, 88 type [2] AttributeDescription OPTIONAL, 89 matchValue [3] AssertionValue, 90 dnAttributes [4] BOOLEAN DEFAULT FALSE 91 } 93 AttributeDescription ::= LDAPString 94 AttributeValue ::= OCTET STRING 96 MatchingRuleID ::= LDAPString 98 AssertionValue ::= OCTET STRING 100 LDAPString ::= OCTET STRING 102 where the LDAPString above is limited to the UTF-8 encoding of the 103 ISO 10646 character set [RFC2279]. The AttributeDescription is a 104 string representation of the attribute description and is defined in 105 [RFC2251bis]. The AttributeValue and AssertionValue OCTET STRING 106 have the form defined in [RFC2252bis]. The Filter is encoded for 107 transmission over a network using the Basic Encoding Rules defined in 108 [ASN.1], with simplifications described in [RFC2251bis]. 110 4. String Search Filter Definition 112 The string representation of an LDAP search filter is defined by the 113 following grammar, following the ABNF notation defined in [RFC2234]. 114 The filter format uses a prefix notation. 116 filter = "(" filtercomp ")" 117 filtercomp = and / or / not / item 118 and = "&" filterlist 119 or = "|" filterlist 120 not = "!" filter 121 filterlist = 1*filter 122 item = simple / present / substring / extensible 123 simple = attr filtertype assertionvalue 124 filtertype = equal / approx / greater / less 125 equal = "=" 126 approx = "~=" 127 greater = ">=" 128 less = "<=" 129 extensible = attr [":dn"] [":" matchingrule] ":=" assertionvalue 130 / [":dn"] ":" matchingrule ":=" assertionvalue 131 present = attr "=*" 132 substring = attr "=" [initial] any [final] 133 initial = assertionvalue 134 any = "*" *(assertionvalue "*") 135 final = assertionvalue 136 attr = 137 matchingrule = 138 assertionvalue = 140 valueencoding = 0*(normal / escaped) 141 normal = %x01-27 / %x2b-5b / %x5d-7f 142 escaped = "\" hex hex 143 hex = %x30-39 / %x41-46 / %x61-66 145 The attr and matchingrule constructs are as described in the 146 corresponding section of [RFC2251bis] given above. 148 The valueencoding rule provides that the characters "*" (ASCII 0x2a), 149 "(" (ASCII 0x28), ")" (ASCII 0x29), "\" (ASCII 0x5c), and NUL (ASCII 150 0x00) are represented as the backslash "\" character (ASCII 0x5c) 151 followed by the two hexadecimal digits representing the ASCII value 152 of the encoded character. 154 This simple escaping mechanism eliminates filter-parsing ambiguities 155 and allows any filter that can be represented in LDAP to be 156 represented as a NUL-terminated string. Other characters besides the 157 ones listed above may be escaped using this mechanism, for example, 158 non-printing characters. Each octet of the character to be escaped 159 is replaced by a backslash and two hex digits, which form a single 160 octet in the code of the character. 162 For example, the filter checking whether the "cn" attribute contained 163 a value with the character "*" anywhere in it would be represented as 164 "(cn=*\2a*)". 166 Note that although both the substring and present productions in the 167 grammar above can produce the "attr=*" construct, this construct is 168 used only to denote a presence filter. 170 5. Examples 172 This section gives a few examples of search filters written using 173 this notation. 175 (cn=Babs Jensen) 176 (!(cn=Tim Howes)) 177 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) 178 (o=univ*of*mich*) 179 (seeAlso=) 181 The following examples illustrate the use of extensible matching. 183 (cn:1.2.3.4.5:=Fred Flintstone) 184 (cn:=Betty Rubble) 185 (sn:dn:2.4.6.8.10:=Barney Rubble) 186 (o:dn:=Ace Industry) 187 (:1.2.3:=Wilma Flintstone) 188 (:dn:2.4.6.8.10:=Dino) 190 The first example shows use of the matching rule "1.2.3.4.5". 192 The second example demonstrates use of a MatchingRuleAssertion form 193 without a matchingRule. 195 The third example illustrates the use of the ":dn" notation to 196 indicate that matching rule "2.4.6.8.10" should be used when making 197 comparisons, and that the attributes of an entry's distinguished name 198 should be considered part of the entry when evaluating the match. 200 The fourth example denotes an equality match, except that DN 201 components should be considered part of the entry when doing the 202 match. 204 The fifth example is a filter that should be applied to any attribute 205 supporting the matching rule given (since the attr has been omitted). 207 The sixth and final example is also a filter that should be applied 208 to any attribute supporting the matching rule given. Attributes 209 supporting the matching rule contained in the DN should also be 210 considered. 212 The following examples illustrate the use of the escaping mechanism. 214 (o=Parens R Us \28for all your parenthetical needs\29) 215 (cn=*\2A*) 216 (filename=C:\5cMyFile) 217 (bin=\00\00\00\04) 218 (sn=Lu\c4\8di\c4\87) 219 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69) 221 The first example shows the use of the escaping mechanism to 222 represent parenthesis characters. The second shows how to represent a 223 "*" in an assertion value, preventing it from being interpreted as a 224 substring indicator. The third illustrates the escaping of the 225 backslash character. 227 The fourth example shows a filter searching for the four-byte value 228 0x00000004, illustrating the use of the escaping mechanism to 229 represent arbitrary data, including NUL characters. 231 The fifth example illustrates the use of the escaping mechanism to 232 represent various non-ASCII UTF-8 characters. 234 The sixth and final example demonstrates assertion of a BER encoded 235 value. 237 6. Security Considerations 239 This memo describes a string representation of LDAP search filters. 240 While the representation itself has no known security implications, 241 LDAP search filters do. They are interpreted by LDAP servers to 242 select entries from which data is retrieved. LDAP servers should 243 take care to protect the data they maintain from unauthorized access. 245 Please refer to the Security Considerations sections of [RFC2251bis], 246 [RFC2829bis], and [RFC2830bis] for more information. 248 7. References 250 [ASN.1] Specification of ASN.1 encoding rules: Basic, Canonical, and 251 Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994. 253 [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax 254 Specifications: ABNF", RFC 2234, November 1997. 256 [RFC2251bis] IETF LDAPBis WG, "Lightweight Directory Access Protocol 257 (v3)", a work in progress. 259 [RFC2252bis] IETF LDAPBis WG, "Lightweight Directory Access Protocol 260 (v3): Attribute Syntax Definitions", a work in progress. 262 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 263 RFC 2279, January 1998. 265 [RFC2829bis] IETF LDAPBis WG, "Authentication Methods for LDAP", a 266 work in progress. 268 [RFC2830bis] IETF LDAPBis WG, "Lightweight Directory Access Protocol 269 (v3): Extension for Transport Layer Security", a work in progress. 271 8. Acknowledgments 273 This document is an update to RFC 2254 by Tim Howes. Changes 274 included in this revised specification are based upon discussions 275 among the authors, discussions within the LDAP (v3) Revision Working 276 Group (ldapbis), and discussions within other IETF Working Groups. 277 The contributions of individuals in these working groups is 278 gratefully acknowledged. 280 9. Authors' Address 282 Mark Smith (document editor) 283 Netscape Communications Corp. 284 Mailstop USCA17-201 285 4170 Network Circle 286 Santa Clara, CA 95054 287 USA 288 +1 650 937-3477 289 mcs@netscape.com 290 Tim Howes 291 Loudcloud, Inc. 292 599 N. Mathilda Ave. 293 Sunnyvale, CA 94086 294 USA 295 +1 408 744-7509 296 howes@loudcloud.com 298 10. Full Copyright Statement 300 Copyright (C) The Internet Society (2001). All Rights Reserved. 302 This document and translations of it may be copied and furnished to 303 others, and derivative works that comment on or otherwise explain it 304 or assist in its implementation may be prepared, copied, published 305 and distributed, in whole or in part, without restriction of any 306 kind, provided that the above copyright notice and this paragraph are 307 included on all such copies and derivative works. However, this 308 document itself may not be modified in any way, such as by removing 309 the copyright notice or references to the Internet Society or other 310 Internet organizations, except as needed for the purpose of 311 developing Internet standards in which case the procedures for 312 copyrights defined in the Internet Standards process must be 313 followed, or as required to translate it into languages other than 314 English. 316 The limited permissions granted above are perpetual and will not be 317 revoked by the Internet Society or its successors or assigns. 319 This document and the information contained herein is provided on an 320 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 321 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 322 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 323 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 324 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 326 11. Appendix A: Changes Since RFC 2254 328 11.1. Technical Changes 330 "String Search Filter Definition" section: replaced the "value" rule 331 with a new "assertionvalue" rule within the "simple", "extensible", 332 and "substring" ("initial", "any", and "final") rules. This matches 333 a change made in [RFC22521bis]. Added angle brackets around free- 334 form prose in the "attr", "matchingrule", and "value" rules. 335 Introduced the "valueencoding" and associated "normal" and "escaped" 336 rules to reduce the dependence on descriptive text. 338 11.2. Editorial Changes 340 IESG Note: removed note about lack of satisfactory mandatory 341 authentication mechanisms. 343 Header and "Authors' Addresses" sections: added Mark Smith as the 344 document editor and updated Tim's affiliation and contact 345 information. 347 Copyright: changed the year to 2001. 349 "Abstract" section: updated second paragraph to indicate that RFC 350 2254 is replaced by this document (instead of RFC 1960). 352 "LDAP Search Filter Definition" section: made corrections to the 353 LDAPv3 search filter ABNF so it matches that used in [RFC2251bis]. 354 In particular, the "at least one must be present" comment and the 355 "substrings" label were added to the SubstringFilter 356 initial/any/final sequence, the second element of the 357 AttributeValueAssertion was changed from "attributeValue 358 AttributeValue" to "assertionValue AssertionValue", and the 359 occurrences of "LDAPString" were replaced with "AssertionValue" 360 within the initial, any, and final elements of the substrings choice. 362 "String Search Filter Definition" section: clarified the definition 363 of 'value' (now 'assertionvalue') to take into account the fact that 364 it is not precisely an AttributeAssertion from [RFC2251bis] section 365 4.1.6 (special handling is required for some characters). Added a 366 note that each octet of a character to be escaped is replaced by a 367 backslash and two hex digits, which form a single octet in the code 368 of the character (text taken from the [RFC2253bis] document). 370 "Examples" section: added four additional examples: (seeAlso=), 371 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and 372 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69). Replaced one occurrence of 373 "a value" with "an assertion value". 375 "Security Considerations" section: added references to [RFC2251bis], 376 [RFC2829bis], and [RFC2830bis]. 378 "References" section: changed from [1] style to [RFC2251bis] style 379 throughout the document. Added entries for [RFC2829bis] and 380 [RFC2830bis] and updated UTF-8 reference to RFC 2279. Replaced RFC 381 822 reference with a reference to RFC 2234. 383 "Acknowledgments" section: added. 385 "Appendix A: Changes Since RFC 2254" section: added. 387 "Appendix B: Changes Since Previous Document Revision" section: 388 added. 390 "Table of Contents" section: added. 392 12. Appendix B: Changes Since Previous Document Revision 394 This appendix lists all changes relative to the last published 395 revision, draft-ietf-ldapbis-filter-00.txt. Note that these changes 396 are also included in Appendix A, but are included here for those who 397 have already reviewed draft-ietf-ldapbis-filter-00.txt. This section 398 will be removed before this document is published as an RFC. 400 12.1. Technical Changes 402 "String Search Filter Definition" section: replaced all occurrences 403 of the "value" rule with "assertionvalue" within the "initial", 404 "any", and "final" rules. This was done to reflect changes made to 405 the ASN.1 definition of the Filter in [RFC2251bis]. Also, the 406 "escaped" rule was revised and a "hex" rule was added to allow any 407 character to be escaped. 409 12.2. Editorial Changes 411 "LDAP Search Filter Definition" section: updated the ASN.1 definition 412 of the Filter to match that used in [RFC2251bis]. Specifically, the 413 occurrences of LDAPString within the initial, any, and final elements 414 of the substrings element were replaced with AssertionValue. 416 "String Search Filter Definition" section: corrected truncated text 417 that described the valueencoding rule (the text was truncated after 418 (ASCII 0x29)). Added a note that each octet of a character to be 419 escaped is replaced by a backslash and two hex digits, which form a 420 single octet in the code of the character (text taken from the 421 [RFC2253bis] document). 423 "Examples" section: replaced one occurrence of "a value" with "an 424 assertion value". 426 References: updated references to refer to LDAPBis WG documents. 428 "Appendix C: Loose Ends": removed this section entirely. 430 This Internet Draft expires on 7 November 2001. 432 1. Status of this Memo............................................1 433 2. Abstract.......................................................1 434 3. LDAP Search Filter Definition..................................2 435 4. String Search Filter Definition................................3 436 5. Examples.......................................................5 437 6. Security Considerations........................................6 438 7. References.....................................................7 439 8. Acknowledgments................................................7 440 9. Authors' Address...............................................7 441 10. Full Copyright Statement.......................................8 442 11. Appendix A: Changes Since RFC 2254.............................8 443 11.1. Technical Changes...........................................8 444 11.2. Editorial Changes...........................................9 445 12. Appendix B: Changes Since Previous Document Revision...........10 446 12.1. Technical Changes...........................................10 447 12.2. Editorial Changes...........................................10