Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)
RFC 3876

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 07

Network Working Group                                        D. Chadwick
Request for Comments: 3876                         University of Salford
Category: Standards Track                                      S. Mullan
                                                        Sun Microsystems
                                                          September 2004

                   Returning Matched Values with the
        Lightweight Directory Access Protocol version 3 (LDAPv3)

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2004).

Abstract

   This document describes a control for the Lightweight Directory
   Access Protocol version 3 that is used to return a subset of
   attribute values from an entry.  Specifically, only those values that
   match a "values return" filter.  Without support for this control, a
   client must retrieve all of an attribute's values and search for
   specific values locally.

1.  Introduction

   When reading an attribute from an entry using the Lightweight
   Directory Access Protocol version 3 (LDAPv3) [2], it is normally only
   possible to read either the attribute type, or the attribute type and
   all its values.  It is not possible to selectively read just a few of
   the attribute values.  If an attribute holds many values, for
   example, the userCertificate attribute, or the subschema publishing
   operational attributes objectClasses and attributeTypes [3], then it
   may be desirable for the user to be able to selectively retrieve a
   subset of the values, specifically, those attribute values that match
   some user defined selection criteria.  Without the control specified
   in this document, a client must read all of the attribute's values
   and filter out the unwanted values, necessitating the client to
   implement the matching rules.  It also requires the client to

Chadwick & Mullan           Standards Track                     [Page 1]
RFC 3876          Returning Matched Values with LDAPv3    September 2004

   potentially read and process many irrelevant values, which can be
   inefficient if the values are large or complex, or there are many
   values stored per attribute.

   This document specifies an LDAPv3 control to enable a user to return
   only those values that matched (i.e., returned TRUE to) one or more
   elements of a newly defined "values return" filter.  This control can
   be especially useful when used in conjunction with extensible
   matching rules that match on one or more components of complex binary
   attribute values.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14, RFC 2119 [4].

2.  The valuesReturnFilter Control

   The valuesReturnFilter control is either critical or non-critical as
   determined by the user.  It only has meaning for the Search
   operation, and SHOULD only be added to the Search operation by the
   client.  If the server supports the control and it is present on a
   Search operation, the server MUST obey the control, regardless of the
   value of the criticality flag.

   If the control is marked as critical, and either the server does not
   support the control or the control is applied to an operation other
   than Search, the server MUST return an unavailableCriticalExtension
   error.  If the control is not marked as critical, and either the
   server does not support the control or the control is applied to an
   operation other than Search, then the server MUST ignore the control.

   The object identifier for this control is 1.2.826.0.1.3344810.2.3.

   The controlValue is an OCTET STRING, whose value is the BER encoding
   [6], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 [5]
   type ValuesReturnFilter.

           ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem

           SimpleFilterItem ::= CHOICE {
                   equalityMatch   [3] AttributeValueAssertion,
                   substrings      [4] SubstringFilter,
                   greaterOrEqual  [5] AttributeValueAssertion,
                   lessOrEqual     [6] AttributeValueAssertion,
                   present         [7] AttributeDescription,
                   approxMatch     [8] AttributeValueAssertion,
                   extensibleMatch [9] SimpleMatchingAssertion }

Chadwick & Mullan           Standards Track                     [Page 2]
RFC 3876          Returning Matched Values with LDAPv3    September 2004

            SimpleMatchingAssertion ::= SEQUENCE {
                   matchingRule    [1] MatchingRuleId OPTIONAL,