RFC 3876

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

📅 published September 2004, from ietf

Returning Matched Values with LDAPv3 🎀 (Part 1 of 3)

RFC: 3876 Title: Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3) Authors: D. Chadwick (University of Salford) and S. Mullan (Sun Microsystems) 👯 Category: Standards Track ✨ Date: September 2004 📅 Obsoletes / Updates: none listed in this header

Status of This Memo 📜

This doc is an Internet standards track protocol for the Internet community, and it's literally asking for discussion and suggestions 💬. For the standardization state and status of this protocol, check the current edition of "Internet Official Protocol Standards" (STD 1) 🔍. Distribution of this memo is unlimited 🌸.

Copyright (C) The Internet Society (2004).

Abstract 🦋

This doc describes a control for LDAPv3 that returns a subset of attribute values from an entry. Specifically, only the values that match a "values return" filter get sent back 💅. Without this control, a client has to grab every single value and search for the ones it wants locally, which is so much work 😩.

1. Introduction 💖

Okay so when you read an attribute from an entry using LDAPv3 [2], you can normally only get the attribute type, or the type plus all of its values. There's no picking out just a few 🙃. If an attribute holds a ton of values, like userCertificate, or the subschema publishing operational attributes objectClasses and attributeTypes [3], it would be really nice to grab only the ones that match your own selection criteria 🧁.

Without the control in this doc, the client has to read all the values and filter out the unwanted ones, which means it has to implement the matching rules itself 😵‍💫. It also has to read and process a bunch of irrelevant values, which is inefficient if they're big or complex, or if there are many stored per attribute 🐌.

This document specifies an LDAPv3 control that lets a user return only the values that matched (i.e., returned TRUE to) one or more elements of a newly defined "values return" filter ✨. It's especially useful together 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 can be critical or non-critical, and the user decides which 🙋‍♀️. It only has meaning for the Search operation, and it SHOULD only be added to the Search operation by the client 💌. If the server supports the control and it's present on a Search operation, the server MUST obey the control, no matter what the criticality flag says 👑.

If the control is marked as critical, and either the server doesn't support it or it's applied to an operation other than Search, the server MUST return an unavailableCriticalExtension error 🚨. If the control is not marked as critical, and either of those things is true, 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. Its 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 }

         SimpleMatchingAssertion ::= SEQUENCE {
                matchingRule    [1] MatchingRuleId OPTIONAL,
                type            [2] AttributeDescription OPTIONAL,
--- at least one of the above must be present
                matchValue      [3] AssertionValue}

All the above data types have their standard meanings as defined in [2] 📚.

If the server supports this control, the server MUST make use of the control as follows 🛠️:

  1. The Search Filter is executed first, to figure out which entries satisfy the Search criteria (these are the filtered entries). The control has no impact on this step 🙌.
  2. 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 hadn't been specified 🤷‍♀️.
  3. If the attributes parameter of the Search Request is a list containing only the attribute with OID "1.1" (meaning no attributes are to be returned), the control has no effect, and the Search Request is processed as if the control hadn't been specified 😴.
  4. For each attribute listed in the attributes parameter of the Search Request, the server MUST apply the control as follows to each entry in the set of filtered entries 🎯:
    • i) Every attribute value that evaluates TRUE against one or more elements of the ValuesReturnFilter is placed in the corresponding SearchResultEntry ✅.
    • ii) Every attribute value that evaluates FALSE or undefined against all elements of the ValuesReturnFilter is not placed in the corresponding SearchResultEntry 🗑️. An attribute that has no values selected is returned with an empty set of values 🫥.

Note. If the AttributeDescriptionList (see [2]) is empty or comprises "*", then the control MUST be applied against every user attribute. If the AttributeDescriptionList contains a "+", then the control MUST be applied against every operational attribute 🌈.

3. Relationship to X.500 🌍

The control is a superset of the matchedValuesOnly (MVO) boolean of the X.500 Directory Access Protocol (DAP) [8] Search argument, as amended in the latest version [9] 🧐. The LDAP Extensions (LDAPEXT) Working Group took a close look at the matchedValuesOnly boolean and found ambiguities and complexities that couldn't easily be resolved 🤯. For example, it wasn't clear whether the MVO boolean governed only the attribute values that contributed to the overall truth of the filter, or all of the attribute values, even when the filter item containing the attribute evaluated as false 🫠. So the LDAPEXT group decided to replace the MVO boolean with a simple filter that removes any uncertainty about whether an attribute value has been selected or not 💯.

4. Relationship to other LDAP Controls 🧚

The purpose of this control is to select zero, one, or more attribute values from each requested attribute in a filtered entry, and to discard the rest 🗂️. Once the attribute values have been discarded by this control, they MUST NOT be re-instated into the Search results by other controls 🚫.

