idnits 2.17.1 draft-smith-ldapv3-filter-update-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 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 2 instances of too long lines in the document, the longest one being 10 characters in excess of 72. ** The abstract seems to contain references ([1]), 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 85: '... matchingRule [1] MatchingRuleID OPTIONAL,...' RFC 2119 keyword, line 86: '... type [2] AttributeDescription OPTIONAL,...' RFC 2119 keyword, line 369: '...art: "At least one filter element MUST...' == 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 (22 November 2000) is 8556 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) == Missing Reference: '0' is mentioned on line 73, but not defined == Missing Reference: '8' is mentioned on line 66, but not defined == Missing Reference: '9' is mentioned on line 67, but not defined ** Obsolete normative reference: RFC 2251 (ref. '1') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (ref. '2') (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 2279 (ref. '4') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 822 (ref. '5') (Obsoleted by RFC 2822) ** Obsolete normative reference: RFC 2829 (ref. '6') (Obsoleted by RFC 4510, RFC 4513) ** Obsolete normative reference: RFC 2830 (ref. '7') (Obsoleted by RFC 4510, RFC 4511, RFC 4513) Summary: 17 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Howes 3 Request for Comments: DRAFT Loudcloud, Inc. 4 Obsoletes: RFC 2254 M. Smith 5 Expires: May 2001 Netscape Communications Corp. 6 22 November 2000 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 Extensions 31 Working Group mailing list . After 32 appropriate review and discussion, this document will be submitted as 33 a Standards Track replacement for RFC 2254. 35 Copyright Notice 37 Copyright (C) The Internet Society (2000). All Rights Reserved. 39 2. Abstract 41 The Lightweight Directory Access Protocol (LDAP) [1] defines a 42 network representation of a search filter transmitted to an LDAP 43 server. Some applications may find it useful to have a common way of 44 representing these search filters in a human-readable form. This 45 document defines a human-readable string format for representing the 46 full range of possible LDAP version 3 search filters, including 47 extended match filters. 49 This document replaces RFC 2254. See Appendix A for a list of 50 changes relative to RFC 2254. 52 3. LDAP Search Filter Definition 54 An LDAPv3 search filter is defined in Section 4.5.1 of [1] as 55 follows: 57 Filter ::= CHOICE { 58 and [0] SET OF Filter, 59 or [1] SET OF Filter, 60 not [2] Filter, 61 equalityMatch [3] AttributeValueAssertion, 62 substrings [4] SubstringFilter, 63 greaterOrEqual [5] AttributeValueAssertion, 64 lessOrEqual [6] AttributeValueAssertion, 65 present [7] AttributeDescription, 66 approxMatch [8] AttributeValueAssertion, 67 extensibleMatch [9] MatchingRuleAssertion 68 } 70 SubstringFilter ::= SEQUENCE { 71 type AttributeDescription, 72 SEQUENCE OF CHOICE { 73 initial [0] LDAPString, 74 any [1] LDAPString, 75 final [2] LDAPString 76 } 77 } 79 AttributeValueAssertion ::= SEQUENCE { 80 attributeDesc AttributeDescription, 81 attributeValue AttributeValue 82 } 84 MatchingRuleAssertion ::= SEQUENCE { 85 matchingRule [1] MatchingRuleID OPTIONAL, 86 type [2] AttributeDescription OPTIONAL, 87 matchValue [3] AssertionValue, 88 dnAttributes [4] BOOLEAN DEFAULT FALSE 89 } 91 AttributeDescription ::= LDAPString 93 AttributeValue ::= OCTET STRING 94 MatchingRuleID ::= LDAPString 96 AssertionValue ::= OCTET STRING 98 LDAPString ::= OCTET STRING 100 where the LDAPString above is limited to the UTF-8 encoding of the 101 ISO 10646 character set [4]. The AttributeDescription is a string 102 representation of the attribute description and is defined in [1]. 103 The AttributeValue and AssertionValue OCTET STRING have the form 104 defined in [2]. The Filter is encoded for transmission over a 105 network using the Basic Encoding Rules defined in [3], with 106 simplifications described in [1]. 108 4. String Search Filter Definition 110 The string representation of an LDAP search filter is defined by the 111 following grammar, following the ABNF notation defined in [5]. The 112 filter format uses a prefix notation. 114 filter = "(" filtercomp ")" 115 filtercomp = and / or / not / item 116 and = "&" filterlist 117 or = "|" filterlist 118 not = "!" filter 119 filterlist = 1*filter 120 item = simple / present / substring / extensible 121 simple = attr filtertype value 122 filtertype = equal / approx / greater / less 123 equal = "=" 124 approx = "~=" 125 greater = ">=" 126 less = "<=" 127 extensible = attr [":dn"] [":" matchingrule] ":=" value 128 / [":dn"] ":" matchingrule ":=" value 129 present = attr "=*" 130 substring = attr "=" [initial] any [final] 131 initial = value 132 any = "*" *(value "*") 133 final = value 134 attr = AttributeDescription from Section 4.1.5 of [1] 135 matchingrule = MatchingRuleId from Section 4.1.9 of [1] 136 value = AttributeValue from Section 4.1.6 of [1] with some characters 137 escaped (see below). 139 The attr and matchingrule constructs are as described in the 140 corresponding section of [1] given above. 142 The value construct is as described in the corresponding section of 143 [1] given above, except that if an AttributeValue contains any of the 144 following characters 146 Character ASCII value 147 --------------------------- 148 * 0x2a 149 ( 0x28 150 ) 0x29 151 \ 0x5c 152 NUL 0x00 154 the character must be encoded as the backslash '\' character (ASCII 155 0x5c) followed by the two hexadecimal digits representing the ASCII 156 value of the encoded character. The case of the two hexadecimal 157 digits is not significant. 159 This simple escaping mechanism eliminates filter-parsing ambiguities 160 and allows any filter that can be represented in LDAP to be 161 represented as a NUL-terminated string. Other characters besides the 162 ones listed above may be escaped using this mechanism, for example, 163 non-printing characters. 165 For example, the filter checking whether the "cn" attribute contained 166 a value with the character "*" anywhere in it would be represented as 167 "(cn=*\2a*)". 169 Note that although both the substring and present productions in the 170 grammar above can produce the "attr=*" construct, this construct is 171 used only to denote a presence filter. 173 5. Examples 175 This section gives a few examples of search filters written using 176 this notation. 178 (cn=Babs Jensen) 179 (!(cn=Tim Howes)) 180 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) 181 (o=univ*of*mich*) 183 The following examples illustrate the use of extensible matching. 185 (cn:1.2.3.4.5:=Fred Flintstone) 186 (cn:=Betty Rubble) 187 (sn:dn:2.4.6.8.10:=Barney Rubble) 188 (o:dn:=Ace Industry) 189 (:1.2.3:=Wilma Flintstone) 190 (:dn:2.4.6.8.10:=Dino) 192 The first example shows use of the matching rule "1.2.3.4.5". 194 The second example demonstrates use of a MatchingRuleAssertion form 195 without a matchingRule. 197 The third example illustrates the use of the ":dn" notation to 198 indicate that matching rule "2.4.6.8.10" should be used when making 199 comparisons, and that the attributes of an entry's distinguished name 200 should be considered part of the entry when evaluating the match. 202 The fourth example denotes an equality match, except that DN 203 components should be considered part of the entry when doing the 204 match. 206 The fifth example is a filter that should be applied to any attribute 207 supporting the matching rule given (since the attr has been omitted). 209 The sixth and final example is also a filter that should be applied 210 to any attribute supporting the matching rule given. Attributes 211 supporting the matching rule contained in the DN should also be 212 considered. 214 The following examples illustrate the use of the escaping mechanism. 216 (o=Parens R Us \28for all your parenthetical needs\29) 217 (cn=*\2A*) 218 (filename=C:\5cMyFile) 219 (bin=\00\00\00\04) 220 (sn=Lu\c4\8di\c4\87) 221 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69) 223 The first example shows the use of the escaping mechanism to 224 represent parenthesis characters. The second shows how to represent a 225 "*" in a value, preventing it from being interpreted as a substring 226 indicator. The third illustrates the escaping of the backslash 227 character. 229 The fourth example shows a filter searching for the four-byte value 230 0x00000004, illustrating the use of the escaping mechanism to 231 represent arbitrary data, including NUL characters. 233 The fifth example illustrates the use of the escaping mechanism to 234 represent various non-ASCII UTF-8 characters. 236 The sixth and final example demonstrates assertion of a BER encoded 237 value. 239 6. Security Considerations 241 This memo describes a string representation of LDAP search filters. 242 While the representation itself has no known security implications, 243 LDAP search filters do. They are interpreted by LDAP servers to 244 select entries from which data is retrieved. LDAP servers should 245 take care to protect the data they maintain from unauthorized access. 247 Please refer to the Security Considerations sections of RFC 2251 [1], 248 RFC 2829 [6], and RFC 2830 [7] for more information. 250 7. References 252 [1] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access 253 Protocol (v3)", RFC 2251, December 1997. 255 [2] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight 256 Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 257 2252, December 1997. 259 [3] Specification of ASN.1 encoding rules: Basic, Canonical, and 260 Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994. 262 [4] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 263 2279, January 1998. 265 [5] Crocker, D., "Standard for the Format of ARPA Internet Text 266 Messages", STD 11, RFC 822, August 1982. 268 [6] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, 269 "Authentication Methods for LDAP", RFC 2829, May 2000. 271 [7] Hodges, J., Morgan, R., Wahl, M., "Lightweight Directory Access 272 Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 273 2000. 275 8. Authors' Address 277 Tim Howes 278 Loudcloud, Inc. 279 599 N. Mathilda Ave. 280 Sunnyvale, CA 94086 281 USA 282 +1 408 744-7509 283 howes@loudcloud.com 285 Mark Smith 286 Netscape Communications Corp. 288 Mailstop USCA17-201 289 4170 Network Circle 290 Santa Clara, CA 95054 291 USA 292 +1 650 937-3477 293 mcs@netscape.com 295 9. Full Copyright Statement 297 Copyright (C) The Internet Society (2000). All Rights Reserved. 299 This document and translations of it may be copied and furnished to 300 others, and derivative works that comment on or otherwise explain it 301 or assist in its implementation may be prepared, copied, published 302 and distributed, in whole or in part, without restriction of any 303 kind, provided that the above copyright notice and this paragraph are 304 included on all such copies and derivative works. However, this 305 document itself may not be modified in any way, such as by removing 306 the copyright notice or references to the Internet Society or other 307 Internet organizations, except as needed for the purpose of 308 developing Internet standards in which case the procedures for 309 copyrights defined in the Internet Standards process must be 310 followed, or as required to translate it into languages other than 311 English. 313 The limited permissions granted above are perpetual and will not be 314 revoked by the Internet Society or its successors or assigns. 316 This document and the information contained herein is provided on an 317 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 318 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 319 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 320 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 321 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 323 10. Appendix A: Changes Since RFC 2254 325 10.1. Technical Changes 327 None. 329 10.2. Editorial Changes 331 IESG Note: removed note about lack of satisfactory mandatory 332 authentication mechanisms. 334 "Abstract" section: updated second paragraph to indicate that RFC 335 2254 is replaced by this document (instead of RFC 1960). 337 "Search Filter Definition" section: clarified the definition of 338 AttributeValue from RFC 2251 section 4.1.6 (special handling is 339 required for some characters). 341 "Examples" section: added three examples: (cn:=Betty Rubble), 342 (:1.2.3:=Wilma Flintstone), and 343 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69). 345 "Security Considerations" section: added references to RFC 2251, RFC 346 2829, and RFC 2830. 348 "References" section: added entries for RFC 2829 and RFC 2830 and 349 updated UTF-8 reference to RFC 2279. 351 Authors: added Mark Smith as an author and updated Tim's affiliation 352 and contact information. 354 "Appendix C: Loose Ends" section: added. 356 "Table of Contents" section: added. 358 11. Appendix B: Changes since draft-smith-ldapv3-filter-update-00.txt 360 Note that these changes are also listed in Appendix A, but are included 361 here for those who have already reviewed draft-smith-ldapv3-filter- 362 update-00.txt. 364 11.1. Technical Changes 366 "Search Filter Definition" section: removed the change made in -00 367 that changed the ABNF definition of 'filterlist' from 1*filter to 368 0*filter. RFC 2251 in fact DOES NOT allow an empty filter set. 369 Section 4.5.1 of 2251 says in part: "At least one filter element MUST 370 be present in an 372 11.2. Editorial Changes 374 "Examples" section: added three examples: (cn:=Betty Rubble), 375 (:1.2.3:=Wilma Flintstone), and 376 (1.3.6.1.4.1.1466.0;binary=\04\02\48\69). 378 "Security Considerations" section: Added references to RFC 2251 and 379 RFC 2830. 381 "References" section: added an entry for RFC 2830. 383 "Appendix C: Loose Ends" section: added. 385 "Table of Contents" section: added. 387 12. Appendix C: Loose Ends 389 The BNF needs to be updated to use the ABNF specified in RFC 2234, 390 and a reference to 2234 needs to be added. 392 This Internet Draft expires in May 2001. 394 1. Status of this Memo............................................1 395 2. Abstract.......................................................1 396 3. LDAP Search Filter Definition..................................2 397 4. String Search Filter Definition................................3 398 5. Examples.......................................................4 399 6. Security Considerations........................................6 400 7. References.....................................................6 401 8. Authors' Address...............................................6 402 9. Full Copyright Statement.......................................7 403 10. Appendix A: Changes Since RFC 2254.............................7 404 10.1. Technical Changes...........................................7 405 10.2. Editorial Changes...........................................7 406 11. Appendix B: Changes since draft-smith-ldapv3-filter-update-00.txt8 407 11.1. Technical Changes...........................................8 408 11.2. Editorial Changes...........................................8 409 12. Appendix C: Loose Ends.........................................9