idnits 2.17.1 draft-ietf-ldapbis-filter-00.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 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 3 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** The abstract seems to contain references ([RFC2251]), 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 (20 February 2001) is 8464 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 425 -- 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 ** 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: 17 errors (**), 0 flaws (~~), 3 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: 20 August 2001 Loudcloud, Inc. 6 20 February 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) [RFC2251] defines a 43 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 [RFC2251] as 56 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] LDAPString, 76 any [1] LDAPString, 77 final [2] LDAPString 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 [RFC2251]. The AttributeValue and AssertionValue OCTET STRING have 106 the form defined in [RFC2252]. The Filter is encoded for 107 transmission over a network using the Basic Encoding Rules defined in 108 [ASN.1], with simplifications described in [RFC2251]. 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 = value 134 any = "*" *(value "*") 135 final = value 136 attr = 137 matchingrule = 138 value = 140 assertionvalue = 143 valueencoding = 0*(normal / escaped) 144 normal = %x01-27 / %x2b-5b / %x5d-7f 145 escaped = " 0" / "2" ( "8" / "9" / "a" ) / "5c" 147 The attr and matchingrule constructs are as described in the 148 corresponding section of [RFC2251] given above. 150 The valueencoding rule provides that the characters "*" (ASCII 0x2a), 151 "(" (ASCII 0x28), ")" (ASCII 0x29), " 0x00) are represented as the 152 backslash " followed by the two hexadecimal digits representing the 153 ASCII value of the encoded character. 155 This simple escaping mechanism eliminates filter-parsing ambiguities 156 and allows any filter that can be represented in LDAP to be 157 represented as a NUL-terminated string. Other characters besides the 158 ones listed above may be escaped using this mechanism, for example, 159 non-printing characters. 161 For example, the filter checking whether the "cn" attribute contained 162 a value with the character "*" anywhere in it would be represented as 163 "(cn=*\2a*)". 165 Note that although both the substring and present productions in the 166 grammar above can produce the "attr=*" construct, this construct is 167 used only to denote a presence filter. 169 5. Examples 171 This section gives a few examples of search filters written using 172 this notation. 174 (cn=Babs Jensen) 175 (!(cn=Tim Howes)) 176 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) 177 (o=univ*of*mich*) 178 (seeAlso=) 180 The following examples illustrate the use of extensible matching. 182 (cn:1.2.3.4.5:=Fred Flintstone) 183 (cn:=Betty Rubble) 184 (sn:dn:2.4.6.8.10:=Barney Rubble) 185 (o:dn:=Ace Industry) 186 (:1.2.3:=Wilma Flintstone) 187 (:dn:2.4.6.8.10:=Dino) 189 The first example shows use of the matching rule "1.2.3.4.5". 191 The second example demonstrates use of a MatchingRuleAssertion form 192 without a matchingRule. 194 The third example illustrates the use of the ":dn" notation to 195 indicate that matching rule "2.4.6.8.10" should be used when making 196 comparisons, and that the attributes of an entry's distinguished name 197 should be considered part of the entry when evaluating the match. 199 The fourth example denotes an equality match, except that DN 200 components should be considered part of the entry when doing the 201 match. 203 The fifth example is a filter that should be applied to any attribute 204 supporting the matching rule given (since the attr has been omitted). 206 The sixth and final example is also a filter that should be applied 207 to any attribute supporting the matching rule given. Attributes 208 supporting the matching rule contained in the DN should also be 209 considered. 211 The following examples illustrate the use of the escaping mechanism. 213 (o=Parens R Us \28for all your parenthetical needs\29) 214 (cn=*\2A*) 215 (filename=C:\5cMyFile) 216 (bin=\00\00\00\04) 217 (sn=Lu\c4\8di\c4\87) 218 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69) 220 The first example shows the use of the escaping mechanism to 221 represent parenthesis characters. The second shows how to represent a 222 "*" in a value, preventing it from being interpreted as a substring 223 indicator. The third illustrates the escaping of the backslash 224 character. 226 The fourth example shows a filter searching for the four-byte value 227 0x00000004, illustrating the use of the escaping mechanism to 228 represent arbitrary data, including NUL characters. 230 The fifth example illustrates the use of the escaping mechanism to 231 represent various non-ASCII UTF-8 characters. 233 The sixth and final example demonstrates assertion of a BER encoded 234 value. 236 6. Security Considerations 238 This memo describes a string representation of LDAP search filters. 239 While the representation itself has no known security implications, 240 LDAP search filters do. They are interpreted by LDAP servers to 241 select entries from which data is retrieved. LDAP servers should 242 take care to protect the data they maintain from unauthorized access. 244 Please refer to the Security Considerations sections of RFC 2251 245 [RFC2251], RFC 2829 [RFC2829], and RFC 2830 [RFC2830] for more 246 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 [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory 257 Access Protocol (v3)", RFC 2251, December 1997. 259 [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, 260 "Lightweight Directory Access Protocol (v3): Attribute Syntax 261 Definitions", RFC 2252, December 1997. 263 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 264 RFC 2279, January 1998. 266 [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, 267 "Authentication Methods for LDAP", RFC 2829, May 2000. 269 [RFC2830] Hodges, J., Morgan, R., Wahl, M., "Lightweight Directory 270 Access Protocol (v3): Extension for Transport Layer Security", RFC 271 2830, May 2000. 273 8. Acknowledgments 275 This document is an update to RFC 2254 by Tim Howes. Changes 276 included in this revised specification are based upon discussions 277 among the authors, discussions within the LDAP (v3) Revision Working 278 Group (ldapbis), and discussions within other IETF Working Groups. 279 The contributions of individuals in these working groups is 280 gratefully acknowledged. 282 9. Authors' Address 284 Mark Smith (document editor) 285 Netscape Communications Corp. 286 Mailstop USCA17-201 287 4170 Network Circle 288 Santa Clara, CA 95054 289 USA 290 +1 650 937-3477 291 mcs@netscape.com 293 Tim Howes 294 Loudcloud, Inc. 295 599 N. Mathilda Ave. 296 Sunnyvale, CA 94086 297 USA 298 +1 408 744-7509 299 howes@loudcloud.com 301 10. Full Copyright Statement 303 Copyright (C) The Internet Society (2001). All Rights Reserved. 305 This document and translations of it may be copied and furnished to 306 others, and derivative works that comment on or otherwise explain it 307 or assist in its implementation may be prepared, copied, published 308 and distributed, in whole or in part, without restriction of any 309 kind, provided that the above copyright notice and this paragraph are 310 included on all such copies and derivative works. However, this 311 document itself may not be modified in any way, such as by removing 312 the copyright notice or references to the Internet Society or other 313 Internet organizations, except as needed for the purpose of 314 developing Internet standards in which case the procedures for 315 copyrights defined in the Internet Standards process must be 316 followed, or as required to translate it into languages other than 317 English. 319 The limited permissions granted above are perpetual and will not be 320 revoked by the Internet Society or its successors or assigns. 322 This document and the information contained herein is provided on an 323 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 324 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 325 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 326 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 327 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 329 11. Appendix A: Changes Since RFC 2254 331 11.1. Technical Changes 333 "String Search Filter Definition" section: replaced the "value" rule 334 with a new "assertionvalue" rule within the "simple" and "extensible" 335 rules. Added angle brackets around free-form prose in the "attr", 336 "matchingrule", and "value" rules. Introduced the "valueencoding" 337 and associated "normal" and "escaped" rules to reduce the dependence 338 on descriptive text. 340 11.2. Editorial Changes 342 IESG Note: removed note about lack of satisfactory mandatory 343 authentication mechanisms. 345 Header and "Authors' Addresses" sections: added Mark Smith as the 346 document editor and updated Tim's affiliation and contact 347 information. 349 Copyright: changed the year to 2001. 351 "Abstract" section: updated second paragraph to indicate that RFC 352 2254 is replaced by this document (instead of RFC 1960). 354 "LDAP Search Filter Definition" section: made corrections to the 355 LDAPv3 search filter ABNF so it matches RFC 2251. In particular, the 356 "at least one must be present" comment and the "substrings" label 357 were added to the SubstringFilter initial/any/final sequence and the 358 second element of the AttributeValueAssertion was changed from 359 "attributeValue AttributeValue" to "assertionValue AssertionValue." 361 "Search Filter Definition" section: clarified the definition of 362 AttributeValue from RFC 2251 section 4.1.6 (special handling is 363 required for some characters). 365 "Examples" section: added four additional examples: (seeAlso=), 366 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and 367 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69). 369 "Security Considerations" section: added references to RFC 2251, RFC 370 2829, and RFC 2830. 372 "References" section: changed from [1] style to [RFC2251] style 373 throughout the document. Added entries for RFC 2829 and RFC 2830 and 374 updated UTF-8 reference to RFC 2279. Replaced RFC 822 reference with 375 a RFC 2234. 377 "Acknowledgments" section: added. 379 "Appendix A: Changes Since RFC 2254" section: added. 381 "Appendix B: Changes Since Previous Document Revision" section: 382 added. 384 "Appendix C: Loose Ends" section: added. 386 "Table of Contents" section: added. 388 12. Appendix B: Changes Since Previous Document Revision 390 This appendix lists all changes relative to the last published revision, 391 draft-smith-ldapv3-filter-update-01.txt. Note that these changes are 392 also included in Appendix A, but are included here for those who have 393 already reviewed draft-smith-ldapv3-filter-update-01.txt. 395 12.1. Technical Changes 397 "String Search Filter Definition" section: replaced the "value" rule 398 with a new "assertionvalue" rule within the "simple" and "extensible" 399 rules. Added angle brackets around free-form prose in the "attr", 400 "matchingrule", and "value" rules. Introduced the "valueencoding" 401 and associated "normal" and "escaped" rules to reduce the dependence 402 on descriptive text. 404 12.2. Editorial Changes 406 Header: changed document from an individual submission to an ldapbis 407 working group submission. Discussion referred to the ietf- 408 ldapbis@openldap.org mailing list. 410 Header and "Authors' Addresses" sections: added "editor" next to Mark 411 Smith's name. 413 Copyright: changed the year to 2001. 415 "LDAP Search Filter Definition" section: made corrections to the 416 LDAPv3 search filter ABNF so it matches RFC 2251. In particular, the 417 "at least one must be present" comment and the "substrings" label 418 were added to the SubstringFilter initial/any/final sequence and the 419 second element of the AttributeValueAssertion was changed from 420 "attributeValue AttributeValue" to "assertionValue AssertionValue." 422 "Examples" section: added the "(seeAlso=)" example to demonstrate 423 assertion of a zero-length value. 425 References: changed from [1] style to [RFC2251] style throughout the 426 document. Replaced reference to RFC 822 with a reference to RFC 427 2234. 429 "Acknowledgments" section: added. 431 "Appendix C: Loose Ends": removed RFC 2234 ABNF item and added a new 432 item about possible changes to the LDAPv3 protocol document that may 433 result in changes to this document. 435 13. Appendix C: Loose Ends 437 There has been some discussion on the LDAPBIS working group 438 discussion list about how to modify the LDAPv3 protocol specification 439 to support use of substring filters within an extensible match 440 filter, which led to further discussion about whether the definition 441 of the SubstringFilter should be changed from LDAPString to 442 AssertionValue. Once that issue is resolved, this filter 443 specification will likely need to be revised to accommodate the 444 group's decision. 446 This Internet Draft expires on 20 August 2001. 448 1. Status of this Memo............................................1 449 2. Abstract.......................................................1 450 3. LDAP Search Filter Definition..................................2 451 4. String Search Filter Definition................................3 452 5. Examples.......................................................5 453 6. Security Considerations........................................6 454 7. References.....................................................7 455 8. Acknowledgments................................................7 456 9. Authors' Address...............................................7 457 10. Full Copyright Statement.......................................8 458 11. Appendix A: Changes Since RFC 2254.............................8 459 11.1. Technical Changes...........................................8 460 11.2. Editorial Changes...........................................9 461 12. Appendix B: Changes Since Previous Document Revision...........10 462 12.1. Technical Changes...........................................10 463 12.2. Editorial Changes...........................................10 464 13. Appendix C: Loose Ends.........................................11