1 Internet-Draft David Chadwick
2 LDAPExt WG University of Salford
3 Intended Category: Standards Track Sean Mullan
5 Expires: 11 June 2001 11 December 2000
8 Returning Matched Values with LDAPv3
9 <draft-ietf-ldapext-matchedval-05.txt>
14 This document is an Internet-Draft and is in full conformance with
15 all the provisions of Section 10 of RFC2026 [1].
17 Internet-Drafts are working documents of the Internet Engineering
18 Task Force (IETF), its areas, and its working groups. Note that other
19 groups may also distribute working documents as Internet-Drafts.
21 Internet-Drafts are draft documents valid for a maximum of six months
22 and may be updated, replaced, or obsoleted by other documents at any
23 time. It is inappropriate to use Internet-Drafts as reference
24 material or to cite them other than as "work in progress."
26 The list of current Internet-Drafts can be accessed at
27 http://www.ietf.org/ietf/1id-abstracts.txt.
29 The list of Internet-Draft Shadow Directories can be accessed at
30 http://www.ietf.org/shadow.html.
32 This Internet-Draft expires on 11 June 2001.
34 Comments and suggestions on this document are encouraged. Comments on
35 this document should be sent to the LDAPEXT working group discussion
37 ietf-ldapext@netscape.com
39 or directly to the authors.
44 This document describes a control for the Lightweight Directory
45 Access Protocol v3 that is used to return a subset of attribute
46 values from an entry, specifically, only those values that match a
47 "values return" filter. Without support for this control, a client
48 must retrieve all of an attribute's values and search for specific
54 When reading an attribute from an entry using LDAPv3 [2], it is
55 normally only possible to read either the attribute type, or the
56 attribute type and all its values. It is not possible to selectively
57 read just a few of the attribute values. If an attribute holds many
58 values, for example, the userCertificate attribute, or the subschema
59 publishing operational attributes objectClasses and attributeTypes
60 [3], then it may be desirable for the user to be able to selectively
61 retrieve a subset of the values, specifically, those attribute values
62 that match some user defined selection criteria. Without the control
63 specified in this [ID/standard/document] a client must read all of
64 the attribute's values and filter out the unwanted values,
65 necessitating the client to implement the matching rules. It also
66 requires the client to potentially read and process many irrelevant
67 values, which can be inefficient if the values are large or complex,
68 or there are many values stored per attribute.
70 This [ID/Standard/document] specifies an LDAPv3 control to enable a
71 user to return only those values that matched (i.e. returned TRUE to)
72 one or more elements of a newly defined "values return" filter. This
73 control can be especially useful when used in conjunction with
74 extensible matching rules that match on one or more components of
75 complex binary attribute values.
77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
79 document are to be interpreted as described in RFC 2119 [5].
82 2. The valuesReturnFilter Control
84 The valuesReturnFilter control MAY be critical or non-critical as
85 determined by the user. It only has meaning for the Search operation,
86 and SHOULD only be added to the Search operation by the client. If
87 the server supports the control and it is present on a Search
88 operation, the server MUST obey the control regardless of the value
89 of the criticality flag.
91 If the control is marked as critical, and either the server does not
92 support the control or the control is applied to an operation other
93 than Search, then the server MUST return an
94 unavailableCriticalExtension error. If the control is not marked as
95 critical, and either the server does not support the control or the
96 control is applied to an operation other than Search, then the server
97 MUST ignore the control.
99 The object identifier for this control is 1.2.826.0.1.3344810.2.3
101 The controlValue is an OCTET STRING, whose value is the BER encoding
102 of a value of the type ValuesReturnFilter.
104 ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem
106 SimpleFilterItem ::= CHOICE {
107 equalityMatch [3] AttributeValueAssertion,
108 substrings [4] SubstringFilter,
109 greaterOrEqual [5] AttributeValueAssertion,
110 lessOrEqual [6] AttributeValueAssertion,
111 present [7] AttributeDescription,
112 approxMatch [8] AttributeValueAssertion,
113 extensibleMatch [9] SimpleMatchingAssertion }
115 SimpleMatchingAssertion ::= SEQUENCE {
116 matchingRule [1] MatchingRuleId OPTIONAL,
117 type [2] AttributeDescription OPTIONAL,
118 --- at least one of the above must be present
119 matchValue [3] AssertionValue}
121 All the above data types have their standard meanings as defined in
124 If the server supports this control, the server MUST make use of the
127 (1) The Search Filter is first executed in order to determine
128 which entries satisfy the Search criteria (these are the
129 filtered entries). The control has no impact on this step.
131 (2) If the typesOnly parameter of the Search Request is TRUE,
132 the control has no effect and the Search Request SHOULD be
133 processed as if the control had not been specified.
135 (3) If the attributes parameter of the Search Request consists
136 of a list containing only the attribute with OID "1.1"
137 (specifying that no attributes are to be returned), the control
138 has no effect and the Search Request SHOULD be processed as if
139 the control had not been specified.
141 (4) For each attribute listed in the attributes parameter of the
142 Search Request, the server MUST apply the control as follows to
143 each entry in the set of filtered entries:
145 i) Every attribute value that evaluates TRUE against one or
146 more elements of the ValuesReturnFilter is placed in the
147 corresponding SearchResultEntry.
148 ii) Every attribute value that evaluates FALSE or undefined
149 against all elements of the ValuesReturnFilter is not
150 placed in the corresponding SearchResultEntry. An
151 attribute that has no values selected is returned with an
154 Note. If the AttributeDescriptionList is empty or comprises "*"
155 then the control MUST be applied against every attribute.
158 3. Relationship to X.500
160 The control is a superset of the matchedValuesOnly (MVO) boolean of
161 the X.500 DAP [4] Search argument, as amended in the latest version
162 [6]. Close examination of the matchedValuesOnly boolean by the
163 LDAPEXT group revealed ambiguities and complexities in the MVO
164 boolean that could not easily be resolved. For example, it was not
165 clear if the MVO boolean governed only those attribute values that
166 contributed to the overall truth of the filter, or all of the
167 attribute values even if the filter item containing the attribute
168 evaluated to false. For this reason the LDAPEXT group decided to
169 replace the MVO boolean with a simple filter that removes any
170 uncertainty as to whether an attribute value has been selected or
174 4. Relationship to other LDAP Controls
176 The purpose of this control is to select zero, one or more attribute
177 values from each requested attribute in a filtered entry, and to
178 discard the remainder. Once the attribute values have been discarded
179 by this control they MUST NOT be re-instated into the Search results
182 This control acts independently of other LDAP controls such as server
183 side sorting [10] and duplicate entries [7]. However, there might be
184 interactions between this control and other controls so that a
185 different set of Search Result Entries are returned, or the entries
186 are returned in a different order, depending upon the sequencing of
187 this control and other controls in the LDAP request. For example,
188 with server side sorting, if sorting is done first, and value return
189 filtering second, the set of Search Results may appear to be in the
190 wrong order since the value filtering may remove the attribute values
191 upon which the ordering was done. (The sorting document specifies
192 that entries without any sort key attribute values should be treated
193 as coming after all other attribute values.) Similarly with duplicate
194 entries, if duplication is performed before value filtering, the set
195 of Search Result Entries may contain identical duplicate entries,
196 each with an empty set of attribute values, because the value
197 filtering removed the attribute values that were used to duplicate
200 For these reasons it is recommended that the ValuesReturnFilter
201 control in a SearchRequest SHOULD precede other controls that affect
202 the number and ordering of SearchResultEntrys.
207 All entries are provided in LDIF format [8].
209 The string representation of the valuesReturnFilter in the examples
210 below uses the following ABNF notation:
212 valuesReturnFilter = "(" 1*simpleFilterItem ")"
213 simpleFilterItem = "(" item ")"
215 where item is as defined by RFC2254 [11].
217 (1) The first example shows how the control can be set to return all
218 attribute values from one attribute type (e.g. telephoneNumber) and a
219 subset of values from another attribute type (e.g. mail).
221 The entries below represent organizationalPerson object classes
222 located somewhere beneath the distinguished name dc=ac, dc=uk.
224 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk
227 objectClass: organizationalPerson
229 objectClass: inetOrgPerson
230 mail: sean.mullan@hotmail.com
231 mail: mullan@east.sun.com
232 telephoneNumber: + 781 442 0926
233 telephoneNumber: 555-9999
235 dn: cn=David Chadwick, ou=isi, o=salford, dc=ac, dc=uk
238 objectClass: organizationalPerson
240 objectClass: inetOrgPerson
241 mail: d.w.chadwick@salford.ac.uk
243 An LDAP search operation is specified with a baseObject set to the
244 DN of the search base (i.e. dc=ac, dc=uk), a subtree scope, a filter
245 set to (sn=mullan), and the list of attributes to be returned set to
246 "mail, telephoneNumber". In addition, a ValuesReturnFilter control is
247 set to ((mail=*hotmail.com)(telephoneNumber=*))
249 The search results returned by the server would consist of the
252 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk
253 mail: sean.mullan@hotmail.com
254 telephoneNumber: + 781 442 0926
255 telephoneNumber: 555-9999
257 Note that the control has no effect on the values returned for the
258 "telephoneNumber" attribute (all of the values are returned), since
259 the control specified that all values should be returned.
262 (2) The second example shows how one might retrieve a single
263 attribute type subschema definition for the "gunk" attribute with OID
264 1.2.3.4.5 from the subschema subentry
266 Assume the subschema subentry is held below the root entry with DN
267 cn=subschema subentry, o=myorg and this holds an attributeTypes
268 operational attribute holding the descriptions of the 35 attributes
269 known to this server (each description is held as a single attribute
270 value of the attributeTypes attribute).
272 dn: cn=subschema subentry, o=myorg
273 cn: subschema subentry
274 objectClass: subschema
275 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )
276 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
277 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY
278 objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
279 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY
280 generalizedTimeMatch ORDERING generalizedTimeOrderingMatch
281 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-
282 MODIFICATION USAGE directoryOperation )
283 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY
284 objectIdentifierFirstComponentMatch SYNTAX
285 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
286 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
287 SUBSTR caseIgnoreSubstringsMatch SYNTAX
288 1.3.6.1.4.1.1466.115.121.1.44{64} )
289 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY
290 objectIdentifierFirstComponentMatch SYNTAX
291 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
293 plus another 28 - you get the idea.
296 The user creates an LDAP search operation with a baseObject set to
297 cn=subschema subentry, o=myorg, a scope of base, a filter set to
298 (objectClass=subschema), the list of attributes to be returned set to
299 "attributeTypes", and the ValuesReturnFilter set to
300 ((attributeTypes=1.2.3.4.5))
302 The search result returned by the server would consist of the
305 dn: cn=subschema subentry, o=myorg
306 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
307 SUBSTR caseIgnoreSubstringsMatch SYNTAX
308 1.3.6.1.4.1.1466.115.121.1.44{64} )
311 (3) The final example shows how the control can be used to match on a
312 userCertificate attribute value with a particular key usage bit set
313 (in this case the key encipherment bit). Note that this example
314 requires the LDAP server to support the certificateMatch matching
315 rule defined in [9] and extensible matching.
317 The entry below represent a pkiUser object class stored in the
320 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University
322 cn: David Chadwick + serialNumber=123456
324 objectClass: organizationalPerson
326 objectClass: inetOrgPerson
328 mail: d.w.chadwick@salford.ac.uk
329 userCertificate: {binary representation of certificate including key
330 usage bit of digitalSignature (0)}
331 userCertificate: {binary representation of certificate including key
332 usage bit of nonRepudiation (1)}
333 userCertificate: {binary representation of certificate including key
334 usage bit of key encipherment (2)}
335 userCertificate: {binary representation of certificate including key
336 usage bit of data encipherment (3)}
338 An LDAP search operation is specified with a baseObject set to
339 o=University of Salford, c=gb, a subtree scope, a filter set to
340 (sn=chadwick) and the list of attributes to be returned set to
341 "userCertificate;binary". In addition, a ValuesReturnFilter control
342 is set to ((userCertificate:2.5.13.35:=(USE'001'B)))
344 The search result returned by the server would consist of the
347 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University
349 userCertificate;binary: {binary representation of certificate with
350 key usage bit of key encipherment (2)}
353 6. Security Considerations
355 This [ID/standard/document] does not primarily discuss security
358 Note however that attribute values MUST only be returned if the
359 access controls applied by the LDAP server allow them to be returned,
360 and in this respect the effect of the ValuesReturnFilter control is
363 Note that the ValuesReturnFilter control may have a positive effect
364 on the deployment of public key infrastructures. Certain PKI
365 operations, like searching for specific certificates, become more
366 practical when combined with X.509 certificate matching rules at the
367 server, and more scalable, since the control avoids the downloading
368 of potentially large numbers of irrelevant certificates which would
369 have to be processed and filtered locally (which in some cases is
370 very difficult to perform).
375 The authors would like to thank members of the LDAPExt list for their
376 constructive comments on earlier versions of this
377 [ID/standard/document], and in particular to Harald Alvestrand who
378 first suggested having an attribute return filter and Bruce
379 Greenblatt who first proposed a syntax for this control.
383 Copyright (C) The Internet Society (date). All Rights Reserved.
385 This document and translations of it may be copied and furnished to
386 others, and derivative works that comment on or otherwise explain it
387 or assist in its implementation may be prepared, copied, published
388 and distributed, in whole or in part, without restriction of any
389 kind, provided that the above copyright notice and this paragraph are
390 included on all such copies and derivative works. However, this
391 document itself may not be modified in any way, such as by removing
392 the copyright notice or references to the Internet Society or other
393 Internet organizations, except as needed for the purpose of
394 developing Internet standards in which case the procedures for
395 copyrights defined in the Internet Standards process must be
396 followed, or as required to translate it into languages other than
399 The limited permissions granted above are perpetual and will not be
400 revoked by the Internet Society or its successors or assigns.
402 This document and the information contained herein is provided on an
403 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
404 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
405 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
406 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
407 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
412 [1] S. Bradner. "The Internet Standards Process -- Revision 3", RFC
414 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
415 Protocol (v3)", Dec. 1997, RFC 2251
416 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
417 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec
419 [4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
421 [5] S.Bradner. "Key words for use in RFCs to Indicate Requirement
422 Levels", RFC 2119, March 1997.
423 [6] Draft ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory:
424 Abstract Service Definition.
425 [7] J. Sermersheim. "LDAP Control for a Duplicate Entry
426 Representation of Search Results", Internet Draft <draft-ietf-
427 ldapext-ldapv3-dupent-06.txt>, October 2000.
428 [8] G. Good. "The LDAP Data Interchange Format (LDIF) - Technical
429 Specification". RFC 2849, June 2000.
430 [9] D. Chadwick, S.Legg. "Internet X.509 Public Key Infrastructure -
431 Additional LDAP Schema for PKIs and PMIs", Internet Draft <draft-
432 pkix-ldap-schema-01.txt>, September 2000
433 [10] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for
434 Server Side Sorting of Search Results", RFC 2891, August 2000
435 [11] T. Howes. "The String Representation of LDAP Search Filters".
436 RFC 2254, December 1997.
438 10. Authors Addresses
442 University of Salford
446 Email: d.w.chadwick@salford.ac.uk
447 Tel: +44 161 295 5351
451 East Point Business Park
455 Email: sean.mullan@sun.com
458 11. Changes since version 2
460 i) Revised the examples to be more appropriate
461 ii) Section on interactions with other LDAP controls added
462 iii) Removed Editor's note concerning present filter
463 iv) Tightened wording about its applicability to other operations
464 and use of criticality field
466 Changes since version 3
468 i) Mandated that at least one of type and matchingRule in
469 simpleMatchingAssertion be present
470 ii) Fixed LDIF mistakes in the examples
471 iii) Additional minor editorials only
473 Changes since version 4
475 i) corrected the ABNF for single items of valuesReturnFilter