1 2 3 4 5 6 7Network Working Group S. Legg 8Request for Comments: 3687 Adacel Technologies 9Category: Standards Track February 2004 10 11 12 Lightweight Directory Access Protocol (LDAP) 13 and X.500 Component Matching Rules 14 15Status of this Memo 16 17 This document specifies an Internet standards track protocol for the 18 Internet community, and requests discussion and suggestions for 19 improvements. Please refer to the current edition of the "Internet 20 Official Protocol Standards" (STD 1) for the standardization state 21 and status of this protocol. Distribution of this memo is unlimited. 22 23Copyright Notice 24 25 Copyright (C) The Internet Society (2004). All Rights Reserved. 26 27Abstract 28 29 The syntaxes of attributes in a Lightweight Directory Access Protocol 30 (LDAP) or X.500 directory range from simple data types, such as text 31 string, integer, or boolean, to complex structured data types, such 32 as the syntaxes of the directory schema operational attributes. 33 Matching rules defined for the complex syntaxes usually only provide 34 the most immediately useful matching capability. This document 35 defines generic matching rules that can match any user selected 36 component parts in an attribute value of any arbitrarily complex 37 attribute syntax. 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58Legg Standards Track [Page 1] 59 60RFC 3687 LDAP and X.500 Component Matching Rules February 2004 61 62 63Table of Contents 64 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. ComponentAssertion . . . . . . . . . . . . . . . . . . . . . . 5 68 3.1. Component Reference. . . . . . . . . . . . . . . . . . . 6 69 3.1.1. Component Type Substitutions . . . . . . . . . . 7 70 3.1.2. Referencing SET, SEQUENCE and CHOICE Components. 8 71 3.1.3. Referencing SET OF and SEQUENCE OF Components. . 9 72 3.1.4. Referencing Components of Parameterized Types. . 10 73 3.1.5. Component Referencing Example. . . . . . . . . . 10 74 3.1.6. Referencing Components of Open Types . . . . . . 12 75 3.1.6.1. Open Type Referencing Example . . . . . 12 76 3.1.7. Referencing Contained Types. . . . . . . . . . . 14 77 3.1.7.1. Contained Type Referencing Example. . . 14 78 3.2. Matching of Components . . . . . . . . . . . . . . . . . 15 79 3.2.1. Applicability of Existing Matching Rules . . . . 17 80 3.2.1.1. String Matching . . . . . . . . . . . . 17 81 3.2.1.2. Telephone Number Matching . . . . . . . 17 82 3.2.1.3. Distinguished Name Matching . . . . . . 18 83 3.2.2. Additional Useful Matching Rules . . . . . . . . 18 84 3.2.2.1. The rdnMatch Matching Rule. . . . . . . 18 85 3.2.2.2. The presentMatch Matching Rule. . . . . 19 86 3.2.3. Summary of Useful Matching Rules . . . . . . . . 20 87 4. ComponentFilter. . . . . . . . . . . . . . . . . . . . . . . . 21 88 5. The componentFilterMatch Matching Rule . . . . . . . . . . . . 22 89 6. Equality Matching of Complex Components. . . . . . . . . . . . 24 90 6.1. The OpenAssertionType Syntax . . . . . . . . . . . . . . 24 91 6.2. The allComponentsMatch Matching Rule . . . . . . . . . . 25 92 6.3. Deriving Component Equality Matching Rules . . . . . . . 27 93 6.4. The directoryComponentsMatch Matching Rule . . . . . . . 28 94 7. Component Matching Examples. . . . . . . . . . . . . . . . . . 30 95 8. Security Considerations. . . . . . . . . . . . . . . . . . . . 37 96 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 97 10. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 37 98 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38 99 11.1. Normative References. . . . . . . . . . . . . . . . . . 38 100 11.2. Informative References. . . . . . . . . . . . . . . . . 40 101 12. Intellectual Property Statement. . . . . . . . . . . . . . . . 40 102 13. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 41 103 14. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 42 104 105 106 107 108 109 110 111 112 113 114Legg Standards Track [Page 2] 115 116RFC 3687 LDAP and X.500 Component Matching Rules February 2004 117 118 1191. Introduction 120 121 The structure or data type of data held in an attribute of a 122 Lightweight Directory Access Protocol (LDAP) [7] or X.500 [19] 123 directory is described by the attribute's syntax. Attribute syntaxes 124 range from simple data types, such as text string, integer, or 125 boolean, to complex data types, for example, the syntaxes of the 126 directory schema operational attributes. 127 128 In X.500, the attribute syntaxes are explicitly described by Abstract 129 Syntax Notation One (ASN.1) [13] type definitions. ASN.1 type 130 notation has a number of simple data types (e.g., PrintableString, 131 INTEGER, BOOLEAN), and combining types (i.e., SET, SEQUENCE, SET OF, 132 SEQUENCE OF, and CHOICE) for constructing arbitrarily complex data 133 types from simpler component types. In LDAP, the attribute syntaxes 134 are usually described in Augmented Backus-Naur Form (ABNF) [2], 135 though there is an implied association between the LDAP attribute 136 syntaxes and the X.500 ASN.1 types. To a large extent, the data 137 types of attribute values in either an LDAP or X.500 directory are 138 described by ASN.1 types. This formal description can be exploited 139 to identify component parts of an attribute value for a variety of 140 purposes. This document addresses attribute value matching. 141 142 With any complex attribute syntax there is normally a requirement to 143 partially match an attribute value of that syntax by matching only 144 selected components of the value. Typically, matching rules specific 145 to the attribute syntax are defined to fill this need. These highly 146 specific matching rules usually only provide the most immediately 147 useful matching capability. Some complex attribute syntaxes don't 148 even have an equality matching rule let alone any additional matching 149 rules for partial matching. This document defines a generic way of 150 matching user selected components in an attribute value of any 151 arbitrarily complex attribute syntax, where that syntax is described 152 using ASN.1 type notation. All of the type notations defined in 153 X.680 [13] are supported. 154 155 Section 3 describes the ComponentAssertion, a testable assertion 156 about the value of a component of an attribute value of any complex 157 syntax. 158 159 Section 4 introduces the ComponentFilter assertion, which is an 160 expression of ComponentAssertions. The ComponentFilter enables more 161 powerful filter matching of components in an attribute value. 162 163 Section 5 defines the componentFilterMatch matching rule, which 164 enables a ComponentFilter to be evaluated against attribute values. 165 166 167 168 169 170Legg Standards Track [Page 3] 171 172RFC 3687 LDAP and X.500 Component Matching Rules February 2004 173 174 175 Section 6 defines matching rules for component-wise equality matching 176 of attribute values of any syntax described by an ASN.1 type 177 definition. 178 179 Examples showing the usage of componentFilterMatch are in Section 7. 180 181 For a new attribute syntax, the Generic String Encoding Rules [9] and 182 the specifications in sections 3 to 6 of this document make it 183 possible to fully and precisely define the LDAP-specific encoding, 184 the LDAP and X.500 binary encoding (and possibly other ASN.1 185 encodings in the future), a suitable equality matching rule, and a 186 comprehensive collection of component matching capabilities, by 187 simply writing down an ASN.1 type definition for the syntax. These 188 implicit definitions are also automatically extended if the ASN.1 189 type is later extended. The algorithmic relationship between the 190 ASN.1 type definition, the various encodings and the component 191 matching behaviour makes directory server implementation support for 192 the component matching rules amenable to automatic code generation 193 from ASN.1 type definitions. 194 195 Schema designers have the choice of storing related items of data as 196 a single attribute value of a complex syntax in some entry, or as a 197 subordinate entry where the related data items are stored as separate 198 attribute values of simpler syntaxes. The inability to search 199 component parts of a complex syntax has been used as an argument for 200 favouring the subordinate entries approach. The component matching 201 rules provide the analogous matching capability on an attribute value 202 of a complex syntax that a search filter has on a subordinate entry. 203 204 Most LDAP syntaxes have corresponding ASN.1 type definitions, though 205 they are usually not reproduced or referenced alongside the formal 206 definition of the LDAP syntax. Syntaxes defined with only a 207 character string encoding, i.e., without an explicit or implied 208 corresponding ASN.1 type definition, cannot use the component 209 matching capabilities described in this document unless and until a 210 semantically equivalent ASN.1 type definition is defined for them. 211 2122. Conventions 213 214 Throughout this document "type" shall be taken to mean an ASN.1 type 215 unless explicitly qualified as an attribute type, and "value" shall 216 be taken to mean an ASN.1 value unless explicitly qualified as an 217 attribute value. 218 219 220 221 222 223 224 225 226Legg Standards Track [Page 4] 227 228RFC 3687 LDAP and X.500 Component Matching Rules February 2004 229 230 231 Note that "ASN.1 value" does not mean a Basic Encoding Rules (BER) 232 [17] encoded value. The ASN.1 value is an abstract concept that is 233 independent of any particular encoding. BER is just one possible 234 encoding of an ASN.1 value. The component matching rules operate at 235 the abstract level without regard for the possible encodings of a 236 value. 237 238 Attribute type and matching rule definitions in this document are 239 provided in both the X.500 [10] and LDAP [4] description formats. 240 Note that the LDAP descriptions have been rendered with additional 241 white-space and line breaks for the sake of readability. 242 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED" and "MAY" in this document are 245 to be interpreted as described in BCP 14, RFC 2119 [1]. The key word 246 "OPTIONAL" is exclusively used with its ASN.1 meaning. 247 2483. ComponentAssertion 249 250 A ComponentAssertion is an assertion about the presence, or values 251 of, components within an ASN.1 value, i.e., an instance of an ASN.1 252 type. The ASN.1 value is typically an attribute value, where the 253 ASN.1 type is the syntax of the attribute. However, a 254 ComponentAssertion may also be applied to a component part of an 255 attribute value. The assertion evaluates to either TRUE, FALSE or 256 Undefined for each tested ASN.1 value. 257 258 A ComponentAssertion is described by the following ASN.1 type 259 (assumed to be defined with "EXPLICIT TAGS" in force): 260 261 ComponentAssertion ::= SEQUENCE { 262 component ComponentReference (SIZE(1..MAX)) OPTIONAL, 263 useDefaultValues BOOLEAN DEFAULT TRUE, 264 rule MATCHING-RULE.&id, 265 value MATCHING-RULE.&AssertionType } 266 267 ComponentReference ::= UTF8String 268 269 MATCHING-RULE.&id equates to the OBJECT IDENTIFIER of a matching 270 rule. MATCHING-RULE.&AssertionType is an open type (formerly known 271 as the ANY type). 272 273 The "component" field of a ComponentAssertion identifies which 274 component part of a value of some ASN.1 type is to be tested, the 275 "useDefaultValues" field indicates whether DEFAULT values are to be 276 substituted for absent component values, the "rule" field indicates 277 278 279 280 281 282Legg Standards Track [Page 5] 283 284RFC 3687 LDAP and X.500 Component Matching Rules February 2004 285 286 287 how the component is to be tested, and the "value" field is an 288 asserted ASN.1 value against which the component is tested. The 289 ASN.1 type of the asserted value is determined by the chosen rule. 290 291 The fields of a ComponentAssertion are described in detail in the 292 following sections. 293 2943.1. Component Reference 295 296 The component field in a ComponentAssertion is a UTF-8 character 297 string [6] whose textual content is a component reference, 298 identifying a component part of some ASN.1 type or value. A 299 component reference conforms to the following ABNF [2], which extends 300 the notation defined in Clause 14 of X.680 [13]: 301 302 component-reference = ComponentId *( "." ComponentId ) 303 ComponentId = identifier / 304 from-beginning / 305 count / 306 from-end / ; extends Clause 14 307 content / ; extends Clause 14 308 select / ; extends Clause 14 309 all 310 311 identifier = lowercase *alphanumeric 312 *(hyphen 1*alphanumeric) 313 alphanumeric = uppercase / lowercase / decimal-digit 314 uppercase = %x41-5A ; "A" to "Z" 315 lowercase = %x61-7A ; "a" to "z" 316 hyphen = "-" 317 318 from-beginning = positive-number 319 count = "0" 320 from-end = "-" positive-number 321 content = %x63.6F.6E.74.65.6E.74 ; "content" 322 select = "(" Value *( "," Value ) ")" 323 all = "*" 324 325 326 positive-number = non-zero-digit *decimal-digit 327 328 decimal-digit = %x30-39 ; "0" to "9" 329 non-zero-digit = %x31-39 ; "1" to "9" 330 331 332 333 334 335 336 337 338Legg Standards Track [Page 6] 339 340RFC 3687 LDAP and X.500 Component Matching Rules February 2004 341 342 343 An <identifier> conforms to the definition of an identifier in ASN.1 344 notation (Clause 11.3 of X.680 [13]). It begins with a lowercase 345 letter and is followed by zero or more letters, digits, and hyphens. 346 A hyphen is not permitted to be the last character and a hyphen is 347 not permitted to be followed by another hyphen. 348 349 The <Value> rule is described by the Generic String Encoding Rules 350 (GSER) [9]. 351 352 A component reference is a sequence of one or more ComponentIds where 353 each successive ComponentId identifies either an inner component at 354 the next level of nesting of an ASN.1 combining type, i.e., SET, 355 SEQUENCE, SET OF, SEQUENCE OF, or CHOICE, or a specific type within 356 an ASN.1 open type. 357 358 A component reference is always considered in the context of a 359 particular complex ASN.1 type. When applied to the ASN.1 type the 360 component reference identifies a specific component type. When 361 applied to a value of the ASN.1 type a component reference identifies 362 zero, one or more component values of that component type. The 363 component values are potentially in a DEFAULT value if 364 useDefaultValues is TRUE. The specific component type identified by 365 the component reference determines what matching rules are capable of 366 being used to match the component values. 367 368 The component field in a ComponentAssertion may also be absent, in 369 which case the identified component type is the ASN.1 type to which 370 the ComponentAssertion is applied, and the identified component value 371 is the whole ASN.1 value. 372 373 A valid component reference for a particular complex ASN.1 type is 374 constructed by starting with the outermost combining type and 375 repeatedly selecting one of the permissible forms of ComponentId to 376 identify successively deeper nested components. A component 377 reference MAY identify a component with a complex ASN.1 type, i.e., 378 it is not required that the component type identified by a component 379 reference be a simple ASN.1 type. 380 3813.1.1. Component Type Substitutions 382 383 ASN.1 type notation has a number of constructs for referencing other 384 defined types, and constructs that are irrelevant for matching 385 purposes. These constructs are not represented in a component 386 reference in any way and substitutions of the component type are 387 performed to eliminate them from further consideration. These 388 substitutions automatically occur prior to each ComponentId, whether 389 constructing or interpreting a component reference, but do not occur 390 after the last ComponentId, except as allowed by Section 3.2. 391 392 393 394Legg Standards Track [Page 7] 395 396RFC 3687 LDAP and X.500 Component Matching Rules February 2004 397 398 399 If the ASN.1 type is an ASN.1 type reference then the component type 400 is taken to be the actual definition on the right hand side of the 401 type assignment for the referenced type. 402 403 If the ASN.1 type is a tagged type then the component type is taken 404 to be the type without the tag. 405 406 If the ASN.1 type is a constrained type (see X.680 [13] and X.682 407 [15] for the details of ASN.1 constraint notation) then the component 408 type is taken to be the type without the constraint. 409 410 If the ASN.1 type is an ObjectClassFieldType (Clause 14 of X.681 411 [14]) that denotes a specific ASN.1 type (e.g., MATCHING-RULE.&id 412 denotes the OBJECT IDENTIFIER type) then the component type is taken 413 to be the denoted type. Section 3.1.6 describes the case where the 414 ObjectClassFieldType denotes an open type. 415 416 If the ASN.1 type is a selection type other than one used in the list 417 of components for a SET or SEQUENCE type then the component type is 418 taken to be the selected alternative type from the named CHOICE. 419 420 If the ASN.1 type is a TypeFromObject (Clause 15 of X.681 [14]) then 421 the component type is taken to be the denoted type. 422 423 If the ASN.1 type is a ValueSetFromObjects (Clause 15 of X.681 [14]) 424 then the component type is taken to be the governing type of the 425 denoted values. 426 4273.1.2. Referencing SET, SEQUENCE and CHOICE Components 428 429 If the ASN.1 type is a SET or SEQUENCE type then the <identifier> 430 form of ComponentId may be used to identify the component type within 431 that SET or SEQUENCE having that identifier. If <identifier> 432 references an OPTIONAL component type and that component is not 433 present in a particular value then there are no corresponding 434 component values. If <identifier> references a DEFAULT component 435 type and useDefaultValues is TRUE (the default setting for 436 useDefaultValues) and that component is not present in a particular 437 value then the component value is taken to be the default value. If 438 <identifier> references a DEFAULT component type and useDefaultValues 439 is FALSE and that component is not present in a particular value then 440 there are no corresponding component values. 441 442 If the ASN.1 type is a CHOICE type then the <identifier> form of 443 ComponentId may be used to identify the alternative type within that 444 CHOICE having that identifier. If <identifier> references an 445 alternative other than the one used in a particular value then there 446 are no corresponding component values. 447 448 449 450Legg Standards Track [Page 8] 451 452RFC 3687 LDAP and X.500 Component Matching Rules February 2004 453 454 455 The COMPONENTS OF notation in Clause 24 of X.680 [13] augments the 456 defined list of components in a SET or SEQUENCE type by including all 457 the components of another defined SET or SEQUENCE type respectively. 458 These included components are referenced directly by identifier as 459 though they were defined in-line in the SET or SEQUENCE type 460 containing the COMPONENTS OF notation. 461 462 The SelectionType (Clause 29 of X.680 [13]), when used in the list of 463 components for a SET or SEQUENCE type, includes a single component 464 from a defined CHOICE type. This included component is referenced 465 directly by identifier as though it was defined in-line in the SET or 466 SEQUENCE type. 467 468 The REAL type is treated as though it is the SEQUENCE type defined in 469 Clause 20.5 of X.680 [13]. 470 471 The EMBEDDED PDV type is treated as though it is the SEQUENCE type 472 defined in Clause 33.5 of X.680 [13]. 473 474 The EXTERNAL type is treated as though it is the SEQUENCE type 475 defined in Clause 8.18.1 of X.690 [17]. 476 477 The unrestricted CHARACTER STRING type is treated as though it is the 478 SEQUENCE type defined in Clause 40.5 of X.680 [13]. 479 480 The INSTANCE OF type is treated as though it is the SEQUENCE type 481 defined in Annex C of X.681 [14]. 482 483 The <identifier> form MUST NOT be used on any other ASN.1 type. 484 4853.1.3. Referencing SET OF and SEQUENCE OF Components 486 487 If the ASN.1 type is a SET OF or SEQUENCE OF type then the 488 <from-beginning>, <from-end>, <count> and <all> forms of ComponentId 489 may be used. 490 491 The <from-beginning> form of ComponentId may be used to identify one 492 instance (i.e., value) of the component type of the SET OF or 493 SEQUENCE OF type (e.g., if Foo ::= SET OF Bar, then Bar is the 494 component type), where the instances are numbered from one upwards. 495 If <from-beginning> references a higher numbered instance than the 496 last instance in a particular value of the SET OF or SEQUENCE OF type 497 then there is no corresponding component value. 498 499 The <from-end> form of ComponentId may be used to identify one 500 instance of the component type of the SET OF or SEQUENCE OF type, 501 where "-1" is the last instance, "-2" is the second last instance, 502 503 504 505 506Legg Standards Track [Page 9] 507 508RFC 3687 LDAP and X.500 Component Matching Rules February 2004 509 510 511 and so on. If <from-end> references a lower numbered instance than 512 the first instance in a particular value of the SET OF or SEQUENCE OF 513 type then there is no corresponding component value. 514 515 The <count> form of ComponentId identifies a notional count of the 516 number of instances of the component type in a value of the SET OF or 517 SEQUENCE OF type. This count is not explicitly represented but for 518 matching purposes it has an assumed ASN.1 type of INTEGER (0..MAX). 519 A ComponentId of the <count> form, if used, MUST be the last 520 ComponentId in a component reference. 521 522 The <all> form of ComponentId may be used to simultaneously identify 523 all instances of the component type of the SET OF or SEQUENCE OF 524 type. It is through the <all> form that a component reference can 525 identify more than one component value. However, if a particular 526 value of the SET OF or SEQUENCE OF type is an empty list, then there 527 are no corresponding component values. 528 529 Where multiple component values are identified, the remaining 530 ComponentIds in the component reference, if any, can identify zero, 531 one or more subcomponent values for each of the higher level 532 component values. 533 534 The corresponding ASN.1 type for the <from-beginning>, <from-end>, 535 and <all> forms of ComponentId is the component type of the SET OF or 536 SEQUENCE OF type. 537 538 The <from-beginning>, <count>, <from-end> and <all> forms MUST NOT be 539 used on ASN.1 types other than SET OF or SEQUENCE OF. 540 5413.1.4. Referencing Components of Parameterized Types 542 543 A component reference cannot be formed for a parameterized type 544 unless the type has been used with actual parameters, in which case 545 the type is treated as though the DummyReferences [16] have been 546 substituted with the actual parameters. 547 5483.1.5. Component Referencing Example 549 550 Consider the following ASN.1 type definitions. 551 552 ExampleType ::= SEQUENCE { 553 part1 [0] INTEGER, 554 part2 [1] ExampleSet, 555 part3 [2] SET OF OBJECT IDENTIFIER, 556 part4 [3] ExampleChoice } 557 558 559 560 561 562Legg Standards Track [Page 10] 563 564RFC 3687 LDAP and X.500 Component Matching Rules February 2004 565 566 567 ExampleSet ::= SET { 568 option PrintableString, 569 setting BOOLEAN } 570 571 ExampleChoice ::= CHOICE { 572 eeny-meeny BIT STRING, 573 miney-mo OCTET STRING } 574 575 Following are component references constructed with respect to the 576 type ExampleType. 577 578 The component reference "part1" identifies a component of a value of 579 ExampleType having the ASN.1 tagged type [0] INTEGER. 580 581 The component reference "part2" identifies a component of a value of 582 ExampleType having the ASN.1 type of [1] ExampleSet 583 584 The component reference "part2.option" identifies a component of a 585 value of ExampleType having the ASN.1 type of PrintableString. A 586 ComponentAssertion could also be applied to a value of ASN.1 type 587 ExampleSet, in which case the component reference "option" would 588 identify the same kind of information. 589 590 The component reference "part3" identifies a component of a value of 591 ExampleType having the ASN.1 type of [2] SET OF OBJECT IDENTIFIER. 592 593 The component reference "part3.2" identifies the second instance of 594 the part3 SET OF. The instance has the ASN.1 type of OBJECT 595 IDENTIFIER. 596 597 The component reference "part3.0" identifies the count of the number 598 of instances in the part3 SET OF. The count has the corresponding 599 ASN.1 type of INTEGER (0..MAX). 600 601 The component reference "part3.*" identifies all the instances in the 602 part3 SET OF. Each instance has the ASN.1 type of OBJECT IDENTIFIER. 603 604 The component reference "part4" identifies a component of a value of 605 ExampleType having the ASN.1 type of [3] ExampleChoice. 606 607 The component reference "part4.miney-mo" identifies a component of a 608 value of ExampleType having the ASN.1 type of OCTET STRING. 609 610 611 612 613 614 615 616 617 618Legg Standards Track [Page 11] 619 620RFC 3687 LDAP and X.500 Component Matching Rules February 2004 621 622 6233.1.6. Referencing Components of Open Types 624 625 If a sequence of ComponentIds identifies an ObjectClassFieldType 626 denoting an open type (e.g., ATTRIBUTE.&Type denotes an open type) 627 then the ASN.1 type of the component varies. An open type is 628 typically constrained by some other component(s) in an outer 629 enclosing type, either formally through the use of a component 630 relation constraint [15], or informally in the accompanying text, so 631 the actual ASN.1 type of a value of the open type will generally be 632 known. The constraint will also limit the range of permissible 633 types. The <select> form of ComponentId may be used to identify one 634 of these permissible types in an open type. Subcomponents of that 635 type can then be identified with further ComponentIds. 636 637 The other components constraining the open type are termed the 638 referenced components [15]. The <select> form contains a list of one 639 or more values which take the place of the value(s) of the referenced 640 component(s) to uniquely identify one of the permissible types of the 641 open type. 642 643 Where the open type is constrained by a component relation 644 constraint, there is a <Value> in the <select> form for each of the 645 referenced components in the component relation constraint, appearing 646 in the same order. The ASN.1 type of each of these values is the 647 same as the ASN.1 type of the corresponding referenced component. 648 The type of a referenced component is potentially any ASN.1 type 649 however it is typically an OBJECT IDENTIFIER or INTEGER, which means 650 that the <Value> in the <select> form of ComponentId will nearly 651 always be an <ObjectIdentifierValue> or <IntegerValue> [9]. 652 Furthermore, component relation constraints typically have only one 653 referenced component. 654 655 Where the open type is not constrained by a component relation 656 constraint, the specification introducing the syntax containing the 657 open type should explicitly nominate the referenced components and 658 their order, so that the <select> form can be used. 659 660 If an instance of <select> contains a value other than the value of 661 the referenced component used in a particular value of the outer 662 enclosing type then there are no corresponding component values for 663 the open type. 664 6653.1.6.1. Open Type Referencing Example 666 667 The ASN.1 type AttributeTypeAndValue [10] describes a single 668 attribute value of a nominated attribute type. 669 670 671 672 673 674Legg Standards Track [Page 12] 675 676RFC 3687 LDAP and X.500 Component Matching Rules February 2004 677 678 679 AttributeTypeAndValue ::= SEQUENCE { 680 type ATTRIBUTE.&id ({SupportedAttributes}), 681 value ATTRIBUTE.&Type ({SupportedAttributes}{@type}) } 682 683 ATTRIBUTE.&id denotes an OBJECT IDENTIFIER and 684 ({SupportedAttributes}) constrains the OBJECT IDENTIFIER to be a 685 supported attribute type. 686 687 ATTRIBUTE.&Type denotes an open type, in this case an attribute 688 value, and ({SupportedAttributes}{@type}) is a component relation 689 constraint that constrains the open type to be of the attribute 690 syntax for the attribute type. The component relation constraint 691 references only the "type" component, which has the ASN.1 type of 692 OBJECT IDENTIFIER, thus if the <select> form of ComponentId is used 693 to identify attribute values of specific attribute types it will 694 contain a single OBJECT IDENTIFIER value. 695 696 The component reference "value" on AttributeTypeAndValue refers to 697 the open type. 698 699 One of the X.500 standard attributes is facsimileTelephoneNumber 700 [12], which is identified with the OBJECT IDENTIFIER 2.5.4.23, and is 701 defined to have the following syntax. 702 703 FacsimileTelephoneNumber ::= SEQUENCE { 704 telephoneNumber PrintableString(SIZE(1..ub-telephone-number)), 705 parameters G3FacsimileNonBasicParameters OPTIONAL } 706 707 The component reference "value.(2.5.4.23)" on AttributeTypeAndValue 708 specifies an attribute value with the FacsimileTelephoneNumber 709 syntax. 710 711 The component reference "value.(2.5.4.23).telephoneNumber" on 712 AttributeTypeAndValue identifies the telephoneNumber component of a 713 facsimileTelephoneNumber attribute value. The component reference 714 "value.(facsimileTelephoneNumber)" is equivalent to 715 "value.(2.5.4.23)". 716 717 If the AttributeTypeAndValue ASN.1 value contains an attribute type 718 other than facsimileTelephoneNumber then there are no corresponding 719 component values for the component references "value.(2.5.4.23)" and 720 "value.(2.5.4.23).telephoneNumber". 721 722 723 724 725 726 727 728 729 730Legg Standards Track [Page 13] 731 732RFC 3687 LDAP and X.500 Component Matching Rules February 2004 733 734 7353.1.7. Referencing Contained Types 736 737 Sometimes the contents of a BIT STRING or OCTET STRING value are 738 required to be the encodings of other ASN.1 values of specific ASN.1 739 types. For example, the extnValue component of the Extension type 740 component in the Certificate type [11] is an OCTET STRING that is 741 required to contain a Distinguished Encoding Rules (DER) [17] 742 encoding of a certificate extension value. It is useful to be able 743 to refer to the embedded encoded value and its components. An 744 embedded encoded value is here referred to as a contained value and 745 its associated type as the contained type. 746 747 If the ASN.1 type is a BIT STRING or OCTET STRING type containing 748 encodings of other ASN.1 values then the <content> form of 749 ComponentId may be used to identify the contained type. 750 Subcomponents of that type can then be identified with further 751 ComponentIds. 752 753 The contained type may be (effectively) an open type, constrained by 754 some other component in an outer enclosing type (e.g., in a 755 certificate Extension, extnValue is constrained by the chosen 756 extnId). In these cases the next ComponentId, if any, MUST be of the 757 <select> form. 758 759 For the purpose of building component references, the content of the 760 extnValue OCTET STRING in the Extension type is assumed to be an open 761 type having a notional component relation constraint with the extnId 762 component as the single referenced component, i.e., 763 764 EXTENSION.&ExtnType ({ExtensionSet}{@extnId}) 765 766 The data-value component of the associated types for the EMBEDDED PDV 767 and CHARACTER STRING types is an OCTET STRING containing the encoding 768 of a data value described by the identification component. For the 769 purpose of building component references, the content of the 770 data-value OCTET STRING in these types is assumed to be an open type 771 having a notional component relation constraint with the 772 identification component as the single referenced component. 773 7743.1.7.1. Contained Type Referencing Example 775 776 The Extension ASN.1 type [11] describes a single certificate 777 extension value of a nominated extension type. 778 779 780 781 782 783 784 785 786Legg Standards Track [Page 14] 787 788RFC 3687 LDAP and X.500 Component Matching Rules February 2004 789 790 791 Extension ::= SEQUENCE { 792 extnId EXTENSION.&id ({ExtensionSet}), 793 critical BOOLEAN DEFAULT FALSE, 794 extnValue OCTET STRING 795 -- contains a DER encoding of a value of type &ExtnType 796 -- for the extension object identified by extnId -- } 797 798 EXTENSION.&id denotes an OBJECT IDENTIFIER and ({ExtensionSet}) 799 constrains the OBJECT IDENTIFIER to be the identifier of a supported 800 certificate extension. 801 802 The component reference "extnValue" on Extension refers to a 803 component type of OCTET STRING. The corresponding component values 804 will be OCTET STRING values. The component reference 805 "extnValue.content" on Extension refers to the type of the contained 806 type, which in this case is an open type. 807 808 One of the X.509 [11] standard extensions is basicConstraints, which 809 is identified with the OBJECT IDENTIFIER 2.5.29.19 and is defined to 810 have the following syntax. 811 812 BasicConstraintsSyntax ::= SEQUENCE { 813 cA BOOLEAN DEFAULT FALSE, 814 pathLenConstraint INTEGER (0..MAX) OPTIONAL } 815 816 The component reference "extnValue.content.(2.5.29.19)" on Extension 817 specifies a BasicConstraintsSyntax extension value and the component 818 reference "extnValue.content.(2.5.29.19).cA" identifies the cA 819 component of a BasicConstraintsSyntax extension value. 820 8213.2. Matching of Components 822 823 The rule in a ComponentAssertion specifies how the zero, one or more 824 component values identified by the component reference are tested by 825 the assertion. Attribute matching rules are used to specify the 826 semantics of the test. 827 828 Each matching rule has a notional set of attribute syntaxes 829 (typically one), defined as ASN.1 types, to which it may be applied. 830 When used in a ComponentAssertion these matching rules apply to the 831 same ASN.1 types, only in this context the corresponding ASN.1 values 832 are not necessarily complete attribute values. 833 834 Note that the referenced component type may be a tagged and/or 835 constrained version of the expected attribute syntax (e.g., 836 [0] INTEGER, whereas integerMatch would expect simply INTEGER), or an 837 open type. Additional type substitutions of the kind described in 838 839 840 841 842Legg Standards Track [Page 15] 843 844RFC 3687 LDAP and X.500 Component Matching Rules February 2004 845 846 847 Section 3.1.1 are performed as required to reduce the component type 848 to the same type as the attribute syntax expected by the matching 849 rule. 850 851 If a matching rule applies to more than one attribute syntax (e.g., 852 objectIdentifierFirstComponentMatch [12]) then the minimum number of 853 substitutions required to conform to any one of those syntaxes is 854 performed. If a matching rule can apply to any attribute syntax 855 (e.g., the allComponentsMatch rule defined in Section 6.2) then the 856 referenced component type is used as is, with no additional 857 substitutions. 858 859 The value in a ComponentAssertion will be of the assertion syntax 860 (i.e., ASN.1 type) required by the chosen matching rule. Note that 861 the assertion syntax of a matching rule is not necessarily the same 862 as the attribute syntax(es) to which the rule may be applied. 863 864 Some matching rules do not have a fixed assertion syntax (e.g., 865 allComponentsMatch). The required assertion syntax is determined in 866 each instance of use by the syntax of the attribute type to which the 867 matching rule is applied. For these rules the ASN.1 type of the 868 referenced component is used in place of an attribute syntax to 869 decide the required assertion syntax. 870 871 The ComponentAssertion is Undefined if: 872 873 a) the matching rule in the ComponentAssertion is not known to the 874 evaluating procedure, 875 876 b) the matching rule is not applicable to the referenced component 877 type, even with the additional type substitutions, 878 879 c) the value in the ComponentAssertion does not conform to the 880 assertion syntax defined for the matching rule, 881 882 d) some part of the component reference identifies an open type in 883 the tested value that cannot be decoded, or 884 885 e) the implementation does not support the particular combination of 886 component reference and matching rule. 887 888 If the ComponentAssertion is not Undefined then the 889 ComponentAssertion evaluates to TRUE if there is at least one 890 component value for which the matching rule applied to that component 891 value returns TRUE, and evaluates to FALSE otherwise (which includes 892 the case where there are no component values). 893 894 895 896 897 898Legg Standards Track [Page 16] 899 900RFC 3687 LDAP and X.500 Component Matching Rules February 2004 901 902 9033.2.1. Applicability of Existing Matching Rules 904 9053.2.1.1. String Matching 906 907 ASN.1 has a number of built in restricted character string types with 908 different character sets and/or different character encodings. A 909 directory user generally has little interest in the particular 910 character set or encoding used to represent a character string 911 component value, and some directory server implementations make no 912 distinction between the different string types in their internal 913 representation of values. So rather than define string matching 914 rules for each of the restricted character string types, the existing 915 case ignore and case exact string matching rules are extended to 916 apply to component values of any of the restricted character string 917 types and any ChoiceOfStrings type [9], in addition to component 918 values of the DirectoryString type. This extension is only for the 919 purposes of component matching described in this document. 920 921 The relevant string matching rules are: caseIgnoreMatch, 922 caseIgnoreOrderingMatch, caseIgnoreSubstringsMatch, caseExactMatch, 923 caseExactOrderingMatch and caseExactSubstringsMatch. The relevant 924 restricted character string types are: NumericString, 925 PrintableString, VisibleString, IA5String, UTF8String, BMPString, 926 UniversalString, TeletexString, VideotexString, GraphicString and 927 GeneralString. A ChoiceOfStrings type is a purely syntactic CHOICE 928 of these ASN.1 string types. Note that GSER [9] declares each and 929 every use of the DirectoryString{} parameterized type to be a 930 ChoiceOfStrings type. 931 932 The assertion syntax of the string matching rules is still 933 DirectoryString regardless of the string syntax of the component 934 being matched. Thus an implementation will be called upon to compare 935 a DirectoryString value to a value of one of the restricted character 936 string types, or a ChoiceOfStrings type. As is the case when 937 comparing two DirectoryStrings where the chosen alternatives are of 938 different string types, the comparison proceeds so long as the 939 corresponding characters are representable in both character sets. 940 Otherwise matching returns FALSE. 941 9423.2.1.2. Telephone Number Matching 943 944 Early editions of X.520 [12] gave the syntax of the telephoneNumber 945 attribute as a constrained PrintableString. The fourth edition of 946 X.520 equates the ASN.1 type name TelephoneNumber to the constrained 947 PrintableString and uses TelephoneNumber as the attribute and 948 assertion syntax. For the purposes of component matching, 949 950 951 952 953 954Legg Standards Track [Page 17] 955 956RFC 3687 LDAP and X.500 Component Matching Rules February 2004 957 958 959 telephoneNumberMatch and telephoneNumberSubstringsMatch are permitted 960 to be applied to any PrintableString value, as well as to 961 TelephoneNumber values. 962 9633.2.1.3. Distinguished Name Matching 964 965 The DistinguishedName type is defined by assignment to be the same as 966 the RDNSequence type, however RDNSequence is sometimes directly used 967 in other type definitions. For the purposes of component matching, 968 distinguishedNameMatch is also permitted to be applied to values of 969 the RDNSequence type. 970 9713.2.2. Additional Useful Matching Rules 972 973 This section defines additional matching rules that may prove useful 974 in ComponentAssertions. These rules may also be used in 975 extensibleMatch search filters [3]. 976 9773.2.2.1. The rdnMatch Matching Rule 978 979 The distinguishedNameMatch matching rule can match whole 980 distinguished names but it is sometimes useful to be able to match 981 specific Relative Distinguished Names (RDNs) in a Distinguished Name 982 (DN) without regard for the other RDNs in the DN. The rdnMatch 983 matching rule allows component RDNs of a DN to be tested. 984 985 The LDAP-style definitions for rdnMatch and its assertion syntax are: 986 987 ( 1.2.36.79672281.1.13.3 NAME 'rdnMatch' 988 SYNTAX 1.2.36.79672281.1.5.0 ) 989 990 ( 1.2.36.79672281.1.5.0 DESC 'RDN' ) 991 992 The LDAP-specific encoding for a value of the RDN syntax is given by 993 the <RelativeDistinguishedNameValue> rule [9]. 994 995 The X.500-style definition for rdnMatch is: 996 997 rdnMatch MATCHING-RULE ::= { 998 SYNTAX RelativeDistinguishedName 999 ID { 1 2 36 79672281 1 13 3 } } 1000 1001 The rdnMatch rule evaluates to true if the component value and 1002 assertion value are the same RDN, using the same RDN comparison 1003 method as distinguishedNameMatch. 1004 1005 1006 1007 1008 1009 1010Legg Standards Track [Page 18] 1011 1012RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1013 1014 1015 When using rdnMatch to match components of DNs it is important to 1016 note that the LDAP-specific encoding of a DN [5] reverses the order 1017 of the RDNs. So for the DN represented in LDAP as 1018 "cn=Steven Legg,o=Adacel,c=AU", the RDN "cn=Steven Legg" corresponds 1019 to the component reference "3", or alternatively, "-1". 1020 10213.2.2.2. The presentMatch Matching Rule 1022 1023 At times it would be useful to test not if a specific value of a 1024 particular component is present, but whether any value of a 1025 particular component is present. The presentMatch matching rule 1026 allows the presence of a particular component value to be tested. 1027 1028 The LDAP-style definitions for presentMatch and its assertion syntax 1029 are: 1030 1031 ( 1.2.36.79672281.1.13.5 NAME 'presentMatch' 1032 SYNTAX 1.2.36.79672281.1.5.1 ) 1033 1034 ( 1.2.36.79672281.1.5.1 DESC 'NULL' ) 1035 1036 The LDAP-specific encoding for a value of the NULL syntax is given by 1037 the <NullValue> rule [9]. 1038 1039 The X.500-style definition for presentMatch is: 1040 1041 presentMatch MATCHING-RULE ::= { 1042 SYNTAX NULL 1043 ID { 1 2 36 79672281 1 13 5 } } 1044 1045 When used in a extensible match filter item, presentMatch behaves 1046 like the "present" case of a regular search filter. In a 1047 ComponentAssertion, presentMatch evaluates to TRUE if and only if the 1048 component reference identifies one or more component values, 1049 regardless of the actual component value contents. Note that if 1050 useDefaultValues is TRUE then the identified component values may be 1051 (part of) a DEFAULT value. 1052 1053 The notional count referenced by the <count> form of ComponentId is 1054 taken to be present if the SET OF value is present, and absent 1055 otherwise. Note that in ASN.1 notation an absent SET OF value is 1056 distinctly different from a SET OF value that is present but empty. 1057 It is up to the specification using the ASN.1 notation to decide 1058 whether the distinction matters. Often an empty SET OF component and 1059 an absent SET OF component are treated as semantically equivalent. 1060 If a SET OF value is present, but empty, a presentMatch on the SET OF 1061 component SHALL return TRUE and the notional count SHALL be regarded 1062 as present and equal to zero. 1063 1064 1065 1066Legg Standards Track [Page 19] 1067 1068RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1069 1070 10713.2.3. Summary of Useful Matching Rules 1072 1073 The following is a non-exhaustive list of useful matching rules and 1074 the ASN.1 types to which they can be applied, taking account of all 1075 the extensions described in Section 3.2.1, and the new matching rules 1076 defined in Section 3.2.2. 1077 1078 +================================+==============================+ 1079 | Matching Rule | ASN.1 Type | 1080 +================================+==============================+ 1081 | bitStringMatch | BIT STRING | 1082 +--------------------------------+------------------------------+ 1083 | booleanMatch | BOOLEAN | 1084 +--------------------------------+------------------------------+ 1085 | caseIgnoreMatch | NumericString | 1086 | caseIgnoreOrderingMatch | PrintableString | 1087 | caseIgnoreSubstringsMatch | VisibleString (ISO646String) | 1088 | caseExactMatch | IA5String | 1089 | caseExactOrderingMatch | UTF8String | 1090 | caseExactSubstringsMatch | BMPString (UCS-2, UNICODE) | 1091 | | UniversalString (UCS-4) | 1092 | | TeletexString (T61String) | 1093 | | VideotexString | 1094 | | GraphicString | 1095 | | GeneralString | 1096 | | any ChoiceOfStrings type | 1097 +--------------------------------+------------------------------+ 1098 | caseIgnoreIA5Match | IA5String | 1099 | caseExactIA5Match | | 1100 +--------------------------------+------------------------------+ 1101 | distinguishedNameMatch | DistinguishedName | 1102 | | RDNSequence | 1103 +--------------------------------+------------------------------+ 1104 | generalizedTimeMatch | GeneralizedTime | 1105 | generalizedTimeOrderingMatch | | 1106 +--------------------------------+------------------------------+ 1107 | integerMatch | INTEGER | 1108 | integerOrderingMatch | | 1109 +--------------------------------+------------------------------+ 1110 | numericStringMatch | NumericString | 1111 | numericStringOrderingMatch | | 1112 | numericStringSubstringsMatch | | 1113 +--------------------------------+------------------------------+ 1114 | objectIdentifierMatch | OBJECT IDENTIFIER | 1115 +--------------------------------+------------------------------+ 1116 | octetStringMatch | OCTET STRING | 1117 | octetStringOrderingMatch | | 1118 | octetStringSubstringsMatch | | 1119 1120 1121 1122Legg Standards Track [Page 20] 1123 1124RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1125 1126 1127 +--------------------------------+------------------------------+ 1128 | presentMatch | any ASN.1 type | 1129 +--------------------------------+------------------------------+ 1130 | rdnMatch | RelativeDistinguishedName | 1131 +--------------------------------+------------------------------+ 1132 | telephoneNumberMatch | PrintableString | 1133 | telephoneNumberSubstringsMatch | TelephoneNumber | 1134 +--------------------------------+------------------------------+ 1135 | uTCTimeMatch | UTCTime | 1136 | uTCTimeOrderingMatch | | 1137 +--------------------------------+------------------------------+ 1138 1139 Note that the allComponentsMatch matching rule defined in Section 6.2 1140 can be used for equality matching of values of the ENUMERATED, NULL, 1141 REAL and RELATIVE-OID ASN.1 types, among other things. 1142 11434. ComponentFilter 1144 1145 The ComponentAssertion allows the value(s) of any one component type 1146 in a complex ASN.1 type to be matched, but there is often a desire to 1147 match the values of more than one component type. A ComponentFilter 1148 is an assertion about the presence, or values of, multiple components 1149 within an ASN.1 value. 1150 1151 The ComponentFilter assertion, an expression of ComponentAssertions, 1152 evaluates to either TRUE, FALSE or Undefined for each tested ASN.1 1153 value. 1154 1155 A ComponentFilter is described by the following ASN.1 type (assumed 1156 to be defined with "EXPLICIT TAGS" in force): 1157 1158 ComponentFilter ::= CHOICE { 1159 item [0] ComponentAssertion, 1160 and [1] SEQUENCE OF ComponentFilter, 1161 or [2] SEQUENCE OF ComponentFilter, 1162 not [3] ComponentFilter } 1163 1164 Note: despite the use of SEQUENCE OF instead of SET OF for the "and" 1165 and "or" alternatives in ComponentFilter, the order of the component 1166 filters is not significant. 1167 1168 A ComponentFilter that is a ComponentAssertion evaluates to TRUE if 1169 the ComponentAssertion is TRUE, evaluates to FALSE if the 1170 ComponentAssertion is FALSE, and evaluates to Undefined otherwise. 1171 1172 1173 1174 1175 1176 1177 1178Legg Standards Track [Page 21] 1179 1180RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1181 1182 1183 The "and" of a sequence of component filters evaluates to TRUE if the 1184 sequence is empty or if each component filter evaluates to TRUE, 1185 evaluates to FALSE if at least one component filter is FALSE, and 1186 evaluates to Undefined otherwise. 1187 1188 The "or" of a sequence of component filters evaluates to FALSE if the 1189 sequence is empty or if each component filter evaluates to FALSE, 1190 evaluates to TRUE if at least one component filter is TRUE, and 1191 evaluates to Undefined otherwise. 1192 1193 The "not" of a component filter evaluates to TRUE if the component 1194 filter is FALSE, evaluates to FALSE if the component filter is TRUE, 1195 and evaluates to Undefined otherwise. 1196 11975. The componentFilterMatch Matching Rule 1198 1199 The componentFilterMatch matching rule allows a ComponentFilter to be 1200 applied to an attribute value. The result of the matching rule is 1201 the result of applying the ComponentFilter to the attribute value. 1202 1203 The LDAP-style definitions for componentFilterMatch and its assertion 1204 syntax are: 1205 1206 ( 1.2.36.79672281.1.13.2 NAME 'componentFilterMatch' 1207 SYNTAX 1.2.36.79672281.1.5.2 ) 1208 1209 ( 1.2.36.79672281.1.5.2 DESC 'ComponentFilter' ) 1210 1211 The LDAP-specific encoding for the ComponentFilter assertion syntax 1212 is specified by GSER [9]. 1213 1214 As a convenience to implementors, an equivalent ABNF description of 1215 the GSER encoding for ComponentFilter is provided here. In the event 1216 that there is a discrepancy between this ABNF and the encoding 1217 determined by GSER, GSER is to be taken as definitive. The GSER 1218 encoding of a ComponentFilter is described by the following 1219 equivalent ABNF: 1220 1221 ComponentFilter = filter-item / 1222 and-filter / 1223 or-filter / 1224 not-filter 1225 1226 filter-item = item-chosen ComponentAssertion 1227 and-filter = and-chosen SequenceOfComponentFilter 1228 or-filter = or-chosen SequenceOfComponentFilter 1229 not-filter = not-chosen ComponentFilter 1230 1231 1232 1233 1234Legg Standards Track [Page 22] 1235 1236RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1237 1238 1239 item-chosen = %x69.74.65.6D.3A ; "item:" 1240 and-chosen = %x61.6E.64.3A ; "and:" 1241 or-chosen = %x6F.72.3A ; "or:" 1242 not-chosen = %x6E.6F.74.3A ; "not:" 1243 1244 SequenceOfComponentFilter = "{" [ sp ComponentFilter 1245 *( "," sp ComponentFilter) ] sp "}" 1246 1247 ComponentAssertion = "{" [ sp component "," ] 1248 [ sp useDefaultValues "," ] 1249 sp rule "," 1250 sp assertion-value sp "}" 1251 component = component-label msp StringValue 1252 useDefaultValues = use-defaults-label msp BooleanValue 1253 rule = rule-label msp ObjectIdentifierValue 1254 assertion-value = value-label msp Value 1255 1256 component-label = %x63.6F.6D.70.6F.6E.65.6E.74 ; "component" 1257 use-defaults-label = %x75.73.65.44.65.66.61.75.6C.74.56.61.6C.75 1258 %x65.73 ; "useDefaultValues" 1259 rule-label = %x72.75.6C.65 ; "rule" 1260 value-label = %x76.61.6C.75.65 ; "value" 1261 1262 sp = *%x20 ; zero, one or more space characters 1263 msp = 1*%x20 ; one or more space characters 1264 1265 The ABNF for <Value>, <StringValue>, <ObjectIdentifierValue> and 1266 <BooleanValue> is defined by GSER [9]. 1267 1268 The ABNF descriptions of LDAP-specific encodings for attribute 1269 syntaxes typically do not clearly or consistently delineate the 1270 component parts of an attribute value. A regular and uniform 1271 character string encoding for arbitrary component data types is 1272 needed to encode the assertion value in a ComponentAssertion. The 1273 <Value> rule from GSER provides a human readable text encoding for a 1274 component value of any arbitrary ASN.1 type. 1275 1276 The X.500-style definition [10] for componentFilterMatch is: 1277 1278 componentFilterMatch MATCHING-RULE ::= { 1279 SYNTAX ComponentFilter 1280 ID { 1 2 36 79672281 1 13 2 } } 1281 1282 A ComponentAssertion can potentially use any matching rule, including 1283 componentFilterMatch, so componentFilterMatch may be nested. The 1284 component references in a nested componentFilterMatch are relative to 1285 1286 1287 1288 1289 1290Legg Standards Track [Page 23] 1291 1292RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1293 1294 1295 the component corresponding to the containing ComponentAssertion. In 1296 Section 7, an example search on the seeAlso attribute shows this 1297 usage. 1298 12996. Equality Matching of Complex Components 1300 1301 It is possible to test if an attribute value of a complex ASN.1 1302 syntax is the same as some purported (i.e., assertion) value by using 1303 a complicated ComponentFilter that tests if corresponding components 1304 are the same. However, it would be more convenient to be able to 1305 present a whole assertion value to a matching rule that could do the 1306 component-wise comparison of an attribute value with the assertion 1307 value for any arbitrary attribute syntax. Similarly, the ability to 1308 do a straightforward equality comparison of a component value that is 1309 itself of a complex ASN.1 type would also be convenient. 1310 1311 It would be difficult to define a single matching rule that 1312 simultaneously satisfies all notions of what the equality matching 1313 semantics should be. For example, in some instances a case sensitive 1314 comparison of string components may be preferable to a case 1315 insensitive comparison. Therefore a basic equality matching rule, 1316 allComponentsMatch, is defined in Section 6.2, and the means to 1317 derive new matching rules from it with slightly different equality 1318 matching semantics are described in Section 6.3. 1319 1320 The directoryComponentsMatch defined in Section 6.4 is a derivation 1321 of allComponentsMatch that suits typical uses of the directory. 1322 Other specifications are free to derive new rules from 1323 allComponentsMatch or directoryComponentsMatch, that suit their usage 1324 of the directory. 1325 1326 The allComponentsMatch rule, the directoryComponentsMatch rule and 1327 any matching rules derived from them are collectively called 1328 component equality matching rules. 1329 13306.1. The OpenAssertionType Syntax 1331 1332 The component equality matching rules have a variable assertion 1333 syntax. In X.500 this is indicated by omitting the optional SYNTAX 1334 field in the MATCHING-RULE information object. The assertion syntax 1335 then defaults to the target attribute's syntax in actual usage, 1336 unless the description of the matching rule says otherwise. The 1337 SYNTAX field in the LDAP-specific encoding of a 1338 MatchingRuleDescription is mandatory, so the OpenAssertionType syntax 1339 is defined to fill the same role. That is, the OpenAssertionType 1340 syntax is semantically equivalent to an omitted SYNTAX field in an 1341 X.500 MATCHING-RULE information object. OpenAssertionType MUST NOT 1342 be used as the attribute syntax in an attribute type definition. 1343 1344 1345 1346Legg Standards Track [Page 24] 1347 1348RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1349 1350 1351 Unless explicitly varied by the description of a particular matching 1352 rule, if an OpenAssertionType assertion value appears in a 1353 ComponentAssertion its LDAP-specific encoding is described by the 1354 <Value> rule in GSER [9], otherwise its LDAP-specific encoding is the 1355 encoding defined for the syntax of the attribute type to which the 1356 matching rule with the OpenAssertionType assertion syntax is applied. 1357 1358 The LDAP definition for the OpenAssertionType syntax is: 1359 1360 ( 1.2.36.79672281.1.5.3 DESC 'OpenAssertionType' ) 1361 13626.2. The allComponentsMatch Matching Rule 1363 1364 The LDAP-style definition for allComponentsMatch is: 1365 1366 ( 1.2.36.79672281.1.13.6 NAME 'allComponentsMatch' 1367 SYNTAX 1.2.36.79672281.1.5.3 ) 1368 1369 The X.500-style definition for allComponentsMatch is: 1370 1371 allComponentsMatch MATCHING-RULE ::= { 1372 ID { 1 2 36 79672281 1 13 6 } } 1373 1374 When allComponentsMatch is used in a ComponentAssertion the assertion 1375 syntax is the same as the ASN.1 type of the identified component. 1376 Otherwise, the assertion syntax of allComponentsMatch is the same as 1377 the attribute syntax of the attribute to which the matching rule is 1378 applied. 1379 1380 Broadly speaking, this matching rule evaluates to true if and only if 1381 corresponding components of the assertion value and the attribute or 1382 component value are the same. 1383 1384 In detail, equality is determined by the following cases applied 1385 recursively. 1386 1387 a) Two values of a SET or SEQUENCE type are the same if and only if, 1388 for each component type, the corresponding component values are 1389 either, 1390 1391 1) both absent, 1392 1393 2) both present and the same, or 1394 1395 3) absent or the same as the DEFAULT value for the component, if a 1396 DEFAULT value is defined. 1397 1398 1399 1400 1401 1402Legg Standards Track [Page 25] 1403 1404RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1405 1406 1407 Values of an EMBEDDED PDV, EXTERNAL, unrestricted CHARACTER 1408 STRING, or INSTANCE OF type are compared according to their 1409 respective associated SEQUENCE type (see Section 3.1.2). 1410 1411 b) Two values of a SEQUENCE OF type are the same if and only if, the 1412 values have the same number of (possibly duplicated) instances and 1413 corresponding instances are the same. 1414 1415 c) Two values of a SET OF type are the same if and only if, the 1416 values have the same number of instances and each distinct 1417 instance occurs in both values the same number of times, i.e., 1418 both values have the same instances, including duplicates, but in 1419 any order. 1420 1421 d) Two values of a CHOICE type are the same if and only if, both 1422 values are of the same chosen alternative and the component values 1423 are the same. 1424 1425 e) Two BIT STRING values are the same if and only if the values have 1426 the same number of bits and corresponding bits are the same. If 1427 the BIT STRING type is defined with a named bit list then trailing 1428 zero bits in the values are treated as absent for the purposes of 1429 this comparison. 1430 1431 f) Two BOOLEAN values are the same if and only if both are TRUE or 1432 both are FALSE. 1433 1434 g) Two values of a string type are the same if and only if the values 1435 have the same number of characters and corresponding characters 1436 are the same. Letter case is significant. For the purposes of 1437 allComponentsMatch, the string types are NumericString, 1438 PrintableString, TeletexString (T61String), VideotexString, 1439 IA5String, GraphicString, VisibleString (ISO646String), 1440 GeneralString, UniversalString, BMPString, UTF8String, 1441 GeneralizedTime, UTCTime and ObjectDescriptor. 1442 1443 h) Two INTEGER values are the same if and only if the integers are 1444 equal. 1445 1446 i) Two ENUMERATED values are the same if and only if the enumeration 1447 item identifiers are the same (equivalently, if the integer values 1448 associated with the identifiers are equal). 1449 1450 j) Two NULL values are always the same, unconditionally. 1451 1452 k) Two OBJECT IDENTIFIER values are the same if and only if the 1453 values have the same number of arcs and corresponding arcs are the 1454 same. 1455 1456 1457 1458Legg Standards Track [Page 26] 1459 1460RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1461 1462 1463 l) Two OCTET STRING values are the same if and only if the values 1464 have the same number of octets and corresponding octets are the 1465 same. 1466 1467 m) Two REAL values are the same if and only if they are both the same 1468 special value, or neither is a special value and they have the 1469 same base and represent the same real number. The special values 1470 for REAL are zero, PLUS-INFINITY and MINUS-INFINITY. 1471 1472 n) Two RELATIVE-OID values are the same if and only if the values 1473 have the same number of arcs and corresponding arcs are the same. 1474 The respective starting nodes for the RELATIVE-OID values are 1475 disregarded in the comparison, i.e., they are assumed to be the 1476 same. 1477 1478 o) Two values of an open type are the same if and only if both are of 1479 the same ASN.1 type and are the same according to that type. If 1480 the actual ASN.1 type of the values is unknown then the 1481 allComponentsMatch rule evaluates to Undefined. 1482 1483 Tags and constraints, being part of the type definition and not part 1484 of the abstract values, are ignored for matching purposes. 1485 1486 The allComponentsMatch rule may be used as the defined equality 1487 matching rule for an attribute. 1488 14896.3. Deriving Component Equality Matching Rules 1490 1491 A new component equality matching rule with more refined matching 1492 semantics may be derived from allComponentsMatch, or any other 1493 component equality matching rule, using the convention described in 1494 this section. 1495 1496 The matching behaviour of a derived component equality matching rule 1497 is specified by nominating, for each of one or more identified 1498 components, a commutative equality matching rule that will be used to 1499 match values of that component. This overrides the matching that 1500 would otherwise occur for values of that component using the base 1501 rule for the derivation. These overrides can be conveniently 1502 represented as rows in a table of the following form. 1503 1504 Component | Matching Rule 1505 ============+=============== 1506 | 1507 | 1508 1509 1510 1511 1512 1513 1514Legg Standards Track [Page 27] 1515 1516RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1517 1518 1519 Usually, all component values of a particular ASN.1 type are to be 1520 matched the same way. An ASN.1 type reference (e.g., 1521 DistinguishedName) or an ASN.1 built-in type name (e.g., INTEGER) in 1522 the Component column of the table specifies that the nominated 1523 equality matching rule is to be applied to all values of the named 1524 type, regardless of context. 1525 1526 An ASN.1 type reference with a component reference appended 1527 (separated by a ".") specifies that the nominated matching rule 1528 applies only to the identified components of values of the named 1529 type. Other component values that happen to be of the same ASN.1 1530 type are not selected. 1531 1532 Additional type substitutions as described in Section 3.2 are assumed 1533 to be performed to align the component type with the matching rule 1534 assertion syntax. 1535 1536 Conceptually, the rows in a table for the base rule are appended to 1537 the rows in the table for a derived rule for the purpose of deciding 1538 the matching semantics of the derived rule. Notionally, 1539 allComponentsMatch has an empty table. 1540 1541 A row specifying values of an outer containing type (e.g., 1542 DistinguishedName) takes precedence over a row specifying values of 1543 an inner component type (e.g., RelativeDistinguishedName), regardless 1544 of their order in the table. Specifying a row for component values 1545 of an inner type is only useful if a value of the type can also 1546 appear on its own, or as a component of values of a different outer 1547 type. For example, if there is a row for DistinguishedName then a 1548 row for RelativeDistinguishedName can only ever apply to 1549 RelativeDistinguishedName component values that are not part of a 1550 DistinguishedName. A row for values of an outer type in the table 1551 for the base rule takes precedence over a row for values of an inner 1552 type in the table for the derived rule. 1553 1554 Where more than one row applies to a particular component value the 1555 earlier row takes precedence over the later row. Thus rows in the 1556 table for the derived rule take precedence over any rows for the same 1557 component in the table for the base rule. 1558 15596.4. The directoryComponentsMatch Matching Rule 1560 1561 The directoryComponentsMatch matching rule is derived from the 1562 allComponentsMatch matching rule. 1563 1564 1565 1566 1567 1568 1569 1570Legg Standards Track [Page 28] 1571 1572RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1573 1574 1575 The LDAP-style definition for directoryComponentsMatch is: 1576 1577 ( 1.2.36.79672281.1.13.7 NAME 'directoryComponentsMatch' 1578 SYNTAX 1.2.36.79672281.1.5.3 ) 1579 1580 The X.500-style definition for directoryComponentsMatch is: 1581 1582 directoryComponentsMatch MATCHING-RULE ::= { 1583 ID { 1 2 36 79672281 1 13 7 } } 1584 1585 The matching semantics of directoryComponentsMatch are described by 1586 the following table, using the convention described in Section 6.3. 1587 1588 ASN.1 Type | Matching Rule 1589 =========================================+======================== 1590 RDNSequence | distinguishedNameMatch 1591 RelativeDistinguishedName | rdnMatch 1592 TelephoneNumber | telephoneNumberMatch 1593 FacsimileTelephoneNumber.telephoneNumber | telephoneNumberMatch 1594 NumericString | numericStringMatch 1595 GeneralizedTime | generalizedTimeMatch 1596 UTCTime | uTCTimeMatch 1597 DirectoryString{} | caseIgnoreMatch 1598 BMPString | caseIgnoreMatch 1599 GeneralString | caseIgnoreMatch 1600 GraphicString | caseIgnoreMatch 1601 IA5String | caseIgnoreMatch 1602 PrintableString | caseIgnoreMatch 1603 TeletexString | caseIgnoreMatch 1604 UniversalString | caseIgnoreMatch 1605 UTF8String | caseIgnoreMatch 1606 VideotexString | caseIgnoreMatch 1607 VisibleString | caseIgnoreMatch 1608 1609 Notes: 1610 1611 1) The DistinguishedName type is defined by assignment to be the same 1612 as the RDNSequence type. Some types (e.g., Name and LocalName) 1613 directly reference RDNSequence rather than DistinguishedName. 1614 Specifying RDNSequence captures all these DN-like types. 1615 1616 2) A RelativeDistinguishedName value is only matched by rdnMatch if 1617 it is not part of an RDNSequence value. 1618 1619 3) The telephone number component of the FacsimileTelephoneNumber 1620 ASN.1 type [12] is defined as a constrained PrintableString. 1621 PrintableString component values that are part of a 1622 FacsimileTelephoneNumber value can be identified separately from 1623 1624 1625 1626Legg Standards Track [Page 29] 1627 1628RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1629 1630 1631 other components of PrintableString type by the specifier 1632 FacsimileTelephoneNumber.telephoneNumber, so that 1633 telephoneNumberMatch can be selectively applied. The fourth 1634 edition of X.520 defines the telephoneNumber component of 1635 FacsimileTelephoneNumber to be of the type TelephoneNumber, making 1636 the row for FacsimileTelephoneNumber.telephoneNumber components 1637 redundant. 1638 1639 The directoryComponentsMatch rule may be used as the defined equality 1640 matching rule for an attribute. 1641 16427. Component Matching Examples 1643 1644 This section contains examples of search filters using the 1645 componentFilterMatch matching rule. The filters are described using 1646 the string representation of LDAP search filters [18]. Note that 1647 this representation requires asterisks to be escaped in assertion 1648 values (in these examples the assertion values are all 1649 <ComponentAssertion> encodings). The asterisks have not been escaped 1650 in these examples for the sake of clarity, and to avoid confusing the 1651 protocol representation of LDAP search filter assertion values, where 1652 such escaping does not apply. Line breaks and indenting have been 1653 added only as an aid to readability. 1654 1655 The example search filters using componentFilterMatch are all single 1656 extensible match filter items, though there is no reason why 1657 componentFilterMatch can't be used in more complicated search 1658 filters. 1659 1660 The first examples describe searches over the objectClasses schema 1661 operational attribute, which has an attribute syntax described by the 1662 ASN.1 type ObjectClassDescription [10], and holds the definitions of 1663 the object classes known to a directory server. The definition of 1664 ObjectClassDescription is as follows: 1665 1666 ObjectClassDescription ::= SEQUENCE { 1667 identifier OBJECT-CLASS.&id, 1668 name SET OF DirectoryString {ub-schema} OPTIONAL, 1669 description DirectoryString {ub-schema} OPTIONAL, 1670 obsolete BOOLEAN DEFAULT FALSE, 1671 information [0] ObjectClassInformation } 1672 1673 ObjectClassInformation ::= SEQUENCE { 1674 subclassOf SET OF OBJECT-CLASS.&id OPTIONAL, 1675 kind ObjectClassKind DEFAULT structural, 1676 mandatories [3] SET OF ATTRIBUTE.&id OPTIONAL, 1677 optionals [4] SET OF ATTRIBUTE.&id OPTIONAL } 1678 1679 1680 1681 1682Legg Standards Track [Page 30] 1683 1684RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1685 1686 1687 ObjectClassKind ::= ENUMERATED { 1688 abstract (0), 1689 structural (1), 1690 auxiliary (2) } 1691 1692 OBJECT-CLASS.&id and ATTRIBUTE.&id are equivalent to the OBJECT 1693 IDENTIFIER ASN.1 type. A value of OBJECT-CLASS.&id is an OBJECT 1694 IDENTIFIER for an object class. A value of ATTRIBUTE.&id is an 1695 OBJECT IDENTIFIER for an attribute type. 1696 1697 The following search filter finds the object class definition for the 1698 object class identified by the OBJECT IDENTIFIER 2.5.6.18: 1699 1700 (objectClasses:componentFilterMatch:= 1701 item:{ component "identifier", 1702 rule objectIdentifierMatch, value 2.5.6.18 }) 1703 1704 A match on the "identifier" component of objectClasses values is 1705 equivalent to the objectIdentifierFirstComponentMatch matching rule 1706 applied to attribute values of the objectClasses attribute type. The 1707 componentFilterMatch matching rule subsumes the functionality of the 1708 objectIdentifierFirstComponentMatch, integerFirstComponentMatch and 1709 directoryStringFirstComponentMatch matching rules. 1710 1711 The following search filter finds the object class definition for the 1712 object class called foobar: 1713 1714 (objectClasses:componentFilterMatch:= 1715 item:{ component "name.*", 1716 rule caseIgnoreMatch, value "foobar" }) 1717 1718 An object class definition can have multiple names and the above 1719 filter will match an objectClasses value if any one of the names is 1720 "foobar". 1721 1722 The component reference "name.0" identifies the notional count of the 1723 number of names in an object class definition. The following search 1724 filter finds object class definitions with exactly one name: 1725 1726 (objectClasses:componentFilterMatch:= 1727 item:{ component "name.0", rule integerMatch, value 1 }) 1728 1729 The "description" component of an ObjectClassDescription is defined 1730 to be an OPTIONAL DirectoryString. The following search filter finds 1731 object class definitions that have descriptions, regardless of the 1732 contents of the description string: 1733 1734 1735 1736 1737 1738Legg Standards Track [Page 31] 1739 1740RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1741 1742 1743 (objectClasses:componentFilterMatch:= 1744 item:{ component "description", 1745 rule presentMatch, value NULL }) 1746 1747 The presentMatch returns TRUE if the description component is present 1748 and FALSE otherwise. 1749 1750 The following search filter finds object class definitions that don't 1751 have descriptions: 1752 1753 (objectClasses:componentFilterMatch:= 1754 not:item:{ component "description", 1755 rule presentMatch, value NULL }) 1756 1757 The following search filter finds object class definitions with the 1758 word "bogus" in the description: 1759 1760 (objectClasses:componentFilterMatch:= 1761 item:{ component "description", 1762 rule caseIgnoreSubstringsMatch, 1763 value { any:"bogus" } }) 1764 1765 The assertion value is of the SubstringAssertion syntax, i.e., 1766 1767 SubstringAssertion ::= SEQUENCE OF CHOICE { 1768 initial [0] DirectoryString {ub-match}, 1769 any [1] DirectoryString {ub-match}, 1770 final [2] DirectoryString {ub-match} } 1771 1772 The "obsolete" component of an ObjectClassDescription is defined to 1773 be DEFAULT FALSE. An object class is obsolete if the "obsolete" 1774 component is present and set to TRUE. The following search filter 1775 finds all obsolete object classes: 1776 1777 (objectClasses:componentFilterMatch:= 1778 item:{ component "obsolete", rule booleanMatch, value TRUE }) 1779 1780 An object class is not obsolete if the "obsolete" component is not 1781 present, in which case it defaults to FALSE, or is present but is 1782 explicitly set to FALSE. The following search filter finds all non- 1783 obsolete object classes: 1784 1785 (objectClasses:componentFilterMatch:= 1786 item:{ component "obsolete", rule booleanMatch, value FALSE }) 1787 1788 The useDefaultValues flag in the ComponentAssertion defaults to TRUE 1789 so the componentFilterMatch rule treats an absent "obsolete" 1790 component as being present and set to FALSE. The following search 1791 1792 1793 1794Legg Standards Track [Page 32] 1795 1796RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1797 1798 1799 filter finds only object class definitions where the "obsolete" 1800 component has been explicitly set to FALSE, rather than implicitly 1801 defaulting to FALSE: 1802 1803 (objectClasses:componentFilterMatch:= 1804 item:{ component "obsolete", useDefaultValues FALSE, 1805 rule booleanMatch, value FALSE }) 1806 1807 With the useDefaultValues flag set to FALSE, if the "obsolete" 1808 component is absent the component reference identifies no component 1809 value and the matching rule will return FALSE. The matching rule can 1810 only return TRUE if the component is present and set to FALSE. 1811 1812 The "information.kind" component of the ObjectClassDescription is an 1813 ENUMERATED type. The allComponentsMatch matching rule can be used to 1814 match values of an ENUMERATED type. The following search filter 1815 finds object class definitions for auxiliary object classes: 1816 1817 (objectClasses:componentFilterMatch:= 1818 item:{ component "information.kind", 1819 rule allComponentsMatch, value auxiliary }) 1820 1821 The following search filter finds auxiliary object classes with 1822 commonName (cn or 2.5.4.3) as a mandatory attribute: 1823 1824 (objectClasses:componentFilterMatch:=and:{ 1825 item:{ component "information.kind", 1826 rule allComponentsMatch, value auxiliary }, 1827 item:{ component "information.mandatories.*", 1828 rule objectIdentifierMatch, value cn } }) 1829 1830 The following search filter finds auxiliary object classes with 1831 commonName as a mandatory or optional attribute: 1832 1833 (objectClasses:componentFilterMatch:=and:{ 1834 item:{ component "information.kind", 1835 rule allComponentsMatch, value auxiliary }, 1836 or:{ 1837 item:{ component "information.mandatories.*", 1838 rule objectIdentifierMatch, value cn }, 1839 item:{ component "information.optionals.*", 1840 rule objectIdentifierMatch, value cn } } }) 1841 1842 Extra care is required when matching optional SEQUENCE OF or SET OF 1843 components because of the distinction between an absent list of 1844 instances and a present, but empty, list of instances. The following 1845 search filter finds object class definitions with less than three 1846 1847 1848 1849 1850Legg Standards Track [Page 33] 1851 1852RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1853 1854 1855 names, including object class definitions with a present but empty 1856 list of names, but does not find object class definitions with an 1857 absent list of names: 1858 1859 (objectClasses:componentFilterMatch:= 1860 item:{ component "name.0", 1861 rule integerOrderingMatch, value 3 }) 1862 1863 If the "name" component is absent the "name.0" component is also 1864 considered to be absent and the ComponentAssertion evaluates to 1865 FALSE. If the "name" component is present, but empty, the "name.0" 1866 component is also present and equal to zero, so the 1867 ComponentAssertion evaluates to TRUE. To also find the object class 1868 definitions with an absent list of names the following search filter 1869 would be used: 1870 1871 (objectClasses:componentFilterMatch:=or:{ 1872 not:item:{ component "name", rule presentMatch, value NULL }, 1873 item:{ component "name.0", 1874 rule integerOrderingMatch, value 3 } }) 1875 1876 Distinguished names embedded in other syntaxes can be matched with a 1877 componentFilterMatch. The uniqueMember attribute type has an 1878 attribute syntax described by the ASN.1 type NameAndOptionalUID. 1879 1880 NameAndOptionalUID ::= SEQUENCE { 1881 dn DistinguishedName, 1882 uid UniqueIdentifier OPTIONAL } 1883 1884 The following search filter finds values of the uniqueMember 1885 attribute containing the author's DN: 1886 1887 (uniqueMember:componentFilterMatch:= 1888 item:{ component "dn", 1889 rule distinguishedNameMatch, 1890 value "cn=Steven Legg,o=Adacel,c=AU" }) 1891 1892 The DistinguishedName and RelativeDistinguishedName ASN.1 types are 1893 also complex ASN.1 types so the component matching rules can be 1894 applied to their inner components. 1895 1896 DistinguishedName ::= RDNSequence 1897 1898 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 1899 1900 RelativeDistinguishedName ::= SET SIZE (1..MAX) OF 1901 AttributeTypeAndValue 1902 1903 1904 1905 1906Legg Standards Track [Page 34] 1907 1908RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1909 1910 1911 AttributeTypeAndValue ::= SEQUENCE { 1912 type AttributeType ({SupportedAttributes}), 1913 value AttributeValue ({SupportedAttributes}{@type}) } 1914 1915 AttributeType ::= ATTRIBUTE.&id 1916 1917 AttributeValue ::= ATTRIBUTE.&Type 1918 1919 ATTRIBUTE.&Type is an open type. A value of ATTRIBUTE.&Type is 1920 constrained by the type component of AttributeTypeAndValue to be of 1921 the attribute syntax of the nominated attribute type. Note: the 1922 fourth edition of X.500 extends and renames the AttributeTypeAndValue 1923 SEQUENCE type. 1924 1925 The seeAlso attribute has the DistinguishedName syntax. The 1926 following search filter finds seeAlso attribute values containing the 1927 RDN, "o=Adacel", anywhere in the DN: 1928 1929 (seeAlso:componentFilterMatch:= 1930 item:{ component "*", rule rdnMatch, value "o=Adacel" }) 1931 1932 The following search filter finds all seeAlso attribute values with 1933 "cn=Steven Legg" as the RDN of the named entry (i.e., the "first" RDN 1934 in an LDAPDN or the "last" RDN in an X.500 DN): 1935 1936 (seeAlso:componentFilterMatch:= 1937 item:{ component "-1", 1938 rule rdnMatch, value "cn=Steven Legg" }) 1939 1940 The following search filter finds all seeAlso attribute values naming 1941 entries in the DIT subtree of "o=Adacel,c=AU": 1942 1943 (seeAlso:componentFilterMatch:=and:{ 1944 item:{ component "1", rule rdnMatch, value "c=AU" }, 1945 item:{ component "2", rule rdnMatch, value "o=Adacel" } }) 1946 1947 The following search filter finds all seeAlso attribute values 1948 containing the naming attribute types commonName (cn) and 1949 telephoneNumber in the same RDN: 1950 1951 (seeAlso:componentFilterMatch:= 1952 item:{ component "*", rule componentFilterMatch, 1953 value and:{ 1954 item:{ component "*.type", 1955 rule objectIdentifierMatch, value cn }, 1956 item:{ component "*.type", 1957 rule objectIdentifierMatch, 1958 value telephoneNumber } } }) 1959 1960 1961 1962Legg Standards Track [Page 35] 1963 1964RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1965 1966 1967 The following search filter would find all seeAlso attribute values 1968 containing the attribute types commonName and telephoneNumber, but 1969 not necessarily in the same RDN: 1970 1971 (seeAlso:componentFilterMatch:=and:{ 1972 item:{ component "*.*.type", 1973 rule objectIdentifierMatch, value cn }, 1974 item:{ component "*.*.type", 1975 rule objectIdentifierMatch, value telephoneNumber } }) 1976 1977 The following search filter finds all seeAlso attribute values 1978 containing the word "Adacel" in any organizationalUnitName (ou) 1979 attribute value in any AttributeTypeAndValue of any RDN: 1980 1981 (seeAlso:componentFilterMatch:= 1982 item:{ component "*.*.value.(2.5.4.11)", 1983 rule caseIgnoreSubstringsMatch, 1984 value { any:"Adacel" } }) 1985 1986 The component reference "*.*.value" identifies an open type, in this 1987 case an attribute value. In a particular AttributeTypeAndValue, if 1988 the attribute type is not organizationalUnitName then the 1989 ComponentAssertion evaluates to FALSE. Otherwise the substring 1990 assertion is evaluated against the attribute value. 1991 1992 Absent component references in ComponentAssertions can be exploited 1993 to avoid false positive matches on multi-valued attributes. For 1994 example, suppose there is a multi-valued attribute named 1995 productCodes, defined to have the Integer syntax 1996 (1.3.6.1.4.1.1466.115.121.1.27). Consider the following search 1997 filter: 1998 1999 (&(!(productCodes:integerOrderingMatch:=3)) 2000 (productCodes:integerOrderingMatch:=8)) 2001 2002 An entry whose productCodes attribute contains only the values 1 and 2003 10 will match the above filter. The first subfilter is satisfied by 2004 the value 10 (10 is not less than 3), and the second subfilter is 2005 satisfied by the value 1 (1 is less than 8). The following search 2006 filter can be used instead to only match entries that have a 2007 productCodes value in the range 3 to 7, because the ComponentFilter 2008 is evaluated against each productCodes value in isolation: 2009 2010 (productCodes:componentFilterMatch:= and:{ 2011 not:item:{ rule integerOrderingMatch, value 3 }, 2012 item:{ rule integerOrderingMatch, value 8 } }) 2013 2014 2015 2016 2017 2018Legg Standards Track [Page 36] 2019 2020RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2021 2022 2023 An entry whose productCodes attribute contains only the values 1 and 2024 10 will not match the above filter. 2025 20268. Security Considerations 2027 2028 The component matching rules described in this document allow for a 2029 compact specification of matching capabilities that could otherwise 2030 have been defined by a plethora of specific matching rules, i.e., 2031 despite their expressiveness and flexibility the component matching 2032 rules do not behave in a way uncharacteristic of other matching 2033 rules, so the security issues for component matching rules are no 2034 different than for any other matching rule. However, because the 2035 component matching rules are applicable to any attribute syntax, 2036 support for them in a directory server may allow searching of 2037 attributes that were previously unsearchable by virtue of there not 2038 being a suitable matching rule. Such attribute types ought to be 2039 properly protected with appropriate access controls. A generic, 2040 interoperable access control mechanism has not yet been developed, 2041 however, and implementors should be aware of the interaction of that 2042 lack with the increased risk of exposure described above. 2043 20449. Acknowledgements 2045 2046 The author would like to thank Tom Gindin for private email 2047 discussions that clarified and refined the ideas presented in this 2048 document. 2049 205010. IANA Considerations 2051 2052 The Internet Assigned Numbers Authority (IANA) has updated the LDAP 2053 descriptors registry [8] as indicated by the following templates: 2054 2055 Subject: Request for LDAP Descriptor Registration 2056 Descriptor (short name): componentFilterMatch 2057 Object Identifier: 1.2.36.79672281.1.13.2 2058 Person & email address to contact for further information: 2059 Steven Legg <steven.legg@adacel.com.au> 2060 Usage: other (matching rule) 2061 Specification: RFC 3687 2062 Author/Change Controller: IESG 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074Legg Standards Track [Page 37] 2075 2076RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2077 2078 2079 Subject: Request for LDAP Descriptor Registration 2080 Descriptor (short name): rdnMatch 2081 Object Identifier: 1.2.36.79672281.1.13.3 2082 Person & email address to contact for further information: 2083 Steven Legg <steven.legg@adacel.com.au> 2084 Usage: other (matching rule) 2085 Specification: RFC 3687 2086 Author/Change Controller: IESG 2087 2088 Subject: Request for LDAP Descriptor Registration 2089 Descriptor (short name): presentMatch 2090 Object Identifier: 1.2.36.79672281.1.13.5 2091 Person & email address to contact for further information: 2092 Steven Legg <steven.legg@adacel.com.au> 2093 Usage: other (matching rule) 2094 Specification: RFC 3687 2095 Author/Change Controller: IESG 2096 2097 Subject: Request for LDAP Descriptor Registration 2098 Descriptor (short name): allComponentsMatch 2099 Object Identifier: 1.2.36.79672281.1.13.6 2100 Person & email address to contact for further information: 2101 Steven Legg <steven.legg@adacel.com.au> 2102 Usage: other (matching rule) 2103 Specification: RFC 3687 2104 Author/Change Controller: IESG 2105 2106 Subject: Request for LDAP Descriptor Registration 2107 Descriptor (short name): directoryComponentsMatch 2108 Object Identifier: 1.2.36.79672281.1.13.7 2109 Person & email address to contact for further information: 2110 Steven Legg <steven.legg@adacel.com.au> 2111 Usage: other (matching rule) 2112 Specification: RFC 3687 2113 Author/Change Controller: IESG 2114 2115 The object identifiers have been assigned for use in this 2116 specification by Adacel Technologies, under an arc assigned to Adacel 2117 by Standards Australia. 2118 211911. References 2120 212111.1. Normative References 2122 2123 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2124 Levels", BCP 14, RFC 2119, March 1997. 2125 2126 2127 2128 2129 2130Legg Standards Track [Page 38] 2131 2132RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2133 2134 2135 [2] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2136 Specifications: ABNF", RFC 2234, November 1997. 2137 2138 [3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access 2139 Protocol (v3)", RFC 2251, December 1997. 2140 2141 [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight 2142 Directory Access Protocol (v3): Attribute Syntax Definitions", 2143 RFC 2252, December 1997. 2144 2145 [5] Wahl, M., Kille S. and T. Howes. "Lightweight Directory Access 2146 Protocol (v3): UTF-8 String Representation of Distinguished 2147 Names", RFC 2253, December 1997. 2148 2149 [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 2150 63, RFC 3629, November 2003. 2151 2152 [7] Hodges, J. and R. Morgan, "Lightweight Directory Access 2153 Protocol (v3): Technical Specification", RFC 3377, September 2154 2002. 2155 2156 [8] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 2157 Considerations for the Lightweight Directory Access Protocol 2158 (LDAP)", BCP 64, RFC 3383, September 2002. 2159 2160 [9] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 2161 Types", RFC 3641, October 2003. 2162 2163 [10] ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1994, 2164 Information Technology - Open Systems Interconnection - The 2165 Directory: Models 2166 2167 [11] ITU-T Recommendation X.509 (1997) | ISO/IEC 9594-8:1998, 2168 Information Technology - Open Systems Interconnection - The 2169 Directory: Authentication Framework 2170 2171 [12] ITU-T Recommendation X.520 (1993) | ISO/IEC 9594-6:1994, 2172 Information technology - Open Systems Interconnection - The 2173 Directory: Selected attribute types 2174 2175 [13] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1:2002, 2176 Information technology - Abstract Syntax Notation One (ASN.1): 2177 Specification of basic notation 2178 2179 [14] ITU-T Recommendation X.681 (07/02) | ISO/IEC 8824-2:2002, 2180 Information technology - Abstract Syntax Notation One (ASN.1): 2181 Information object specification 2182 2183 2184 2185 2186Legg Standards Track [Page 39] 2187 2188RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2189 2190 2191 [15] ITU-T Recommendation X.682 (07/02) | ISO/IEC 8824-3:2002, 2192 Information technology - Abstract Syntax Notation One (ASN.1): 2193 Constraint specification 2194 2195 [16] ITU-T Recommendation X.683 (07/02) | ISO/IEC 8824-4:2002, 2196 Information technology - Abstract Syntax Notation One (ASN.1): 2197 Parameterization of ASN.1 specifications 2198 2199 [17] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, 2200 Information technology - ASN.1 encoding rules: Specification of 2201 Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and 2202 Distinguished Encoding Rules (DER) 2203 220412.2. Informative References 2205 2206 [18] Howes, T., "The String Representation of LDAP Search Filters", 2207 RFC 2254, December 1997. 2208 2209 [19] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994, 2210 Information Technology - Open Systems Interconnection - The 2211 Directory: Overview of concepts, models and services 2212 221312. Intellectual Property Statement 2214 2215 The IETF takes no position regarding the validity or scope of any 2216 intellectual property or other rights that might be claimed to 2217 pertain to the implementation or use of the technology described in 2218 this document or the extent to which any license under such rights 2219 might or might not be available; neither does it represent that it 2220 has made any effort to identify any such rights. Information on the 2221 IETF's procedures with respect to rights in standards-track and 2222 standards-related documentation can be found in BCP-11. Copies of 2223 claims of rights made available for publication and any assurances of 2224 licenses to be made available, or the result of an attempt made to 2225 obtain a general license or permission for the use of such 2226 proprietary rights by implementors or users of this specification can 2227 be obtained from the IETF Secretariat. 2228 2229 The IETF invites any interested party to bring to its attention any 2230 copyrights, patents or patent applications, or other proprietary 2231 rights which may cover technology that may be required to practice 2232 this standard. Please address the information to the IETF Executive 2233 Director. 2234 2235 2236 2237 2238 2239 2240 2241 2242Legg Standards Track [Page 40] 2243 2244RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2245 2246 224713. Author's Address 2248 2249 Steven Legg 2250 Adacel Technologies Ltd. 2251 250 Bay Street 2252 Brighton, Victoria 3186 2253 AUSTRALIA 2254 2255 Phone: +61 3 8530 7710 2256 Fax: +61 3 8530 7888 2257 EMail: steven.legg@adacel.com.au 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298Legg Standards Track [Page 41] 2299 2300RFC 3687 LDAP and X.500 Component Matching Rules February 2004 2301 2302 230314. Full Copyright Statement 2304 2305 Copyright (C) The Internet Society (2004). All Rights Reserved. 2306 2307 This document and translations of it may be copied and furnished to 2308 others, and derivative works that comment on or otherwise explain it 2309 or assist in its implementation may be prepared, copied, published 2310 and distributed, in whole or in part, without restriction of any 2311 kind, provided that the above copyright notice and this paragraph are 2312 included on all such copies and derivative works. However, this 2313 document itself may not be modified in any way, such as by removing 2314 the copyright notice or references to the Internet Society or other 2315 Internet organizations, except as needed for the purpose of 2316 developing Internet standards in which case the procedures for 2317 copyrights defined in the Internet Standards process must be 2318 followed, or as required to translate it into languages other than 2319 English. 2320 2321 The limited permissions granted above are perpetual and will not be 2322 revoked by the Internet Society or its successors or assignees. 2323 2324 This document and the information contained herein is provided on an 2325 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 2326 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 2327 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 2328 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 2329 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2330 2331Acknowledgement 2332 2333 Funding for the RFC Editor function is currently provided by the 2334 Internet Society. 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354Legg Standards Track [Page 42] 2355 2356