can be used for equality matching of values of the ENUMERATED, NULL,
REAL and RELATIVE-OID ASN.1 types, among other things.
4. ComponentFilter
The ComponentAssertion allows the value(s) of any one component type
in a complex ASN.1 type to be matched, but there is often a desire to
match the values of more than one component type. A ComponentFilter
is an assertion about the presence, or values of, multiple components
within an ASN.1 value.
The ComponentFilter assertion, an expression of ComponentAssertions,
evaluates to either TRUE, FALSE or Undefined for each tested ASN.1
value.
A ComponentFilter is described by the following ASN.1 type (assumed
to be defined with "EXPLICIT TAGS" in force):
ComponentFilter ::= CHOICE {
item [0] ComponentAssertion,
and [1] SEQUENCE OF ComponentFilter,
or [2] SEQUENCE OF ComponentFilter,
not [3] ComponentFilter }
Note: despite the use of SEQUENCE OF instead of SET OF for the "and"
and "or" alternatives in ComponentFilter, the order of the component
filters is not significant.
A ComponentFilter that is a ComponentAssertion evaluates to TRUE if
the ComponentAssertion is TRUE, evaluates to FALSE if the
ComponentAssertion is FALSE, and evaluates to Undefined otherwise.
The "and" of a sequence of component filters evaluates to TRUE if the
sequence is empty or if each component filter evaluates to TRUE,
evaluates to FALSE if at least one component filter is FALSE, and
evaluates to Undefined otherwise.
The "or" of a sequence of component filters evaluates to FALSE if the
sequence is empty or if each component filter evaluates to FALSE,
evaluates to TRUE if at least one component filter is TRUE, and
evaluates to Undefined otherwise.
The "not" of a component filter evaluates to TRUE if the component
filter is FALSE, evaluates to FALSE if the component filter is TRUE,
and evaluates to Undefined otherwise.
5. The componentFilterMatch Matching Rule
The componentFilterMatch matching rule allows a ComponentFilter to be
applied to an attribute value. The result of the matching rule is
the result of applying the ComponentFilter to the attribute value.
The LDAP-style definitions for componentFilterMatch and its assertion
syntax are:
( 1.2.36.79672281.1.13.2 NAME ’componentFilterMatch’
SYNTAX 1.2.36.79672281.1.5.2 )
( 1.2.36.79672281.1.5.2 DESC ’ComponentFilter’ )
The LDAP-specific encoding for the ComponentFilter assertion syntax
is specified by GSER [9].
As a convenience to implementors, an equivalent ABNF description of
the GSER encoding for ComponentFilter is provided here. In the event
that there is a discrepancy between this ABNF and the encoding
determined by GSER, GSER is to be taken as definitive. The GSER
encoding of a ComponentFilter is described by the following
equivalent ABNF:
ComponentFilter = filter-item /
and-filter /
or-filter /
not-filter
filter-item = item-chosen ComponentAssertion
and-filter = and-chosen SequenceOfComponentFilter
or-filter = or-chosen SequenceOfComponentFilter
not-filter = not-chosen ComponentFilter
item-chosen = %x69.74.65.6D.3A ; "item:"
and-chosen = %x61.6E.64.3A ; "and:"
or-chosen = %x6F.72.3A ; "or:"
not-chosen = %x6E.6F.74.3A ; "not:"
SequenceOfComponentFilter = "{" [ sp ComponentFilter
*( "," sp ComponentFilter) ] sp "}"
ComponentAssertion = "{" [ sp component "," ]
[ sp useDefaultValues "," ]
sp rule ","
sp assertion-value sp "}"
component = component-label msp StringValue
useDefaultValues = use-defaults-label msp BooleanValue
rule = rule-label msp ObjectIdentifierValue
assertion-value = value-label msp Value
component-label = %x63.6F.6D.70.6F.6E.65.6E.74 ; "component"
use-defaults-label = %x75.73.65.44.65.66.61.75.6C.74.56.61.6C.75
%x65.73 ; "useDefaultValues"
rule-label = %x72.75.6C.65 ; "rule"
value-label = %x76.61.6C.75.65 ; "value"
sp = *%x20 ; zero, one or more space characters
msp = 1*%x20 ; one or more space characters
The ABNF for <Value>, <StringValue>, <ObjectIdentifierValue> and
<BooleanValue> is defined by GSER [9].
The ABNF descriptions of LDAP-specific encodings for attribute
syntaxes typically do not clearly or consistently delineate the
component parts of an attribute value. A regular and uniform
character string encoding for arbitrary component data types is
needed to encode the assertion value in a ComponentAssertion. The
<Value> rule from GSER provides a human readable text encoding for a
component value of any arbitrary ASN.1 type.
The X.500-style definition [10] for componentFilterMatch is:
componentFilterMatch MATCHING-RULE ::= {
SYNTAX ComponentFilter
ID { 1 2 36 79672281 1 13 2 } }
A ComponentAssertion can potentially use any matching rule, including
componentFilterMatch, so componentFilterMatch may be nested. The
component references in a nested componentFilterMatch are relative to
the component corresponding to the containing ComponentAssertion. In
Section 7, an example search on the seeAlso attribute shows this
usage.
6. Equality Matching of Complex Components
It is possible to test if an attribute value of a complex ASN.1
syntax is the same as some purported (i.e., assertion) value by using
a complicated ComponentFilter that tests if corresponding components
are the same. However, it would be more convenient to be able to
present a whole assertion value to a matching rule that could do the
component-wise comparison of an attribute value with the assertion
value for any arbitrary attribute syntax. Similarly, the ability to
do a straightforward equality comparison of a component value that is
itself of a complex ASN.1 type would also be convenient.
It would be difficult to define a single matching rule that
simultaneously satisfies all notions of what the equality matching
semantics should be. For example, in some instances a case sensitive
comparison of string components may be preferable to a case
insensitive comparison. Therefore a basic equality matching rule,
allComponentsMatch, is defined in Section 6.2, and the means to
derive new matching rules from it with slightly different equality
matching semantics are described in Section 6.3.
The directoryComponentsMatch defined in Section 6.4 is a derivation
of allComponentsMatch that suits typical uses of the directory.
Other specifications are free to derive new rules from
allComponentsMatch or directoryComponentsMatch, that suit their usage
of the directory.
The allComponentsMatch rule, the directoryComponentsMatch rule and
any matching rules derived from them are collectively called
component equality matching rules.
6.1. The OpenAssertionType Syntax
The component equality matching rules have a variable assertion
syntax. In X.500 this is indicated by omitting the optional SYNTAX
field in the MATCHING-RULE information object. The assertion syntax
then defaults to the target attribute’s syntax in actual usage,
unless the description of the matching rule says otherwise. The
SYNTAX field in the LDAP-specific encoding of a
MatchingRuleDescription is mandatory, so the OpenAssertionType syntax
is defined to fill the same role. That is, the OpenAssertionType
syntax is semantically equivalent to an omitted SYNTAX field in an
X.500 MATCHING-RULE information object. OpenAssertionType MUST NOT
be used as the attribute syntax in an attribute type definition.
Unless explicitly varied by the description of a particular matching
rule, if an OpenAssertionType assertion value appears in a
ComponentAssertion its LDAP-specific encoding is described by the
<Value> rule in GSER [9], otherwise its LDAP-specific encoding is the
encoding defined for the syntax of the attribute type to which the
matching rule with the OpenAssertionType assertion syntax is applied.
The LDAP definition for the OpenAssertionType syntax is:
( 1.2.36.79672281.1.5.3 DESC ’OpenAssertionType’ )
6.2. The allComponentsMatch Matching Rule
The LDAP-style definition for allComponentsMatch is:
( 1.2.36.79672281.1.13.6 NAME ’allComponentsMatch’
SYNTAX 1.2.36.79672281.1.5.3 )
The X.500-style definition for allComponentsMatch is:
allComponentsMatch MATCHING-RULE ::= {
ID { 1 2 36 79672281 1 13 6 } }
When allComponentsMatch is used in a ComponentAssertion the assertion
syntax is the same as the ASN.1 type of the identified component.
Otherwise, the assertion syntax of allComponentsMatch is the same as
the attribute syntax of the attribute to which the matching rule is
applied.
Broadly speaking, this matching rule evaluates to true if and only if
corresponding components of the assertion value and the attribute or
component value are the same.
In detail, equality is determined by the following cases applied
recursively.
a) Two values of a SET or SEQUENCE type are the same if and only if,
for each component type, the corresponding component values are
either,
1) both absent,
2) both present and the same, or
3) absent or the same as the DEFAULT value for the component, if a
DEFAULT value is defined.
Values of an EMBEDDED PDV, EXTERNAL, unrestricted CHARACTER
STRING, or INSTANCE OF type are compared according to their
respective associated SEQUENCE type (see Section 3.1.2).
b) Two values of a SEQUENCE OF type are the same if and only if, the
values have the same number of (possibly duplicated) instances and
corresponding instances are the same.
c) Two values of a SET OF type are the same if and only if, the
values have the same number of instances and each distinct
instance occurs in both values the same number of times, i.e.,
both values have the same instances, including duplicates, but in
any order.
d) Two values of a CHOICE type are the same if and only if, both
values are of the same chosen alternative and the component values
are the same.
e) Two BIT STRING values are the same if and only if the values have
the same number of bits and corresponding bits are the same. If
the BIT STRING type is defined with a named bit list then trailing
zero bits in the values are treated as absent for the purposes of
this comparison.
f) Two BOOLEAN values are the same if and only if both are TRUE or
both are FALSE.
g) Two values of a string type are the same if and only if the values
have the same number of characters and corresponding characters
are the same. Letter case is significant. For the purposes of
allComponentsMatch, the string types are NumericString,
PrintableString, TeletexString (T61String), VideotexString,
IA5String, GraphicString, VisibleString (ISO646String),
GeneralString, UniversalString, BMPString, UTF8String,
GeneralizedTime, UTCTime and ObjectDescriptor.
h) Two INTEGER values are the same if and only if the integers are
equal.
i) Two ENUMERATED values are the same if and only if the enumeration
item identifiers are the same (equivalently, if the integer values
associated with the identifiers are equal).
j) Two NULL values are always the same, unconditionally.
k) Two OBJECT IDENTIFIER values are the same if and only if the
values have the same number of arcs and corresponding arcs are the
same.
l) Two OCTET STRING values are the same if and only if the values
have the same number of octets and corresponding octets are the
same.
m) Two REAL values are the same if and only if they are both the same
special value, or neither is a special value and they have the
same base and represent the same real number. The special values
for REAL are zero, PLUS-INFINITY and MINUS-INFINITY.
n) Two RELATIVE-OID values are the same if and only if the values
have the same number of arcs and corresponding arcs are the same.
The respective starting nodes for the RELATIVE-OID values are
disregarded in the comparison, i.e., they are assumed to be the
same.
o) Two values of an open type are the same if and only if both are of
the same ASN.1 type and are the same according to that type. If
the actual ASN.1 type of the values is unknown then the
allComponentsMatch rule evaluates to Undefined.
Tags and constraints, being part of the type definition and not part
of the abstract values, are ignored for matching purposes.
The allComponentsMatch rule may be used as the defined equality
matching rule for an attribute.
6.3. Deriving Component Equality Matching Rules
A new component equality matching rule with more refined matching
semantics may be derived from allComponentsMatch, or any other
component equality matching rule, using the convention described in
this section.
The matching behaviour of a derived component equality matching rule
is specified by nominating, for each of one or more identified
components, a commutative equality matching rule that will be used to
match values of that component. This overrides the matching that
would otherwise occur for values of that component using the base
rule for the derivation. These overrides can be conveniently
represented as rows in a table of the following form.
Component | Matching Rule
============+===============
|
|
Usually, all component values of a particular ASN.1 type are to be
matched the same way. An ASN.1 type reference (e.g.,
DistinguishedName) or an ASN.1 built-in type name (e.g., INTEGER) in
the Component column of the table specifies that the nominated
equality matching rule is to be applied to all values of the named
type, regardless of context.
An ASN.1 type reference with a component reference appended
(separated by a ".") specifies that the nominated matching rule
applies only to the identified components of values of the named
type. Other component values that happen to be of the same ASN.1
type are not selected.
Additional type substitutions as described in Section 3.2 are assumed
to be performed to align the component type with the matching rule
assertion syntax.
Conceptually, the rows in a table for the base rule are appended to
the rows in the table for a derived rule for the purpose of deciding
the matching semantics of the derived rule. Notionally,
allComponentsMatch has an empty table.
A row specifying values of an outer containing type (e.g.,
DistinguishedName) takes precedence over a row specifying values of
an inner component type (e.g., RelativeDistinguishedName), regardless
of their order in the table. Specifying a row for component values
of an inner type is only useful if a value of the type can also
appear on its own, or as a component of values of a different outer
type. For example, if there is a row for DistinguishedName then a
row for RelativeDistinguishedName can only ever apply to
RelativeDistinguishedName component values that are not part of a
DistinguishedName. A row for values of an outer type in the table
for the base rule takes precedence over a row for values of an inner
type in the table for the derived rule.
Where more than one row applies to a particular component value the
earlier row takes precedence over the later row. Thus rows in the
table for the derived rule take precedence over any rows for the same
component in the table for the base rule.
6.4. The directoryComponentsMatch Matching Rule
The directoryComponentsMatch matching rule is derived from the
allComponentsMatch matching rule.
The LDAP-style definition for directoryComponentsMatch is:
( 1.2.36.79672281.1.13.7 NAME ’directoryComponentsMatch’
SYNTAX 1.2.36.79672281.1.5.3 )
The X.500-style definition for directoryComponentsMatch is:
directoryComponentsMatch MATCHING-RULE ::= {
ID { 1 2 36 79672281 1 13 7 } }
The matching semantics of directoryComponentsMatch are described by
the following table, using the convention described in Section 6.3.
ASN.1 Type | Matching Rule
=========================================+========================
RDNSequence | distinguishedNameMatch
RelativeDistinguishedName | rdnMatch
TelephoneNumber | telephoneNumberMatch
FacsimileTelephoneNumber.telephoneNumber | telephoneNumberMatch
NumericString | numericStringMatch
GeneralizedTime | generalizedTimeMatch
UTCTime | uTCTimeMatch
DirectoryString{} | caseIgnoreMatch
BMPString | caseIgnoreMatch
GeneralString | caseIgnoreMatch
GraphicString | caseIgnoreMatch
IA5String | caseIgnoreMatch
PrintableString | caseIgnoreMatch
TeletexString | caseIgnoreMatch
UniversalString | caseIgnoreMatch
UTF8String | caseIgnoreMatch
VideotexString | caseIgnoreMatch
VisibleString | caseIgnoreMatch
Notes:
1) The DistinguishedName type is defined by assignment to be the same
as the RDNSequence type. Some types (e.g., Name and LocalName)
directly reference RDNSequence rather than DistinguishedName.
Specifying RDNSequence captures all these DN-like types.
2) A RelativeDistinguishedName value is only matched by rdnMatch if
it is not part of an RDNSequence value.
3) The telephone number component of the FacsimileTelephoneNumber
ASN.1 type [12] is defined as a constrained PrintableString.
PrintableString component values that are part of a
FacsimileTelephoneNumber value can be identified separately from
other components of PrintableString type by the specifier
FacsimileTelephoneNumber.telephoneNumber, so that
telephoneNumberMatch can be selectively applied. The fourth
edition of X.520 defines the telephoneNumber component of
FacsimileTelephoneNumber to be of the type TelephoneNumber, making
the row for FacsimileTelephoneNumber.telephoneNumber components
redundant.
The directoryComponentsMatch rule may be used as the defined equality
matching rule for an attribute.
7. Component Matching Examples
This section contains examples of search filters using the
componentFilterMatch matching rule. The filters are described using
the string representation of LDAP search filters [18]. Note that
this representation requires asterisks to be escaped in assertion
values (in these examples the assertion values are all
<ComponentAssertion> encodings). The asterisks have not been escaped
in these examples for the sake of clarity, and to avoid confusing the
protocol representation of LDAP search filter assertion values, where
such escaping does not apply. Line breaks and indenting have been
added only as an aid to readability.
The example search filters using componentFilterMatch are all single
extensible match filter items, though there is no reason why
componentFilterMatch can’t be used in more complicated search
filters.
The first examples describe searches over the objectClasses schema
operational attribute, which has an attribute syntax described by the
ASN.1 type ObjectClassDescription [10], and holds the definitions of
the object classes known to a directory server. The definition of
ObjectClassDescription is as follows:
ObjectClassDescription ::= SEQUENCE {
identifier OBJECT-CLASS.&id,
name SET OF DirectoryString {ub-schema} OPTIONAL,
description DirectoryString {ub-schema} OPTIONAL,
obsolete BOOLEAN DEFAULT FALSE,
information [0] ObjectClassInformation }
ObjectClassInformation ::= SEQUENCE {
subclassOf SET OF OBJECT-CLASS.&id OPTIONAL,
kind ObjectClassKind DEFAULT structural,
mandatories [3] SET OF ATTRIBUTE.&id OPTIONAL,
optionals [4] SET OF ATTRIBUTE.&id OPTIONAL }
ObjectClassKind ::= ENUMERATED {
abstract (0),
structural (1),
auxiliary (2) }
OBJECT-CLASS.&id and ATTRIBUTE.&id are equivalent to the OBJECT
IDENTIFIER ASN.1 type. A value of OBJECT-CLASS.&id is an OBJECT
IDENTIFIER for an object class. A value of ATTRIBUTE.&id is an
OBJECT IDENTIFIER for an attribute type.
The following search filter finds the object class definition for the
object class identified by the OBJECT IDENTIFIER 2.5.6.18:
(objectClasses:componentFilterMatch:=
item:{ component "identifier",
rule objectIdentifierMatch, value 2.5.6.18 })
A match on the "identifier" component of objectClasses values is
equivalent to the objectIdentifierFirstComponentMatch matching rule
applied to attribute values of the objectClasses attribute type. The
componentFilterMatch matching rule subsumes the functionality of the
objectIdentifierFirstComponentMatch, integerFirstComponentMatch and
directoryStringFirstComponentMatch matching rules.
The following search filter finds the object class definition for the
object class called foobar:
(objectClasses:componentFilterMatch:=
item:{ component "name.*",
rule caseIgnoreMatch, value "foobar" })
An object class definition can have multiple names and the above