This control acts independently of other LDAP controls, such as server side sorting [13] and duplicate entries [10] 🤝. However, there might be interactions between this control and other controls, so a different set of Search Result Entries could come back, or the entries could come back in a different order, depending on the sequencing of this control and the other controls in the LDAP request 🔀. For example, with server side sorting: if sorting is done first and value return filtering second, the set of Search Results may appear to be in the wrong order, since the value filtering may remove the attribute values the ordering was based on 😬. (The sorting document specifies that entries without any sort key attribute values should be treated as coming after all other attribute values.) Similarly with duplicate entries: if duplication is performed before value filtering, the set of Search Result Entries may contain identical duplicate entries, each with an empty set of attribute values, because the value filtering removed the attribute values that were used to duplicate the results 👯‍♀️.

For these reasons, the ValuesReturnFilter control in a SearchRequest SHOULD precede other controls that affect the number and ordering of SearchResultEntrys 🏁✨

5. Examples 🎀

Okay so the examples are where it all clicks, bestie 🧚. Every entry is written in LDIF (LDAP Data Interchange Format) [11] 💖

Here's the string form of the valuesReturnFilter we'll be using, written in ABNF [15]. Quick heads up that it's adapted from RFC2254 [14] 🌸

valuesReturnFilter = "(" 1*simpleFilterItem ")"
simpleFilterItem = "(" item ")"

where item is as defined below (adapted from RFC2254 [14]).

   item         = simple / present / substring / extensible
   simple       = attr filtertype value
   filtertype   = equal / approx / greater / less
   equal        = "="
   approx       = "~="
   greater      = ">="
   less         = "<="
   extensible   = attr [":" matchingrule] ":=" value
                  / ":" matchingrule ":=" value
   present      = attr "=*"
   substring    = attr "=" [initial] any [final]
   initial      = value
   any          = "*" *(value "*")
   final        = value
   attr         = AttributeDescription from Section 4.1.5 of [1]
   matchingrule = MatchingRuleId from Section 4.1.9 of [1]
   value        = AttributeValue from Section 4.1.6 of [1]

1) Example one is all about setting the control so it returns all the values of one attribute type (telephoneNumber, in this case) and only a subset of the values from another (mail). Cute, right? 🦋

These entries are organizationalPerson object classes sitting somewhere beneath the distinguished name dc=ac,dc=uk 💅

dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk
cn: Sean Mullan
sn: Mullan
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
mail: sean.mullan@hotmail.com
mail: mullan@east.sun.com
telephoneNumber: + 781 442 0926
telephoneNumber: 555-9999
dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk
cn: David Chadwick
sn: Chadwick
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
mail: d.w.chadwick@salford.ac.uk

So the LDAP search has a baseObject set to the DN of the search base (that's dc=ac,dc=uk), a subtree scope, and a filter of (sn=mullan). The list of attributes to return is "mail,telephoneNumber" or "*". On top of that, the ValuesReturnFilter control is set to ((mail=*hotmail.com)(telephoneNumber=*)) ✨

And the server sends back this one entry 🌈

dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk
mail: sean.mullan@hotmail.com
telephoneNumber: + 781 442 0926
telephoneNumber: 555-9999

Notice the control does nothing to the telephoneNumber values here. Both of them come back, because the control said all values should be returned for that attribute 🙈

2) Example two is about grabbing a single attribute type subschema definition, the one for the "gunk" attribute with OID 1.2.3.4.5, straight out of the subschema subentry 🧚‍♀️

Pretend the subschema subentry sits below the root entry with DN cn=subschema subentry,o=myorg. It holds an attributeTypes operational attribute, and that holds the descriptions of the 35 attributes this server knows about. Each description is stored as its own single attribute value of the attributeTypes attribute 📚

dn: cn=subschema subentry,o=myorg
cn: subschema subentry
objectClass: subschema
attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )
attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY obj
 ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen
 eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN
 TAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-
 MODIFICATION USAGE directoryOperation )
attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY obj

 ectIdentifierFirstComponentMatch SYNTAX 1.3.
 6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat
 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.
 6.1.4.1.1466.115.121.1.44{64} )
attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj
 ectIdentifierFirstComponentMatch SYNTAX 1.3.
 6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )

plus another 28, you get the idea 😂

The user sets up an LDAP search with a baseObject of cn=subschema subentry,o=myorg, a scope of base, a filter of (objectClass=subschema), and the list of attributes to return set to "attributeTypes". The ValuesReturnFilter is set to ((attributeTypes=1.2.3.4.5)) 💜

The search result the server sends back is just this 🍓

dn: cn=subschema subentry,o=myorg
attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat
 ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.
 6.1.4.1.1466.115.121.1.44{64} )

3) Example three is the big one, showing how the control can match on a userCertificate attribute value 🔐 Heads up: this one needs the LDAP server to support the certificateExactMatch matching rule defined in [12], because that's the EQUALITY matching rule for userCertificate.

The entry below is a pkiUser object class sitting in the directory 🌸

dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb
cn: David Chadwick
objectClass: person
objectClass: organizationalPerson
objectClass: pkiUser
objectClass: inetOrgPerson
sn: Chadwick
mail: d.w.chadwick@salford.ac.uk
userCertificate;binary: {binary representation of a certificate with
a serial number of 2468 issued by o=truetrust ltd,c=gb}
userCertificate;binary: {binary representation of certificate with a
serial number of 1357 issued by o=truetrust ltd,c=gb}
userCertificate;binary: {binary representation of certificate with a
serial number of 1234 issued by dc=certsRus,dc=com}

The LDAP search has a baseObject of o=University of Salford,c=gb, a subtree scope, and a filter of (sn=chadwick). The list of attributes to return is "userCertificate;binary". The ValuesReturnFilter control is set to ((userCertificate=1357$o=truetrust ltd,c=gb)) 🎯

And the server replies with this 🦋

dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb
userCertificate;binary: {binary representation of certificate with a
serial number of 1357 issued by o=truetrust ltd,c=gb}

6. Security Considerations 🔐

Good news, this document doesn't mainly deal with security issues 🫶

Now, the important part 🚨 Attribute values MUST only be returned if the access controls the LDAP server applies allow them to be returned. The effect of the ValuesReturnFilter control doesn't change that at all, so it's of no consequence here.

Heads up, bestie: the access controls always get the final say. The control can't be used to get around them 🙅‍♀️

The ValuesReturnFilter control might actually help the deployment of public key infrastructures 🌈 Certain PKI operations, like searching for specific certificates, get more scalable and way more practical when they're combined with X.509 certificate matching rules at the server. Why? Because the control stops you from downloading tons of irrelevant certificates that would otherwise have to be processed and filtered locally, which in some cases is seriously difficult to do 😭

7. IANA Considerations 🧚

The Matched Values control, registered as an LDAP Protocol Mechanism [7], has been registered like this 📋

   Subject: Request for LDAP Protocol Mechanism Registration

   Object Identifier: 1.2.826.0.1.3344810.2.3
   Description: Matched Values Control
   Person & email address to contact for further information:
     David Chadwick <d.w.chadwick@salford.ac.uk>
   Usage: Control
   Specification: RFC3876
   Author/Change Controller: IESG
   Comments: none

This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the matchedValues control described here. That OID was assigned by TrueTrust Ltd, under its BSI assigned English/Welsh Registered Company number [16] 💅

8. Acknowledgements 💖

The authors want to say a big thank you to the members of the LDAPExt list 🫶 for their constructive comments on earlier versions of this document. Special shoutouts go to Harald Alvestrand, who first suggested having an attribute return filter, and Bruce Greenblatt, who first proposed a syntax for this control ✨

9. References 📚

9.1. Normative References

  • [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996.
  • [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (w3)", RFC 2251, December 1997.
  • [3] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997.
  • [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [5] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998, Information Technology - Abstract Syntax Notation One (ASN.1): Specification of Basic Notation
  • [6] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998 Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)
  • [7] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002.

9.2. Informative References

  • [8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 1993.
  • [9] ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract Service Definition.
  • [10] Sermersheim, J., "LDAP Control for a Duplicate Entry Representation of Search Results", Work in Progress, October 2000.
  • [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000.
  • [12] Chadwick, D. and S.Legg, "Internet X.509 Public Key Infrastructure - Additional LDAP Schema for PKIs", Work in Progress, June 2002
  • [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for Server Side Sorting of Search Results", RFC 2891, August 2000.
  • [14] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997.
  • [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.
  • [16] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration for Open System Standards Part 1: Procedures for the UK Name Registration Authority.

10. Authors' Addresses 🦋

David Chadwick
IS Institute
University of Salford
Salford M5 4WT
England

Phone: +44 161 295 5351
EMail: d.w.chadwick@salford.ac.uk


Sean Mullan
Sun Microsystems
One Network Drive
Burlington, MA 01803
USA

EMail: sean.mullan@sun.com
Copyright (C) The Internet Society (2004).

This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.

This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE
REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Okay bestie, last stretch! 🎀 The IETF's legal bits are kinda boring, but they matter. The IETF doesn't say whether any patents or rights apply to this tech, and it hasn't checked for any either. 🙈 If you want the official scoop on IPR rules, look at BCP 78 and BCP 79. 💅

Anyone can ask the IETF Secretariat for copies of IPR disclosures, licence assurances, or the results of attempts to get a general licence or permission for using proprietary rights. You can find all of that in the IETF's online IPR repository at http://www.ietf.org/ipr. 📚✨

The IETF also wants to hear from anyone who knows about copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to implement this standard. Send that info to the IETF at ietf-ipr@ietf.org. 🦋

Acknowledgement

The RFC Editor function is currently funded by the Internet Society. 🌸 Thank you, Internet Society, you're literally keeping the lights on! 💖

📦 where this page comes from