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