Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)
Extracted elements (17)
The LDAPEXT Working Group chose to replace the X.500 DAP matchedValuesOnly (MVO) boolean with an explicit filter because the MVO boolean had ambiguities—it was unclear whether it governed only values contributing to overall filter truth or all attribute values even when their filter item evaluated false.
If duplicate-entry processing is performed before value filtering, the result set may contain identical duplicate entries each with an empty set of attribute values, because filtering removed the values used to differentiate duplicates.
The control acts independently of other LDAP controls such as server-side sorting and duplicate entries, but sequencing matters: if sorting is done before value filtering, the result set may appear in the wrong order since filtering may remove the sort-key attribute values.
For each attribute listed in the Search Request's attributes parameter, the server MUST apply the ValuesReturnFilter to each filtered entry: values evaluating TRUE against one or more filter items are included; values evaluating FALSE or undefined against all items are excluded, resulting in an empty set for that attribute if no values match.
If the AttributeDescriptionList is empty or '*', the control MUST be applied against every user attribute. If it contains '+', the control MUST be applied against every operational attribute.
If the attributes parameter consists of only the OID '1.1' (no attributes to be returned), the control has no effect and the Search Request is processed as if the control had not been specified.
If the control is marked critical and the server does not support it or it is applied to an operation other than Search, the server MUST return an unavailableCriticalExtension error. If not critical in those same conditions, the server MUST ignore the control.
If the typesOnly parameter of the Search Request is TRUE, the control has no effect and the Search Request is processed as if the control had not been specified.
Once attribute values have been discarded by the ValuesReturnFilter control, they MUST NOT be re-instated into the Search results by other controls.
The ValuesReturnFilter control in a SearchRequest SHOULD precede other controls that affect the number and ordering of SearchResultEntrys (e.g., server side sorting, duplicate entries) to avoid unexpected interactions.
The valuesReturnFilter control SHOULD only be added to the Search operation by the client. If the server supports it and it is present on a Search operation, the server MUST obey the control regardless of the criticality flag.
The valuesReturnFilter control (OID 1.2.826.0.1.3344810.2.3) is an LDAPv3 control that causes the server to return only those attribute values that match a 'values return' filter. It applies only to Search operations and can be marked critical or non-critical by the client.
The Matched Values Control (OID 1.2.826.0.1.3344810.2.3) is registered as an LDAP Protocol Mechanism with IANA per RFC 3383. Usage type: Control. Author/Change Controller: IESG.
Attribute values MUST only be returned if the LDAP server's access controls permit it; the ValuesReturnFilter control does not override access controls and has no consequence on their enforcement.
The ValuesReturnFilter control can improve PKI scalability by enabling server-side certificate matching, avoiding the download and local processing of large numbers of irrelevant certificates when searching for specific userCertificate values.
SimpleMatchingAssertion for the extensibleMatch choice is a SEQUENCE containing optional matchingRule [1] (MatchingRuleId) and optional type [2] (AttributeDescription), with at least one of these present, plus mandatory matchValue [3] (AssertionValue).
The controlValue is an OCTET STRING containing the BER encoding of a ValuesReturnFilter, defined as SEQUENCE OF SimpleFilterItem. SimpleFilterItem is a CHOICE supporting equalityMatch [3], substrings [4], greaterOrEqual [5], lessOrEqual [6], present [7], approxMatch [8], and extensibleMatch [9].