UnderstandingMatchingRuleUses

Overview#

Return to Contents
Next: Attribute Syntaxes

Matching Rules#

Matching rules are used by the Directory Server to compare two values for the same attribute (i.e., to perform matching operations on them). There are several different types of matching rules, including:

Overview#

The Matching Rule Description Format The matching rule description format is described in RFC 4512, section 4.1.3. This is the format that is used to display matching rules in the matchingRules attribute of the schema subentry, and it shows the properties that may be associated with a matching rule. The definition of the matching rule description format is as follows:
     MatchingRuleDescription = LPAREN WSP
         numericoid                 ; object identifier
         [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
         [ SP "DESC" SP qdstring ]  ; description
         [ SP "OBSOLETE" ]          ; not active
         SP "SYNTAX" SP numericoid  ; assertion syntax
         extensions WSP RPAREN      ; extensions

The elements of the matching rule description include:

For example, the following is the matching rule description for the standard caseIgnoreMatch matching rule:

    ( 2.5.13.2 NAME 'caseIgnoreMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
In this case, the OID is "2.5.13.2". There is one name, which is "caseIgnoreMatch". There is no description. The OID of the associated syntax is 1.3.6.1.4.1.1466.115.121.1.15 (which is the Directory String syntax). There are no extensions.

Commonly-Used Matching Rules#

There are a number of matching rules defined in LDAP, both in the core protocol specification, as well as other related RFCs and Internet Drafts. Many of these matching rules are defined in RFC 4517 (LDAP Syntaxes and Matching Rules), in section 4.2. Some of the most commonly-used matching rules include:

Value Normalization#

One of the tasks that most matching rules need to perform is value normalization. This is the process of transforming a given value to a form that can be used to compare values efficiently. In most cases, the normalization process should reduce all logically equivalent values to the same string so that a very simple string comparison can be performed to determine whether the strings are equal. For example, the caseIgnoreMatch matching rule will typically normalize values by converting all characters to lowercase and replacing occurrences of multiple consecutive spaces with a single space. A more complicated example is the distinguishedNameMatch matching rule, which removes all unnecessary spaces (e.g., around commas, equal signs, and plus signs), converts all attribute types to lowercase, and then uses the appropriate matching rules to normalize the attribute values for each RDN component.

Note that in some cases, normalization alone is not sufficient for determining whether two values are logically equivalent. This is particularly true for cases in which the value is transformed, and there can be multiple different transformations for the same value. For example, this is often done for the userPassword attribute type, where values may be encoded using a one-way message digest algorithm, and if that algorithm includes a salt then each time a given value is encoded it may result in a different string (in fact, this is the intended behavior, which helps prevent dictionary attacks). In cases like this, the matching rule simply needs to use different logic to determine equality, rather than relying solely on normalization.

The OpenDS Matching Rule Implementation#

Because matching rules require logic to perform the appropriate kinds of matching operations, they must be implemented in code. All matching rules in OpenDS must be subclasses of the org.opends.server.api.MatchingRule class, and most of them should be subclasses of one of the following classes (each of which is a subclass of org.opends.server.api.MatchingRule):

All of the matching rule implementations that are provided as part of OpenDS are included in the org.opends.server.schema package. When a new matching rule class is implemented, a corresponding configuration entry should be added below the "cn=Matching Rules,cn=config" entry. For example, the configuration entry that defines the caseIgnoreMatch equality matching rule is as follows:

dn: cn=Case Ignore Equality Matching Rule,cn=Matching Rules,cn=config
objectClass: top
objectClass: ds-cfg-matching-rule
objectClass: ds-cfg-equality-matching-rule
cn: Case Ignore Equality Matching Rule
ds-cfg-matching-rule-class: org.opends.server.schema.CaseIgnoreEqualityMatchingRule
ds-cfg-matching-rule-enabled: true
The most important methods from the org.opends.server.api.MatchingRule class that matching rules need to implement are:
public ByteString normalizeValue(ByteString value)
       throws DirectoryException

public ConditionResult valuesMatch(ByteString attributeValue,
                                   ByteString assertionValue)
Equality matching rules need to implement the following method from the org.opends.server.api.EqualityMatchingRule class:
public boolean areEqual(ByteString value1, ByteString value2)
Ordering matching rules need to implement the following method from the org.opends.server.api.OrderingMatchingRule class:
public int compareValues(ByteString value1, ByteString value2)
Substring matching rules need to implement the following two methods from the org.opends.server.api.SubstringMatchingRule class:
public ByteString normalizeSubstring(ByteString substring)
       throws DirectoryException

public boolean valueMatchesSubstring(ByteString value,
                                     ByteString subInitial,
                                     List subAnyElements,
                                     ByteString subFinal)
Approximate matching rules need to implement the following method from the org.opends.server.api.ApproximateMatchingRule class:
public boolean approximatelyMatch(ByteString value1,
                                  ByteString value2)
Matching rule objects may be retrieved from the server schema using their OIDs or any of their human-readable names.
Return to Contents
Next: Attribute Syntaxes

More Information#

There might be more information for this subject on one of the following: