1
2
3
4
5
6
7Network Working Group                                        D. Chadwick
8Request for Comments: 3876                         University of Salford
9Category: Standards Track                                      S. Mullan
10                                                        Sun Microsystems
11                                                          September 2004
12
13
14                   Returning Matched Values with the
15        Lightweight Directory Access Protocol version 3 (LDAPv3)
16
17Status of this Memo
18
19   This document specifies an Internet standards track protocol for the
20   Internet community, and requests discussion and suggestions for
21   improvements.  Please refer to the current edition of the "Internet
22   Official Protocol Standards" (STD 1) for the standardization state
23   and status of this protocol.  Distribution of this memo is unlimited.
24
25Copyright Notice
26
27   Copyright (C) The Internet Society (2004).
28
29Abstract
30
31   This document describes a control for the Lightweight Directory
32   Access Protocol version 3 that is used to return a subset of
33   attribute values from an entry.  Specifically, only those values that
34   match a "values return" filter.  Without support for this control, a
35   client must retrieve all of an attribute's values and search for
36   specific values locally.
37
381.  Introduction
39
40   When reading an attribute from an entry using the Lightweight
41   Directory Access Protocol version 3 (LDAPv3) [2], it is normally only
42   possible to read either the attribute type, or the attribute type and
43   all its values.  It is not possible to selectively read just a few of
44   the attribute values.  If an attribute holds many values, for
45   example, the userCertificate attribute, or the subschema publishing
46   operational attributes objectClasses and attributeTypes [3], then it
47   may be desirable for the user to be able to selectively retrieve a
48   subset of the values, specifically, those attribute values that match
49   some user defined selection criteria.  Without the control specified
50   in this document, a client must read all of the attribute's values
51   and filter out the unwanted values, necessitating the client to
52   implement the matching rules.  It also requires the client to
53
54
55
56
57
58Chadwick & Mullan           Standards Track                     [Page 1]
59
60RFC 3876          Returning Matched Values with LDAPv3    September 2004
61
62
63   potentially read and process many irrelevant values, which can be
64   inefficient if the values are large or complex, or there are many
65   values stored per attribute.
66
67   This document specifies an LDAPv3 control to enable a user to return
68   only those values that matched (i.e., returned TRUE to) one or more
69   elements of a newly defined "values return" filter.  This control can
70   be especially useful when used in conjunction with extensible
71   matching rules that match on one or more components of complex binary
72   attribute values.
73
74   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
75   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
76   document are to be interpreted as described in BCP 14, RFC 2119 [4].
77
782.  The valuesReturnFilter Control
79
80   The valuesReturnFilter control is either critical or non-critical as
81   determined by the user.  It only has meaning for the Search
82   operation, and SHOULD only be added to the Search operation by the
83   client.  If the server supports the control and it is present on a
84   Search operation, the server MUST obey the control, regardless of the
85   value of the criticality flag.
86
87   If the control is marked as critical, and either the server does not
88   support the control or the control is applied to an operation other
89   than Search, the server MUST return an unavailableCriticalExtension
90   error.  If the control is not marked as critical, and either the
91   server does not support the control or the control is applied to an
92   operation other than Search, then the server MUST ignore the control.
93
94   The object identifier for this control is 1.2.826.0.1.3344810.2.3.
95
96   The controlValue is an OCTET STRING, whose value is the BER encoding
97   [6], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 [5]
98   type ValuesReturnFilter.
99
100           ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem
101
102           SimpleFilterItem ::= CHOICE {
103                   equalityMatch   [3] AttributeValueAssertion,
104                   substrings      [4] SubstringFilter,
105                   greaterOrEqual  [5] AttributeValueAssertion,
106                   lessOrEqual     [6] AttributeValueAssertion,
107                   present         [7] AttributeDescription,
108                   approxMatch     [8] AttributeValueAssertion,
109                   extensibleMatch [9] SimpleMatchingAssertion }
110
111
112
113
114Chadwick & Mullan           Standards Track                     [Page 2]
115
116RFC 3876          Returning Matched Values with LDAPv3    September 2004
117
118
119            SimpleMatchingAssertion ::= SEQUENCE {
120                   matchingRule    [1] MatchingRuleId OPTIONAL,
121                   type            [2] AttributeDescription OPTIONAL,
122   --- at least one of the above must be present
123                   matchValue      [3] AssertionValue}
124
125   All the above data types have their standard meanings as defined in
126   [2].
127
128   If the server supports this control, the server MUST make use of the
129   control as follows:
130
131   1) The Search Filter is first executed in order to determine which
132      entries satisfy the Search criteria (these are the filtered
133      entries).  The control has no impact on this step.
134
135   2) If the typesOnly parameter of the Search Request is TRUE, the
136      control has no effect and the Search Request is processed as if
137      the control had not been specified.
138
139   3) If the attributes parameter of the Search Request consists of a
140      list containing only the attribute with OID "1.1" (specifying that
141      no attributes are to be returned), the control has no effect and
142      the Search Request is processed as if the control had not been
143      specified.
144
145   4) For each attribute listed in the attributes parameter of the
146      Search Request, the server MUST apply the control as follows to
147      each entry in the set of filtered entries:
148
149      i)  Every attribute value that evaluates TRUE against one or more
150          elements of the ValuesReturnFilter is placed in the
151          corresponding SearchResultEntry.
152
153      ii) Every attribute value that evaluates FALSE or undefined
154          against all elements of the ValuesReturnFilter is not placed
155          in the corresponding SearchResultEntry.  An attribute that has
156          no values selected is returned with an empty set of values.
157
158   Note.  If the AttributeDescriptionList (see [2]) is empty or
159   comprises "*", then the control MUST be applied against every user
160   attribute.  If the AttributeDescriptionList contains a "+", then the
161   control MUST be applied against every operational attribute.
162
163
164
165
166
167
168
169
170Chadwick & Mullan           Standards Track                     [Page 3]
171
172RFC 3876          Returning Matched Values with LDAPv3    September 2004
173
174
1753.  Relationship to X.500
176
177   The control is a superset of the matchedValuesOnly (MVO) boolean of
178   the X.500 Directory Access Protocol (DAP) [8] Search argument, as
179   amended in the latest version [9].  Close examination of the
180   matchedValuesOnly boolean by the LDAP Extensions (LDAPEXT) Working
181   Group revealed ambiguities and complexities in the MVO boolean that
182   could not easily be resolved.  For example, it was not clear if the
183   MVO boolean governed only those attribute values that contributed to
184   the overall truth of the filter, or all of the attribute values, even
185   if the filter item containing the attribute was evaluated as false.
186   For this reason the LDAPEXT group decided to replace the MVO boolean
187   with a simple filter that removes any uncertainty as to whether an
188   attribute value has been selected or not.
189
1904.  Relationship to other LDAP Controls
191
192   The purpose of this control is to select zero, one, or more attribute
193   values from each requested attribute in a filtered entry, and to
194   discard the remainder.  Once the attribute values have been discarded
195   by this control, they MUST NOT be re-instated into the Search results
196   by other controls.
197
198   This control acts independently of other LDAP controls such as server
199   side sorting [13] and duplicate entries [10].  However, there might
200   be interactions between this control and other controls so that a
201   different set of Search Result Entries are returned, or the entries
202   are returned in a different order, depending upon the sequencing of
203   this control and other controls in the LDAP request.  For example,
204   with server side sorting, if sorting is done first, and value return
205   filtering second, the set of Search Results may appear to be in the
206   wrong order since the value filtering may remove the attribute values
207   upon which the ordering was done.  (The sorting document specifies
208   that entries without any sort key attribute values should be treated
209   as coming after all other attribute values.)  Similarly with
210   duplicate entries, if duplication is performed before value
211   filtering, the set of Search Result Entries may contain identical
212   duplicate entries, each with an empty set of attribute values,
213   because the value filtering removed the attribute values that were
214   used to duplicate the results.
215
216   For these reasons, the ValuesReturnFilter control in a SearchRequest
217   SHOULD precede other controls that affect the number and ordering of
218   SearchResultEntrys.
219
220
221
222
223
224
225
226Chadwick & Mullan           Standards Track                     [Page 4]
227
228RFC 3876          Returning Matched Values with LDAPv3    September 2004
229
230
2315.  Examples
232
233   All entries are provided in an LDAP Data Interchange Format
234   (LDIF)[11].
235
236   The string representation of the valuesReturnFilter in the examples
237   below uses the following ABNF [15] notation:
238
239   valuesReturnFilter = "(" 1*simpleFilterItem ")"
240   simpleFilterItem = "(" item ")"
241
242   where item is as defined below (adapted from RFC2254 [14]).
243
244      item         = simple / present / substring / extensible
245      simple       = attr filtertype value
246      filtertype   = equal / approx / greater / less
247      equal        = "="
248      approx       = "~="
249      greater      = ">="
250      less         = "<="
251      extensible   = attr [":" matchingrule] ":=" value
252                     / ":" matchingrule ":=" value
253      present      = attr "=*"
254      substring    = attr "=" [initial] any [final]
255      initial      = value
256      any          = "*" *(value "*")
257      final        = value
258      attr         = AttributeDescription from Section 4.1.5 of [1]
259      matchingrule = MatchingRuleId from Section 4.1.9 of [1]
260      value        = AttributeValue from Section 4.1.6 of [1]
261
262   1) The first example shows how the control can be set to return all
263      attribute values from one attribute type (e.g., telephoneNumber)
264      and a subset of values from another attribute type (e.g., mail).
265
266   The entries below represent organizationalPerson object classes
267   located somewhere beneath the distinguished name dc=ac,dc=uk.
268
269   dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk
270   cn: Sean Mullan
271   sn: Mullan
272   objectClass: organizationalPerson
273   objectClass: person
274   objectClass: inetOrgPerson
275   mail: sean.mullan@hotmail.com
276   mail: mullan@east.sun.com
277   telephoneNumber: + 781 442 0926
278   telephoneNumber: 555-9999
279
280
281
282Chadwick & Mullan           Standards Track                     [Page 5]
283
284RFC 3876          Returning Matched Values with LDAPv3    September 2004
285
286
287   dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk
288   cn: David Chadwick
289   sn: Chadwick
290   objectClass: organizationalPerson
291   objectClass: person
292   objectClass: inetOrgPerson
293   mail: d.w.chadwick@salford.ac.uk
294
295   An LDAP search operation is specified with a baseObject set to the DN
296   of the search base (i.e., dc=ac,dc=uk), a subtree scope, a filter set
297   to (sn=mullan), and the list of attributes to be returned set to
298   "mail,telephoneNumber" or "*".  In addition, a ValuesReturnFilter
299   control is set to ((mail=*hotmail.com)(telephoneNumber=*)).
300
301   The search results returned by the server would consist of the
302   following entry:
303
304   dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk
305   mail: sean.mullan@hotmail.com
306   telephoneNumber: + 781 442 0926
307   telephoneNumber: 555-9999
308
309   Note that the control has no effect on the values returned for the
310   "telephoneNumber" attribute (all of the values are returned), since
311   the control specified that all values should be returned.
312
313   2) The second example shows how one might retrieve a single attribute
314      type subschema definition for the "gunk" attribute with OID
315      1.2.3.4.5 from the subschema subentry.
316
317   Assume the subschema subentry is held below the root entry with DN
318   cn=subschema subentry,o=myorg and this holds an attributeTypes
319   operational attribute holding the descriptions of the 35 attributes
320   known to this server (each description is held as a single attribute
321   value of the attributeTypes attribute).
322
323   dn: cn=subschema subentry,o=myorg
324   cn: subschema subentry
325   objectClass: subschema
326   attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )
327   attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
328   attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY obj
329    ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
330   attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen
331    eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN
332    TAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-
333    MODIFICATION USAGE directoryOperation )
334   attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY obj
335
336
337
338Chadwick & Mullan           Standards Track                     [Page 6]
339
340RFC 3876          Returning Matched Values with LDAPv3    September 2004
341
342
343    ectIdentifierFirstComponentMatch SYNTAX 1.3.
344    6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
345   attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat
346    ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.
347    6.1.4.1.1466.115.121.1.44{64} )
348   attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj
349    ectIdentifierFirstComponentMatch SYNTAX 1.3.
350    6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
351
352   plus another 28 - you get the idea.
353
354   The user creates an LDAP search operation with a baseObject set to
355   cn=subschema subentry,o=myorg, a scope of base, a filter set to
356   (objectClass=subschema), the list of attributes to be returned set to
357   "attributeTypes", and the ValuesReturnFilter set to
358   ((attributeTypes=1.2.3.4.5))
359
360   The search result returned by the server would consist of the
361   following entry:
362
363   dn: cn=subschema subentry,o=myorg
364   attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat
365    ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.
366    6.1.4.1.1466.115.121.1.44{64} )
367
368   3) The final example shows how the control can be used to match on a
369      userCertificate attribute value.  Note that this example requires
370      the LDAP server to support the certificateExactMatch matching rule
371      defined in [12] as the EQUALITY matching rule for userCertificate.
372
373   The entry below represents a pkiUser object class stored in the
374   directory.
375
376   dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb
377   cn: David Chadwick
378   objectClass: person
379   objectClass: organizationalPerson
380   objectClass: pkiUser
381   objectClass: inetOrgPerson
382   sn: Chadwick
383   mail: d.w.chadwick@salford.ac.uk
384   userCertificate;binary: {binary representation of a certificate with
385   a serial number of 2468 issued by o=truetrust ltd,c=gb}
386   userCertificate;binary: {binary representation of certificate with a
387   serial number of 1357 issued by o=truetrust ltd,c=gb}
388   userCertificate;binary: {binary representation of certificate with a
389   serial number of 1234 issued by dc=certsRus,dc=com}
390
391
392
393
394Chadwick & Mullan           Standards Track                     [Page 7]
395
396RFC 3876          Returning Matched Values with LDAPv3    September 2004
397
398
399   An LDAP search operation is specified with a baseObject set to
400   o=University of Salford,c=gb, a subtree scope, a filter set to
401   (sn=chadwick), and the list of attributes to be returned set to
402   "userCertificate;binary".  In addition, a ValuesReturnFilter control
403   is set to ((userCertificate=1357$o=truetrust ltd,c=gb)).
404
405   The search result returned by the server would consist of the
406   following entry:
407
408   dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb
409   userCertificate;binary: {binary representation of certificate with a
410   serial number of 1357 issued by o=truetrust ltd,c=gb}
411
4126.  Security Considerations
413
414   This document does not primarily discuss security issues.
415
416   Note however that attribute values MUST only be returned if the
417   access controls applied by the LDAP server allow them to be returned,
418   and in this respect the effect of the ValuesReturnFilter control is
419   of no consequence.
420
421   Note that the ValuesReturnFilter control may have a positive effect
422   on the deployment of public key infrastructures.  Certain PKI
423   operations, like searching for specific certificates, become more
424   scalable, and more practical when combined with X.509 certificate
425   matching rules at the server, since the control avoids the
426   downloading of potentially large numbers of irrelevant certificates
427   which would have to be processed and filtered locally (which in some
428   cases is very difficult to perform).
429
4307.  IANA Considerations
431
432   The Matched Values control as an LDAP Protocol Mechanism [7] has been
433   registered as follows:
434
435      Subject: Request for LDAP Protocol Mechanism Registration
436
437      Object Identifier: 1.2.826.0.1.3344810.2.3
438      Description: Matched Values Control
439      Person & email address to contact for further information:
440        David Chadwick <d.w.chadwick@salford.ac.uk>
441      Usage: Control
442      Specification: RFC3876
443      Author/Change Controller: IESG
444      Comments: none
445
446
447
448
449
450Chadwick & Mullan           Standards Track                     [Page 8]
451
452RFC 3876          Returning Matched Values with LDAPv3    September 2004
453
454
455   This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the
456   matchedValues control described here.  This OID was assigned by
457   TrueTrust Ltd, under its BSI assigned English/Welsh Registered
458   Company number [16].
459
4608.  Acknowledgements
461
462   The authors would like to thank members of the LDAPExt list for their
463   constructive comments on earlier versions of this document, and in
464   particular to Harald Alvestrand who first suggested having an
465   attribute return filter and Bruce Greenblatt who first proposed a
466   syntax for this control.
467
4689.  References
469
4709.1.  Normative References
471
472   [1]  Bradner, S., "The Internet Standards Process -- Revision 3", BCP
473        9, RFC 2026, October 1996.
474
475   [2]  Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
476        Protocol (w3)", RFC 2251, December 1997.
477
478   [3]  Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
479        Directory Access Protocol (v3): Attribute Syntax Definitions",
480        RFC 2252, December 1997.
481
482   [4]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
483        Levels", BCP 14, RFC 2119, March 1997.
484
485   [5]  ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998,
486        Information Technology - Abstract Syntax Notation One (ASN.1):
487        Specification of Basic Notation
488
489   [6]  ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998
490        Information technology - ASN.1 encoding rules: Specification of
491        Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and
492        Distinguished Encoding Rules (DER)
493
494   [7]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
495        Considerations for the Lightweight Directory Access Protocol
496        (LDAP)", BCP 64, RFC 3383, September 2002.
497
498
499
500
501
502
503
504
505
506Chadwick & Mullan           Standards Track                     [Page 9]
507
508RFC 3876          Returning Matched Values with LDAPv3    September 2004
509
510
5119.2.  Informative References
512
513   [8]  ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
514        1993.
515
516   [9]  ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract
517        Service Definition.
518
519   [10] Sermersheim, J., "LDAP Control for a Duplicate Entry
520        Representation of Search Results", Work in Progress, October
521        2000.
522
523   [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical
524        Specification", RFC 2849, June 2000.
525
526   [12] Chadwick, D. and S.Legg, "Internet X.509 Public Key
527        Infrastructure - Additional LDAP Schema for PKIs", Work in
528        Progress, June 2002
529
530   [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for
531        Server Side Sorting of Search Results", RFC 2891, August 2000.
532
533   [14] Howes, T., "The String Representation of LDAP Search Filters",
534        RFC 2254, December 1997.
535
536   [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax
537        Specifications: ABNF", RFC 2234, November 1997.
538
539   [16] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration
540        for Open System Standards Part 1: Procedures for the UK Name
541        Registration Authority.
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562Chadwick & Mullan           Standards Track                    [Page 10]
563
564RFC 3876          Returning Matched Values with LDAPv3    September 2004
565
566
56710.  Authors' Addresses
568
569   David Chadwick
570   IS Institute
571   University of Salford
572   Salford M5 4WT
573   England
574
575   Phone: +44 161 295 5351
576   EMail: d.w.chadwick@salford.ac.uk
577
578
579   Sean Mullan
580   Sun Microsystems
581   One Network Drive
582   Burlington, MA 01803
583   USA
584
585   EMail: sean.mullan@sun.com
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618Chadwick & Mullan           Standards Track                    [Page 11]
619
620RFC 3876          Returning Matched Values with LDAPv3    September 2004
621
622
62311.  Full Copyright Statement
624
625   Copyright (C) The Internet Society (2004).
626
627   This document is subject to the rights, licenses and restrictions
628   contained in BCP 78, and except as set forth therein, the authors
629   retain all their rights.
630
631   This document and the information contained herein are provided on an
632   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE
633   REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
634   INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
635   IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
636   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
637   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
638
639Intellectual Property
640
641   The IETF takes no position regarding the validity or scope of any
642   Intellectual Property Rights or other rights that might be claimed to
643   pertain to the implementation or use of the technology described in
644   this document or the extent to which any license under such rights
645   might or might not be available; nor does it represent that it has
646   made any independent effort to identify any such rights.  Information
647   on the IETF's procedures with respect to rights in IETF Documents can
648   be found in BCP 78 and BCP 79.
649
650   Copies of IPR disclosures made to the IETF Secretariat and any
651   assurances of licenses to be made available, or the result of an
652   attempt made to obtain a general license or permission for the use of
653   such proprietary rights by implementers or users of this
654   specification can be obtained from the IETF on-line IPR repository at
655   http://www.ietf.org/ipr.
656
657   The IETF invites any interested party to bring to its attention any
658   copyrights, patents or patent applications, or other proprietary
659   rights that may cover technology that may be required to implement
660   this standard.  Please address the information to the IETF at ietf-
661   ipr@ietf.org.
662
663Acknowledgement
664
665   Funding for the RFC Editor function is currently provided by the
666   Internet Society.
667
668
669
670
671
672
673
674Chadwick & Mullan           Standards Track                    [Page 12]
675
676