Appendix A - LDAP: Component Matching Search Filter
The normal text form of the search filter is defined by RFC 4515 with a bit of help from RFC 4510 and is described here. The search filter was significantly extended with component matching (RFC3687) and Generic String Encoding Rules (GSER) (RFC4792).
Note: As previously noted, while component matching is part of the base LDAPv3 specification it was defined significantly later than LDAPv3 and being part of the basic specification does not require an SupportedExtension OID. It is not clear how to tell, other than by trying (or searching for the componentMatchingRule in the rootDSE under matchingRules), whether an implementation claiming LDAPv3 compatibility supports the feature. Certainly LDAP servers claiming compliance with the RFC45XX series should support component matching while those referencing the earlier RFC 225X series most likely will not not. Extremely confusing.
OpenLDAP is evolving. Component matching was defined to be released with OpenLDAP 2.4.8 - it was not.
Component Matching (RFC 3687)
Component Matching allows searches to be performed on the components of a complex (composite) attribute, for instance member, by explicitly referencing (or extracting) them. The primary motive for the development of the Matching Rule syntax appears to be to enable additional processing of X.509 certificates. To achieve this goal the syntax allows the user to drill down to the grubby ASN.1 details of the attribute and reference the contents of SEQUENCE OF, SEQUENCE, SET OF or SET grammars - this level of detail may require cross reference to multiple X.5xx (X.501 and X.520 as a miniumum) series documents.
However component matching can also provide a more readable, but lengthier, syntax especially for nornal combined expressions which users may find useful. In order to simplify the feature's description (for ourselves as much as for any reader) we have chosen to separately document simple and complex Component Matching expressions.
The component matching feature introduces two new matching rules, rdnMatch (1.2.36.79672281.1.13.3) which allows processing of an RDN within a DN and presentMatch (1.2.36.79672281.1.13.5) which returns TRUE if the target attribute or extracted component exists and is the equivalent of attr=* (the presence filter) in normal search filters.
Simple Component Matching (RFC 3687)
Simple Component Matching we define to cover either an alternate syntax for simple attribute (single instance) searching or where a component is extracted from a complex attribute (multiple instances) defined using ASN.1 SEQUENCE OF or SET OF grammars - essentially an attribute which contains multiple components each of which is of the same type.
(attr:componentFilterMatch:=[boolexp:{]
item:{[component comexp] [useDefaultValues TRUE|FALSE] rule
matchingRule value valexp } [next-item ... }] )
The search filter is enclosed in brackets (parentheses) while elements within a component matching filter are enclosed in braces (curly brackets {}).
The following sections describe the component matching syntax when used for simple expressions. Additional detail is provided when used in complex expressions. The syntax can get brutally complex - do not despair - instead it may be better to look at the simple examples which show normal filters and the component matching rule syntax - then work backwards to the formal definition.
Attr
The name of the attribute being referenced. May be a simple or complex (composite) attribute or an operational attribute.
componentMatchingRule
MatchingRule invoking component matching feature.
[boolexp{]
Optional boolean expression which may be 'and:', 'or:' or 'not:'. Boolean expressions are enclosed in braces {} amd may be nested leading to very complex expressions.
item:{
Item is a keyword denoting the start of a component expression which is enclosed in braces {}.
component
The component keyword is optional and is followed by the component extraction (or isolation) expression. If omitted the component is assumed to be the whole attr referenced in the search filter, that is, no component is extracted and the filter simply becomes an alternative syntax for defining the search. If a component expression is present then the type of componet it extracts will determine the rule that may be applied.
comexp
The component extraction expression may be a simple quoted value or may be a nested item expression. The simple quoted value may be:
number - defines the number of the instance within a
SET OF or SEQUENCE OF attribute definition. In the
case of an attribute containing a DN each instance
(defined in a SEQUENCE OF) is an RDN. The right-most RDN
is given the number 1, the next is the number 2 etc. Thus
in the DN ou=me,dc=my,dc=us The RDN dc=us has the instance
value "1", dc=my "2" and ou=me "3". Instance values are numbered
from the right.
negative
number - Same as above but where "-1" is the left-most instance. Thus
in the DN ou=me,dc=my,dc=us The RDN ou=me has the instance
value "-1", dc=my "-2" and dc=us "-3". Instance values are numbered
from the left.
count - The value "0" indicates the subsequent tests are applied to the number
of instances within the attribute not the values of the instances.
all - The value "*" indicates that all instances of the attribute will be used.
useDefaultValues TRUE|FALSE
Optional (defaults to TRUE) and defines whether default values for an attribute (if defined) will be used (TRUE) in evaluation of the component expression or not (FALSE).
rule
The rule keyword is followed by the matchingRule that will be applied to the extracted component.
matchingRule
The matchingRule to be applied to the extracted component. May be defined as an name or an OID. The matchingRule should clearly be appropriate to the extracted component.
value
The keyword value is followed by the value to used in evaluating the search filter.
valexp
The value expression (enclosed in quotes) that will be used in evaluating the search filter or the value NULL that is applied only to the presentMatch matchingRule.
Simple Examples
The following examples use component matching as an alternate syntax rewrite the normal search filter expressions already illustrated using component matching syntax. In all cases since the search is being performed:
# normal search filter
(mail=*) # returns all entries which have a mail attribute
# component matching syntax
(mail:componentFilterMatch:=item:{rule presentMatch, value NULL})
# presentMatch returns TRUE if present else FALSE
# the negative form (return entries which do NOT have
# a mail attribute would be
(mail:componentFilterMatch:=not:{item:{rule presentMatch, value NULL}})
# normal search filter
(mail=*@*) # return entries with any valid RFC822 mail address
# component matching syntax
(mail:componentFilterMatch:=item:{rule caseIgnoreMatch, value "*@*"})
# normal search filter
(&(mail=*)(cn=*r)(sn=s*)) # has mail attr AND cn ends with R
AND sn starts with s
# component matching syntax
()
# normal search filter
(|(sn=a*)(sn=b*)(sb=c*)) # sn starts with a OR b OR c
# component matching syntax
(sn:componentFilterMatch:=or:{item:{rule caseIgnoreMatch, value "a*"},
item:{rule caseIgnoreMatch, value "b*"},
item:{rule caseIgnoreMatch, value "c*"}})
# normal search filter
(!(sn=a*)) # entries with sn NOT starting with a
# component search syntax
(sn:componentFilterMatch:=not:{item:{rule caseIgnoreMatch, value "a*"}})
# normal search filter
(&(!(sn=a*))(!(sn=b*))) # entries with sn NOT starting with a
AND NOT starting with b
# component search syntax
(sn:componentFilterMatch:=and:{item:{rule caseIgnoreMatch, value "a*"},
not:{item:{rule caseIgnoreMatch, value "b*"}}})
# normal search filter
# override EQUALITY match with case sensitive match
sn:caseExactMatch:=Smith
# functionally same as above using OID
sn:2.5.13.5:=Smith
# component search syntax
(sn:componentFilterMatch:=item:{rule caseExactMatch, value "Smith"})
# or
(sn:componentFilterMatch:=item:{rule 2.5.13.5, value "Smith"})
The following examples extract components from a complex attribute - in this case a DN attribute such as member:
# All examples assume member has the format
# cn=groupname,ou=groups,dc=example,dc=com
# where groupname is variable
# find entries which have a member whose cn = sales
# using number (numbered from RIGHT)
(cn:componentFilterMatch:=item{component "4",rule rdnMatch, value "cn=sales"})
# find entries which have a member whose cn = sales
# using negative number (numbered from LEFT)
(cn:componentFilterMatch:=item{component "-1",rule rdnMatch, value "cn=sales"})
# find entries which have a member whose ou = groups
# anywhere in the dn
# using all syntax
(cn:componentFilterMatch:=item{component "*",rule rdnMatch, value "ou=groups"})
# find entries which have 5 member attributes
# using count syntax
(cn:componentFilterMatch:=item{component "0",rule rdnMatch, value "5"})
# find entries which have 5 or more but less than 8 member attributes
# using count syntax
(cn:componentFilterMatch:=or:{item{component "0",rule rdnMatch, value "5"},
item{component "0",rule rdnMatch, value "6"},
item{component "0",rule rdnMatch, value "7"}})
# find entries which have a member whose cn=sales and dc=example and dc=com
# using compound expressions
(cn:componentFilterMatch:=and:{item:{component "4",rule rdnMatch, value "cn=sales"},
item:{component "2",rule rdnMatch, value "dc=example"},
item:{component "1",rule rdnMatch, value "dc=com"}})
Complex Component Matching (RFC 3687)
When we understand it we'll let you know. Hint: Don't hold your breath.
Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.
