1 2 3 4 5 6 7Network Working Group M. Smith, Ed. 8Request for Comments: 4515 Pearl Crescent, LLC 9Obsoletes: 2254 T. Howes 10Category: Standards Track Opsware, Inc. 11 June 2006 12 13 14 Lightweight Directory Access Protocol (LDAP): 15 String Representation of Search Filters 16 17Status of This Memo 18 19 This document specifies an Internet standards track protocol for the 20 Internet community, and requests discussion and suggestions for 21 improvements. Please refer to the current edition of the "Internet 22 Official Protocol Standards" (STD 1) for the standardization state 23 and status of this protocol. Distribution of this memo is unlimited. 24 25Copyright Notice 26 27 Copyright (C) The Internet Society (2006). 28 29Abstract 30 31 Lightweight Directory Access Protocol (LDAP) search filters are 32 transmitted in the LDAP protocol using a binary representation that 33 is appropriate for use on the network. This document defines a 34 human-readable string representation of LDAP search filters that is 35 appropriate for use in LDAP URLs (RFC 4516) and in other 36 applications. 37 38Table of Contents 39 40 1. Introduction ....................................................2 41 2. LDAP Search Filter Definition ...................................2 42 3. String Search Filter Definition .................................3 43 4. Examples ........................................................5 44 5. Security Considerations .........................................7 45 6. Normative References ............................................7 46 7. Informative References ..........................................8 47 8. Acknowledgements ................................................8 48 Appendix A: Changes Since RFC 2254 .................................9 49 A.1. Technical Changes ..........................................9 50 A.2. Editorial Changes ..........................................9 51 52 53 54 55 56 57 58Smith and Howes Standards Track [Page 1] 59 60RFC 4515 LDAP: String Representation of Search Filters June 2006 61 62 631. Introduction 64 65 The Lightweight Directory Access Protocol (LDAP) [RFC4510] defines a 66 network representation of a search filter transmitted to an LDAP 67 server. Some applications may find it useful to have a common way of 68 representing these search filters in a human-readable form; LDAP URLs 69 [RFC4516] are an example of one such application. This document 70 defines a human-readable string format for representing the full 71 range of possible LDAP version 3 search filters, including extended 72 match filters. 73 74 This document is a integral part of the LDAP technical specification 75 [RFC4510], which obsoletes the previously defined LDAP technical 76 specification, RFC 3377, in its entirety. 77 78 This document replaces RFC 2254. Changes to RFC 2254 are summarized 79 in Appendix A. 80 81 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 82 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 83 document are to be interpreted as described in BCP 14 [RFC2119]. 84 852. LDAP Search Filter Definition 86 87 An LDAP search filter is defined in Section 4.5.1 of [RFC4511] as 88 follows: 89 90 Filter ::= CHOICE { 91 and [0] SET SIZE (1..MAX) OF filter Filter, 92 or [1] SET SIZE (1..MAX) OF filter Filter, 93 not [2] Filter, 94 equalityMatch [3] AttributeValueAssertion, 95 substrings [4] SubstringFilter, 96 greaterOrEqual [5] AttributeValueAssertion, 97 lessOrEqual [6] AttributeValueAssertion, 98 present [7] AttributeDescription, 99 approxMatch [8] AttributeValueAssertion, 100 extensibleMatch [9] MatchingRuleAssertion } 101 102 SubstringFilter ::= SEQUENCE { 103 type AttributeDescription, 104 -- initial and final can occur at most once 105 substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { 106 initial [0] AssertionValue, 107 any [1] AssertionValue, 108 final [2] AssertionValue } } 109 110 111 112 113 114Smith and Howes Standards Track [Page 2] 115 116RFC 4515 LDAP: String Representation of Search Filters June 2006 117 118 119 AttributeValueAssertion ::= SEQUENCE { 120 attributeDesc AttributeDescription, 121 assertionValue AssertionValue } 122 123 MatchingRuleAssertion ::= SEQUENCE { 124 matchingRule [1] MatchingRuleId OPTIONAL, 125 type [2] AttributeDescription OPTIONAL, 126 matchValue [3] AssertionValue, 127 dnAttributes [4] BOOLEAN DEFAULT FALSE } 128 129 AttributeDescription ::= LDAPString 130 -- Constrained to <attributedescription> 131 -- [RFC4512] 132 133 AttributeValue ::= OCTET STRING 134 135 MatchingRuleId ::= LDAPString 136 137 AssertionValue ::= OCTET STRING 138 139 LDAPString ::= OCTET STRING -- UTF-8 encoded, 140 -- [Unicode] characters 141 142 The AttributeDescription, as defined in [RFC4511], is a string 143 representation of the attribute description that is discussed in 144 [RFC4512]. The AttributeValue and AssertionValue OCTET STRING have 145 the form defined in [RFC4517]. The Filter is encoded for 146 transmission over a network using the Basic Encoding Rules (BER) 147 defined in [X.690], with simplifications described in [RFC4511]. 148 1493. String Search Filter Definition 150 151 The string representation of an LDAP search filter is a string of 152 UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined 153 by the following grammar, following the ABNF notation defined in 154 [RFC4234]. The productions used that are not defined here are 155 defined in Section 1.4 (Common ABNF Productions) of [RFC4512] unless 156 otherwise noted. The filter format uses a prefix notation. 157 158 filter = LPAREN filtercomp RPAREN 159 filtercomp = and / or / not / item 160 and = AMPERSAND filterlist 161 or = VERTBAR filterlist 162 not = EXCLAMATION filter 163 filterlist = 1*filter 164 item = simple / present / substring / extensible 165 simple = attr filtertype assertionvalue 166 filtertype = equal / approx / greaterorequal / lessorequal 167 168 169 170Smith and Howes Standards Track [Page 3] 171 172RFC 4515 LDAP: String Representation of Search Filters June 2006 173 174 175 equal = EQUALS 176 approx = TILDE EQUALS 177 greaterorequal = RANGLE EQUALS 178 lessorequal = LANGLE EQUALS 179 extensible = ( attr [dnattrs] 180 [matchingrule] COLON EQUALS assertionvalue ) 181 / ( [dnattrs] 182 matchingrule COLON EQUALS assertionvalue ) 183 present = attr EQUALS ASTERISK 184 substring = attr EQUALS [initial] any [final] 185 initial = assertionvalue 186 any = ASTERISK *(assertionvalue ASTERISK) 187 final = assertionvalue 188 attr = attributedescription 189 ; The attributedescription rule is defined in 190 ; Section 2.5 of [RFC4512]. 191 dnattrs = COLON "dn" 192 matchingrule = COLON oid 193 assertionvalue = valueencoding 194 ; The <valueencoding> rule is used to encode an <AssertionValue> 195 ; from Section 4.1.6 of [RFC4511]. 196 valueencoding = 0*(normal / escaped) 197 normal = UTF1SUBSET / UTFMB 198 escaped = ESC HEX HEX 199 UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F 200 ; UTF1SUBSET excludes 0x00 (NUL), LPAREN, 201 ; RPAREN, ASTERISK, and ESC. 202 EXCLAMATION = %x21 ; exclamation mark ("!") 203 AMPERSAND = %x26 ; ampersand (or AND symbol) ("&") 204 ASTERISK = %x2A ; asterisk ("*") 205 COLON = %x3A ; colon (":") 206 VERTBAR = %x7C ; vertical bar (or pipe) ("|") 207 TILDE = %x7E ; tilde ("~") 208 209 Note that although both the <substring> and <present> productions in 210 the grammar above can produce the "attr=*" construct, this construct 211 is used only to denote a presence filter. 212 213 The <valueencoding> rule ensures that the entire filter string is a 214 valid UTF-8 string and provides that the octets that represent the 215 ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII 216 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a 217 backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits 218 representing the value of the encoded octet. 219 220 221 222 223 224 225 226Smith and Howes Standards Track [Page 4] 227 228RFC 4515 LDAP: String Representation of Search Filters June 2006 229 230 231 This simple escaping mechanism eliminates filter-parsing ambiguities 232 and allows any filter that can be represented in LDAP to be 233 represented as a NUL-terminated string. Other octets that are part 234 of the <normal> set may be escaped using this mechanism, for example, 235 non-printing ASCII characters. 236 237 For AssertionValues that contain UTF-8 character data, each octet of 238 the character to be escaped is replaced by a backslash and two hex 239 digits, which form a single octet in the code of the character. For 240 example, the filter checking whether the "cn" attribute contained a 241 value with the character "*" anywhere in it would be represented as 242 "(cn=*\2a*)". 243 244 As indicated by the <valueencoding> rule, implementations MUST escape 245 all octets greater than 0x7F that are not part of a valid UTF-8 246 encoding sequence when they generate a string representation of a 247 search filter. Implementations SHOULD accept as input strings that 248 are not valid UTF-8 strings. This is necessary because RFC 2254 did 249 not clearly define the term "string representation" (and in 250 particular did not mention that the string representation of an LDAP 251 search filter is a string of UTF-8-encoded Unicode characters). 252 2534. Examples 254 255 This section gives a few examples of search filters written using 256 this notation. 257 258 (cn=Babs Jensen) 259 (!(cn=Tim Howes)) 260 (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) 261 (o=univ*of*mich*) 262 (seeAlso=) 263 264 The following examples illustrate the use of extensible matching. 265 266 (cn:caseExactMatch:=Fred Flintstone) 267 (cn:=Betty Rubble) 268 (sn:dn:2.4.6.8.10:=Barney Rubble) 269 (o:dn:=Ace Industry) 270 (:1.2.3:=Wilma Flintstone) 271 (:DN:2.4.6.8.10:=Dino) 272 273 The first example shows use of the matching rule "caseExactMatch." 274 275 The second example demonstrates use of a MatchingRuleAssertion form 276 without a matchingRule. 277 278 279 280 281 282Smith and Howes Standards Track [Page 5] 283 284RFC 4515 LDAP: String Representation of Search Filters June 2006 285 286 287 The third example illustrates the use of the ":oid" notation to 288 indicate that the matching rule identified by the OID "2.4.6.8.10" 289 should be used when making comparisons, and that the attributes of an 290 entry's distinguished name should be considered part of the entry 291 when evaluating the match (indicated by the use of ":dn"). 292 293 The fourth example denotes an equality match, except that DN 294 components should be considered part of the entry when doing the 295 match. 296 297 The fifth example is a filter that should be applied to any attribute 298 supporting the matching rule given (since the <attr> has been 299 omitted). 300 301 The sixth and final example is also a filter that should be applied 302 to any attribute supporting the matching rule given. Attributes 303 supporting the matching rule contained in the DN should also be 304 considered. 305 306 The following examples illustrate the use of the escaping mechanism. 307 308 (o=Parens R Us \28for all your parenthetical needs\29) 309 (cn=*\2A*) 310 (filename=C:\5cMyFile) 311 (bin=\00\00\00\04) 312 (sn=Lu\c4\8di\c4\87) 313 (1.3.6.1.4.1.1466.0=\04\02\48\69) 314 315 The first example shows the use of the escaping mechanism to 316 represent parenthesis characters. The second shows how to represent 317 a "*" in an assertion value, preventing it from being interpreted as 318 a substring indicator. The third illustrates the escaping of the 319 backslash character. 320 321 The fourth example shows a filter searching for the four-octet value 322 00 00 00 04 (hex), illustrating the use of the escaping mechanism to 323 represent arbitrary data, including NUL characters. 324 325 The fifth example illustrates the use of the escaping mechanism to 326 represent various non-ASCII UTF-8 characters. Specifically, there 327 are 5 characters in the <assertionvalue> portion of this example: 328 LATIN CAPITAL LETTER L (U+004C), LATIN SMALL LETTER U (U+0075), LATIN 329 SMALL LETTER C WITH CARON (U+010D), LATIN SMALL LETTER I (U+0069), 330 and LATIN SMALL LETTER C WITH ACUTE (U+0107). 331 332 The sixth and final example demonstrates assertion of a BER-encoded 333 value. 334 335 336 337 338Smith and Howes Standards Track [Page 6] 339 340RFC 4515 LDAP: String Representation of Search Filters June 2006 341 342 3435. Security Considerations 344 345 This memo describes a string representation of LDAP search filters. 346 While the representation itself has no known security implications, 347 LDAP search filters do. They are interpreted by LDAP servers to 348 select entries from which data is retrieved. LDAP servers should 349 take care to protect the data they maintain from unauthorized access. 350 351 Please refer to the Security Considerations sections of [RFC4511] and 352 [RFC4513] for more information. 353 3546. Normative References 355 356 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 357 Requirement Levels", BCP 14, RFC 2119, March 1997. 358 359 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 360 10646", STD 63, RFC 3629, November 2003. 361 362 [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 363 Specifications: ABNF", RFC 4234, October 2005. 364 365 [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 366 (LDAP): Technical Specification Road Map", RFC 4510, June 367 2006. 368 369 [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access 370 Protocol (LDAP): The Protocol", RFC 4511, June 2006. 371 372 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 373 (LDAP): Directory Information Models", RFC 4512, June 374 2006. 375 376 [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol 377 (LDAP): Authentication Methods and Security Mechanisms", 378 RFC 4513, June 2006. 379 380 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 381 (LDAP): Syntaxes and Matching Rules", RFC 4517, June 382 2006. 383 384 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 385 3.2.0" is defined by "The Unicode Standard, Version 3.0" 386 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), 387 as amended by the "Unicode Standard Annex #27: Unicode 388 3.1" (http://www.unicode.org/reports/tr27/) and by the 389 "Unicode Standard Annex #28: Unicode 3.2." 390 391 392 393 394Smith and Howes Standards Track [Page 7] 395 396RFC 4515 LDAP: String Representation of Search Filters June 2006 397 398 3997. Informative References 400 401 [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory 402 Access Protocol (LDAP): Uniform Resource Locator", RFC 403 4516, June 2006. 404 405 [X.690] Specification of ASN.1 encoding rules: Basic, Canonical, 406 and Distinguished Encoding Rules, ITU-T Recommendation 407 X.690, 1994. 408 4098. Acknowledgements 410 411 This document replaces RFC 2254 by Tim Howes. RFC 2254 was a product 412 of the IETF ASID Working Group. 413 414 Changes included in this revised specification are based upon 415 discussions among the authors, discussions within the LDAP (v3) 416 Revision Working Group (ldapbis), and discussions within other IETF 417 Working Groups. The contributions of individuals in these working 418 groups is gratefully acknowledged. 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450Smith and Howes Standards Track [Page 8] 451 452RFC 4515 LDAP: String Representation of Search Filters June 2006 453 454 455Appendix A: Changes Since RFC 2254 456 457A.1. Technical Changes 458 459 Replaced [ISO 10646] reference with [Unicode]. 460 461 The following technical changes were made to the contents of the 462 "String Search Filter Definition" section: 463 464 Added statement that the string representation is a string of UTF-8- 465 encoded Unicode characters. 466 467 Revised all of the ABNF to use common productions from [RFC4512]. 468 469 Replaced the "value" rule with a new "assertionvalue" rule within the 470 "simple", "extensible", and "substring" ("initial", "any", and 471 "final") rules. This matches a change made in [RFC4517]. 472 473 Added "(" and ")" around the components of the <extensible> 474 subproductions for clarity. 475 476 Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more 477 precisely reference productions from the [RFC4512] and [RFC4511] 478 documents. 479 480 "String Search Filter Definition" section: replaced "greater" and 481 "less" with "greaterorequal" and "lessorequal" to avoid confusion. 482 483 Introduced the "valueencoding" and associated "normal" and "escaped" 484 rules to reduce the dependence on descriptive text. The "normal" 485 production restricts filter strings to valid UTF-8 sequences. 486 487 Added a statement about expected behavior in light of RFC 2254's lack 488 of a clear definition of "string representation." 489 490A.2. Editorial Changes 491 492 Changed document title to include "LDAP:" prefix. 493 494 IESG Note: removed note about lack of satisfactory mandatory 495 authentication mechanisms. 496 497 Header and "Authors' Addresses" sections: added Mark Smith as the 498 document editor and updated affiliation and contact information. 499 500 "Table of Contents" and "Intellectual Property" sections: added. 501 502 Copyright: updated per latest IETF guidelines. 503 504 505 506Smith and Howes Standards Track [Page 9] 507 508RFC 4515 LDAP: String Representation of Search Filters June 2006 509 510 511 "Abstract" section: separated from introductory material. 512 513 "Introduction" section: new section; separated from the Abstract. 514 Updated second paragraph to indicate that RFC 2254 is replaced by 515 this document (instead of RFC 1960). Added reference to the 516 [RFC4510] document. 517 518 "LDAP Search Filter Definition" section: made corrections to the LDAP 519 search filter ABNF so it matches that used in [RFC4511]. 520 521 Clarified the definition of 'value' (now 'assertionvalue') to take 522 into account the fact that it is not precisely an AttributeAssertion 523 from [RFC4511] Section 4.1.6 (special handling is required for some 524 characters). Added a note that each octet of a character to be 525 escaped is replaced by a backslash and two hex digits, which 526 represent a single octet. 527 528 "Examples" section: added four additional examples: (seeAlso=), 529 (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and 530 (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a 531 value" with "an assertion value". Corrected the description of this 532 example: (sn:dn:2.4.6.8.10:=Barney Rubble). Replaced the numeric OID 533 in the first extensible match example with "caseExactMatch" to 534 demonstrate use of the descriptive form. Used "DN" (uppercase) in 535 the last extensible match example to remind the reader to treat the 536 <dnattrs> production as case insensitive. Reworded the description 537 of the fourth escaping mechanism example to avoid making assumptions 538 about byte order. Added text to the fifth escaping mechanism example 539 to spell out what the non-ASCII characters are in Unicode terms. 540 541 "Security Considerations" section: added references to [RFC4511] and 542 [RFC4513]. 543 544 "Normative References" section: renamed from "References" per new RFC 545 guidelines. Changed from [1] style to [RFC4511] style throughout the 546 document. Added entries for [Unicode], [RFC2119], [RFC4513], 547 [RFC4512], and [RFC4510] and updated the UTF-8 reference. Replaced 548 RFC 822 reference with a reference to RFC 4234. 549 550 "Informative References" section: (new section) moved [X.690] to this 551 section. Added a reference to [RFC4516]. 552 553 "Acknowledgements" section: added. 554 555 "Appendix A: Changes Since RFC 2254" section: added. 556 557 Surrounded the names of all ABNF productions with "<" and ">" where 558 they are used in descriptive text. 559 560 561 562Smith and Howes Standards Track [Page 10] 563 564RFC 4515 LDAP: String Representation of Search Filters June 2006 565 566 567 Replaced all occurrences of "LDAPv3" with "LDAP." 568 569Authors' Addresses 570 571 Mark Smith, Editor 572 Pearl Crescent, LLC 573 447 Marlpool Dr. 574 Saline, MI 48176 575 USA 576 577 Phone: +1 734 944-2856 578 EMail: mcs@pearlcrescent.com 579 580 581 Tim Howes 582 Opsware, Inc. 583 599 N. Mathilda Ave. 584 Sunnyvale, CA 94085 585 USA 586 587 Phone: +1 408 744-7509 588 EMail: howes@opsware.com 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618Smith and Howes Standards Track [Page 11] 619 620RFC 4515 LDAP: String Representation of Search Filters June 2006 621 622 623Full Copyright Statement 624 625 Copyright (C) The Internet Society (2006). 626 627 This document is subject to the rights, licenses and restrictions 628 contained in BCP 78, and except as set forth therein, the authors 629 retain all their rights. 630 631 This document and the information contained herein are provided on an 632 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 633 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 634 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 635 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 636 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 637 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 638 639Intellectual Property 640 641 The IETF takes no position regarding the validity or scope of any 642 Intellectual Property Rights or other rights that might be claimed to 643 pertain to the implementation or use of the technology described in 644 this document or the extent to which any license under such rights 645 might or might not be available; nor does it represent that it has 646 made any independent effort to identify any such rights. Information 647 on the procedures with respect to rights in RFC documents can be 648 found in BCP 78 and BCP 79. 649 650 Copies of IPR disclosures made to the IETF Secretariat and any 651 assurances of licenses to be made available, or the result of an 652 attempt made to obtain a general license or permission for the use of 653 such proprietary rights by implementers or users of this 654 specification can be obtained from the IETF on-line IPR repository at 655 http://www.ietf.org/ipr. 656 657 The IETF invites any interested party to bring to its attention any 658 copyrights, patents or patent applications, or other proprietary 659 rights that may cover technology that may be required to implement 660 this standard. Please address the information to the IETF at 661 ietf-ipr@ietf.org. 662 663Acknowledgement 664 665 Funding for the RFC Editor function is provided by the IETF 666 Administrative Support Activity (IASA). 667 668 669 670 671 672 673 674Smith and Howes Standards Track [Page 12] 675 676