idnits 2.17.1 draft-ietf-ldapbis-filter-04.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 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.) ** There are 3 instances of too long lines in the document, the longest one being 8 characters in excess of 72. == 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. -- The draft header indicates that this document obsoletes RFC2254, but the abstract doesn't seem to mention this, which it should. 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 the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (28 February 2003) is 7728 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 111 -- Looks like a reference, but probably isn't: '1' on line 477 -- Looks like a reference, but probably isn't: '2' on line 121 -- Looks like a reference, but probably isn't: '3' on line 122 -- Looks like a reference, but probably isn't: '4' on line 123 -- Looks like a reference, but probably isn't: '5' on line 100 -- Looks like a reference, but probably isn't: '6' on line 101 -- Looks like a reference, but probably isn't: '7' on line 102 -- Looks like a reference, but probably isn't: '8' on line 103 -- Looks like a reference, but probably isn't: '9' on line 104 -- No information found for draft-ietf-ldapbis-authmeth-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'AuthMeth' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO10646' -- No information found for draft-ietf-ldapbis-models-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Models' -- No information found for draft-ietf-ldapbis-protocol-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Protocol' ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) -- No information found for draft-ietf-ldapbis-roadmap-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Roadmap' -- No information found for draft-ietf-ldapbis-syntaxes-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'Syntaxes' Summary: 9 errors (**), 0 flaws (~~), 4 warnings (==), 24 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: 28 August 2003 Opsware, Inc. 6 28 February 2003 8 LDAP: String Representation of Search Filters 9 11 1. Status of this Memo 13 This document is an Internet-Draft and is subject to all provisions 14 of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet- Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/1id-abstracts.html 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html 32 Discussion of this document should take place on the LDAP (v3) 33 Revision (ldapbis) Working Group mailing list . 36 Copyright (C) The Internet Society (2003). All Rights Reserved. 38 2. Abstract 40 LDAP search filters are transmitted in the LDAP protocol using a 41 binary representation that is appropriate for use on the network. 42 This document defines a human-readable string representation of LDAP 43 search filters that is appropriate for use in LDAP URLs and in other 44 applications. 46 3. Table of Contents 48 1. Status of this Memo............................................1 49 2. Abstract.......................................................1 50 3. Table of Contents..............................................2 51 4. Introduction...................................................2 52 5. LDAP Search Filter Definition..................................2 53 6. String Search Filter Definition................................4 54 7. Examples.......................................................5 55 8. Security Considerations........................................7 56 9. Normative References...........................................7 57 10. Informative References.........................................8 58 11. Acknowledgments................................................8 59 12. Authors' Address...............................................8 60 13. Full Copyright Statement.......................................9 61 14. Appendix A: Changes Since RFC 2254.............................9 62 14.1. Technical Changes...........................................9 63 14.2. Editorial Changes...........................................10 64 15. Appendix B: Changes Since Previous Document Revision...........11 65 15.1. Technical Changes...........................................11 66 15.2. Editorial Changes...........................................11 68 4. Introduction 70 The Lightweight Directory Access Protocol (LDAP) [Protocol] defines a 71 network representation of a search filter transmitted to an LDAP 72 server. Some applications may find it useful to have a common way of 73 representing these search filters in a human-readable form; LDAP URLs 74 are an example of one such application. This document defines a 75 human-readable string format for representing the full range of 76 possible LDAP version 3 search filters, including extended match 77 filters. 79 This document is an integral part of the LDAP Technical 80 Specification [Roadmap]. 82 This document replaces RFC 2254. Changes to RFC 2254 are summarized 83 in Appendix A. 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in BCP 14 [RFC2119]. 89 5. LDAP Search Filter Definition 91 An LDAPv3 search filter is defined in Section 4.5.1 of [Protocol] as 92 follows: 94 Filter ::= CHOICE { 95 and [0] SET SIZE (1..MAX) OF Filter, 96 or [1] SET SIZE (1..MAX) OF Filter, 97 not [2] Filter, 98 equalityMatch [3] AttributeValueAssertion, 99 substrings [4] SubstringFilter, 100 greaterOrEqual [5] AttributeValueAssertion, 101 lessOrEqual [6] AttributeValueAssertion, 102 present [7] AttributeDescription, 103 approxMatch [8] AttributeValueAssertion, 104 extensibleMatch [9] MatchingRuleAssertion } 106 SubstringFilter ::= SEQUENCE { 107 type AttributeDescription, 108 -- at least one must be present, 109 -- initial and final can occur at most once 110 substrings SEQUENCE OF CHOICE { 111 initial [0] AssertionValue, 112 any [1] AssertionValue, 113 final [2] AssertionValue } } 115 AttributeValueAssertion ::= SEQUENCE { 116 attributeDesc AttributeDescription, 117 assertionValue AssertionValue } 119 MatchingRuleAssertion ::= SEQUENCE { 120 matchingRule [1] MatchingRuleId OPTIONAL, 121 type [2] AttributeDescription OPTIONAL, 122 matchValue [3] AssertionValue, 123 dnAttributes [4] BOOLEAN DEFAULT FALSE } 125 AttributeDescription ::= LDAPString 126 -- Constrained to attributedescription 127 -- [Models] 129 AttributeValue ::= OCTET STRING 131 MatchingRuleId ::= LDAPString 133 AssertionValue ::= OCTET STRING 135 LDAPString ::= OCTET STRING -- UTF-8 encoded, 136 -- ISO 10646 characters 138 where the LDAPString above is limited to the UTF-8 encoding [RFC2279] 139 of the ISO 10646 character set [ISO10646]. The AttributeDescription 140 is a string representation of the attribute description and is 141 defined in [Protocol]. The AttributeValue and AssertionValue OCTET 142 STRING have the form defined in [Syntaxes]. The Filter is encoded 143 for transmission over a network using the Basic Encoding Rules 144 defined in [ASN.1], with simplifications described in [Protocol]. 146 6. String Search Filter Definition 148 The string representation of an LDAP search filter is a string of 149 UTF-8 encoded ISO 10646-1 characters that is defined by the following 150 grammar, following the ABNF notation defined in [RFC2234]. The 151 productions used that are not defined here are defined in section 1.3 152 (Common ABNF Productions) of [Models] unless otherwise noted. The 153 filter format uses a prefix notation. 155 filter = LPAREN filtercomp RPAREN 156 filtercomp = and / or / not / item 157 and = AMPERSAND filterlist 158 or = VERTBAR filterlist 159 not = EXCLAMATION filter 160 filterlist = 1*filter 161 item = simple / present / substring / extensible 162 simple = attr filtertype assertionvalue 163 filtertype = equal / approx / greater / less 164 equal = EQUALS 165 approx = TILDE EQUALS 166 greater = RANGLE EQUALS 167 less = LANGLE EQUALS 168 extensible = attr [dnattrs] [matchingrule] COLON EQUALS assertionvalue 169 / [dnattrs] matchingrule COLON EQUALS assertionvalue 170 / COLON EQUALS assertionvalue 171 present = attr EQUALS ASTERIX 172 substring = attr EQUALS [initial] any [final] 173 initial = assertionvalue 174 any = ASTERIX *(assertionvalue ASTERIX) 175 final = assertionvalue 176 attr = attributedescription 177 ; The attributedescription rule is defined in 178 ; Section 2.5 of [Models]. 179 dnattrs = COLON "dn" 180 matchingrule = COLON oid 181 assertionvalue = valueencoding 182 ; The rule is used to encode an 183 ; from Section 4.1.6 of [Protocol]. 184 valueencoding = 0*(normal / escaped) 185 normal = UTF1SUBSET / UTFMB 186 escaped = ESC HEX HEX 187 UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F 188 ; UTF1SUBSET excludes 0x00 (NUL), LPAREN, 189 ; RPAREN, ASTERIX, and ESC. 191 EXCLAMATION = %x21 ; exclamation mark ("!") 192 AMPERSAND = %x26 ; ampersand (or AND symbol) ("&") 193 ASTERIX = %x2A ; asterix ("*") 194 COLON = %x3A ; colon (":") 195 VERTBAR = %x7C ; vertical bar (or pipe) ("|") 196 TILDE = %x7E ; tilde ("~") 198 Note that although both the and productions in 199 the grammar above can produce the "attr=*" construct, this construct 200 is used only to denote a presence filter. 202 The rule ensures that the entire filter string is a 203 valid UTF-8 string and provides that the octets that represent the 204 ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII 205 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a 206 backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits 207 representing the value of the encoded octet. 209 This simple escaping mechanism eliminates filter-parsing ambiguities 210 and allows any filter that can be represented in LDAP to be 211 represented as a NUL-terminated string. Other octets that are part of 212 the set may be escaped using this mechanism, for example, 213 non-printing ASCII characters. 215 For AssertionValues that contain UTF-8 character data, each octet of 216 the character to be escaped is replaced by a backslash and two hex 217 digits, which form a single octet in the code of the character. 219 For example, the filter checking whether the "cn" attribute contained 220 a value with the character "*" anywhere in it would be represented as 221 "(cn=*\2a*)". 223 As indicated by the valueencoding rule, implementations MUST escape 224 all octets greater than 0x7F that are not part of a valid UTF-8 225 encoding sequence when they generate a string representation of a 226 search filter. Since RFC 2254 does not clearly define the term 227 "string representation" (and in particular does mention that the 228 string representation of an LDAP search filter is a string of UTF-8 229 encoded ISO 10646-1 characters) implementations SHOULD accept as 230 input strings that include invalid UTF-8 octet sequences. 232 7. Examples 234 This section gives a few examples of search filters written using 235 this notation. 237 (cn=Babs Jensen) 238 (!(cn=Tim Howes)) 239 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) 240 (o=univ*of*mich*) 241 (seeAlso=) 243 The following examples illustrate the use of extensible matching. 245 (cn:1.2.3.4.5:=Fred Flintstone) 246 (cn:=Betty Rubble) 247 (sn:dn:2.4.6.8.10:=Barney Rubble) 248 (o:dn:=Ace Industry) 249 (:1.2.3:=Wilma Flintstone) 250 (:dn:2.4.6.8.10:=Dino) 251 (:=Fred Flintstone) 253 The first example shows use of the matching rule "1.2.3.4.5". 255 The second example demonstrates use of a MatchingRuleAssertion form 256 without a matchingRule. 258 The third example illustrates the use of the ":dn" notation to 259 indicate that matching rule "2.4.6.8.10" should be used when making 260 comparisons, and that the attributes of an entry's distinguished name 261 should be considered part of the entry when evaluating the match. 263 The fourth example denotes an equality match, except that DN 264 components should be considered part of the entry when doing the 265 match. 267 The fifth example is a filter that should be applied to any attribute 268 supporting the matching rule given (since the attr has been omitted). 270 The sixth example is also a filter that should be applied to any 271 attribute supporting the matching rule given. Attributes supporting 272 the matching rule contained in the DN should also be considered. 274 The seventh and final example is a filter that should be applied to 275 any attribute (since both the attr and matching rule have been 276 omitted). 278 The following examples illustrate the use of the escaping mechanism. 280 (o=Parens R Us \28for all your parenthetical needs\29) 281 (cn=*\2A*) 282 (filename=C:\5cMyFile) 283 (bin=\00\00\00\04) 284 (sn=Lu\c4\8di\c4\87) 285 (1.3.6.1.4.1.1466.0=\04\02\48\69) 287 The first example shows the use of the escaping mechanism to 288 represent parenthesis characters. The second shows how to represent a 289 "*" in an assertion value, preventing it from being interpreted as a 290 substring indicator. The third illustrates the escaping of the 291 backslash character. 293 The fourth example shows a filter searching for the four-byte value 294 0x00000004, illustrating the use of the escaping mechanism to 295 represent arbitrary data, including NUL characters. 297 The fifth example illustrates the use of the escaping mechanism to 298 represent various non-ASCII UTF-8 characters. 300 The sixth and final example demonstrates assertion of a BER encoded 301 value. 303 8. Security Considerations 305 This memo describes a string representation of LDAP search filters. 306 While the representation itself has no known security implications, 307 LDAP search filters do. They are interpreted by LDAP servers to 308 select entries from which data is retrieved. LDAP servers should 309 take care to protect the data they maintain from unauthorized access. 311 Please refer to the Security Considerations sections of [Protocol] 312 and [AuthMeth] for more information. 314 9. Normative References 316 [ASN.1] Specification of ASN.1 encoding rules: Basic, Canonical, and 317 Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994. 319 [AuthMeth] Harrison, R. (editor), "LDAP: Authentication Methods and 320 Connection Level Security Mechanisms", draft-ietf-ldapbis-authmeth- 321 xx.txt, a work in progress. 323 [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - 324 Architecture and Basic Multilingual Plane, ISO/IEC 10646-1, 1993. 326 [Models] Zeilenga, K. (editor), "LDAP: Directory Information Models", 327 draft-ietf-ldapbis-models-xx.txt, a work in progress. 329 [Protocol] Sermersheim, J. (editor), "LDAP: The Protocol", draft- 330 ietf-ldapbis-protocol-xx.txt, a work in progress. 332 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14 (also RFC 2119), March 1997. 335 [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax 336 Specifications: ABNF", RFC 2234, November 1997. 338 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 339 RFC 2279, January 1998. 341 [Roadmap] Zeilenga, K. (editor), "LDAP: Technical Specification Road 342 Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in progress. 344 [Syntaxes] Dally, K. (editor), "LDAP: Syntaxes", draft-ietf-ldapbis- 345 syntaxes-xx.txt, a work in progress. 347 10. Informative References 349 None. 351 11. Acknowledgments 353 This document replaces RFC 2254 by Tim Howes. Changes included in 354 this revised specification are based upon discussions among the 355 authors, discussions within the LDAP (v3) Revision Working Group 356 (ldapbis), and discussions within other IETF Working Groups. The 357 contributions of individuals in these working groups is gratefully 358 acknowledged. 360 12. Authors' Address 362 Mark Smith, Editor 363 Netscape Communications Corp. 364 360 W. Caribbean Drive 365 Sunnyvale, CA 94089 366 USA 367 +1 650 937-3477 368 mcs@netscape.com 370 Tim Howes 371 Opsware, Inc. 372 599 N. Mathilda Ave. 373 Sunnyvale, CA 94085 374 USA 375 +1 408 744-7509 376 howes@opsware.com 378 13. Full Copyright Statement 380 Copyright (C) The Internet Society (2003). All Rights Reserved. 382 This document and translations of it may be copied and furnished to 383 others, and derivative works that comment on or otherwise explain it 384 or assist in its implementation may be prepared, copied, published 385 and distributed, in whole or in part, without restriction of any 386 kind, provided that the above copyright notice and this paragraph are 387 included on all such copies and derivative works. However, this 388 document itself may not be modified in any way, such as by removing 389 the copyright notice or references to the Internet Society or other 390 Internet organizations, except as needed for the purpose of 391 developing Internet standards in which case the procedures for 392 copyrights defined in the Internet Standards process must be 393 followed, or as required to translate it into languages other than 394 English. 396 The limited permissions granted above are perpetual and will not be 397 revoked by the Internet Society or its successors or assigns. 399 This document and the information contained herein is provided on an 400 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 401 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 402 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 403 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 404 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 406 14. Appendix A: Changes Since RFC 2254 408 14.1. Technical Changes 410 The following technical changes were made to the contents of the 411 "String Search Filter Definition" section: 413 Added statement that the string representation is a string of UTF-8 414 encoded ISO 10646-1 characters. 416 Revised all of the ABNF to use common productions from [Models]. 418 Replaced the "value" rule with a new "assertionvalue" rule within the 419 "simple", "extensible", and "substring" ("initial", "any", and 420 "final") rules. This matches a change made in [Syntaxes]. 422 Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more 423 precisely reference productions from the [Models] and [Protocol] 424 documents. 426 Introduced the "valueencoding" and associated "normal" and "escaped" 427 rules to reduce the dependence on descriptive text. The "normal" 428 production restricts filter strings to valid UTF-8 sequences. 430 Added a third option to the "extensible" production to allow creation 431 of a MatchingRuleAssertion that only has a matchValue. 433 Added a statement about expected behavior in light of RFC 2254's lack 434 of a clear definition of "string representation." 436 14.2. Editorial Changes 438 Changed document title to include "LDAP:" prefix. 440 IESG Note: removed note about lack of satisfactory mandatory 441 authentication mechanisms. 443 Header and "Authors' Addresses" sections: added Mark Smith as the 444 document editor and updated affiliation and contact information. 446 "Table of Contents" section: added. 448 Copyright: updated the year. 450 "Abstract" section: separated from introductory material. 452 "Introduction" section: new section; separated from the Abstract. 453 Updated second paragraph to indicate that RFC 2254 is replaced by 454 this document (instead of RFC 1960). Added reference to the [Roadmap] 455 document. 457 "LDAP Search Filter Definition" section: made corrections to the 458 LDAPv3 search filter ABNF so it matches that used in [Protocol]. 460 Clarified the definition of 'value' (now 'assertionvalue') to take 461 into account the fact that it is not precisely an AttributeAssertion 462 from [Protocol] section 4.1.6 (special handling is required for some 463 characters). Added a note that each octet of a character to be 464 escaped is replaced by a backslash and two hex digits, which 465 represent a single octet. 467 "Examples" section: added five additional examples: (seeAlso=), 468 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), (:=Fred Flintstone), 469 and (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a 470 value" with "an assertion value". 472 "Security Considerations" section: added references to [Protocol] and 474 [AuthMeth]. 476 "Normative References" section: renamed from "References" per new RFC 477 guidelines. Changed from [1] style to [Protocol] style throughout the 478 document. Added entries for [ISO10646], [RFC2119], [AuthMeth], 479 [Models], and [Roadmap] and updated UTF-8 reference to RFC 2279. 480 Replaced RFC 822 reference with a reference to RFC 2234. 482 "Informative References" section: added for clarity. 484 "Acknowledgments" section: added. 486 "Appendix A: Changes Since RFC 2254" section: added. 488 "Appendix B: Changes Since Previous Document Revision" section: 489 added. 491 15. Appendix B: Changes Since Previous Document Revision 493 This appendix lists all changes relative to the last published 494 revision, draft-ietf-ldapbis-filter-03.txt. Note that when 495 appropriate these changes are also included in Appendix A, but are 496 also included here for the benefit of the people who have already 497 reviewed draft-ietf-ldapbis-filter-03.txt. This section will be 498 removed before this document is published as an RFC. 500 15.1. Technical Changes 502 "String Search Filter Definition" section: Added statement that the 503 string representation is a string of UTF-8 encoded ISO 10646-1 504 characters and statement about expected behavior in light of RFC 505 2254's lack of a clear definition of "string representation." 507 "String Search Filter Definition" section: Revised all of the ABNF to 508 use common productions from [Models]. Revised the "normal" 509 production to restrict filter strings to valid UTF-8 sequences. 511 15.2. Editorial Changes 513 "Status of this Memo" section: updated boilerplate to match current 514 I-D guidelines. 516 "Examples" section: removed ;binary from an example. 518 "LDAP Search Filter Definition " section: updated section references 519 to match current LDAPBis drafts. Made minor changes to the ASN.1 so 520 it exactly matches that used in the Protocol document (added 521 comments). 523 "Normative References" section: added references to [ISO10646], 524 [RFC2119] and [Models]. 526 "Informative References" section: added for clarity. 528 Updated copyright year to 2003. 530 This Internet Draft expires on 28 August 2003.