1 Internet-Draft David Chadwick
2 LDAPExt WG University of Salford
3 Intended Category: Standards Track Sean Mullan
5 Expires: 15 April 2001 16 October 2000
8 Returning Matched Values with LDAPv3
9 <draft-ietf-ldapext-matchedval-04.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 15 April 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 notation defined in RFC 2254 [11].
212 (1) The first example shows how the control can be set to return all
213 attribute values from one attribute type (e.g. telephoneNumber) and a
214 subset of values from another attribute type (e.g. mail).
216 The entries below represent organizationalPerson object classes
217 located somewhere beneath the distinguished name dc=ac, dc=uk.
219 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk
222 objectClass: organizationalPerson
224 objectClass: inetOrgPerson
225 mail: sean.mullan@hotmail.com
226 mail: mullan@east.sun.com
227 telephoneNumber: + 781 442 0926
228 telephoneNumber: 555-9999
230 dn: cn=David Chadwick, ou=isi, o=salford, dc=ac, dc=uk
233 objectClass: organizationalPerson
235 objectClass: inetOrgPerson
236 mail: d.w.chadwick@salford.ac.uk
238 An LDAP search operation is specified with a baseObject set to the
239 DN of the search base (i.e. dc=ac, dc=uk), a subtree scope, a filter
240 set to (sn=mullan), and the list of attributes to be returned set to
241 "mail, telephoneNumber". In addition, a ValuesReturnFilter control is
242 set to ((mail=*hotmail.com)(telephoneNumber=*))
244 The search results returned by the server would consist of the
247 dn: cn=Sean Mullan, ou=people, dc=sun, dc=ac, dc=uk
248 mail: sean.mullan@hotmail.com
249 telephoneNumber: + 781 442 0926
250 telephoneNumber: 555-9999
252 Note that the control has no effect on the values returned for the
253 "telephoneNumber" attribute (all of the values are returned), since
254 the control specified that all values should be returned.
257 (2) The second example shows how one might retrieve a single
258 attribute type subschema definition for the "gunk" attribute with OID
259 1.2.3.4.5 from the subschema subentry
261 Assume the subschema subentry is held below the root entry with DN
262 cn=subschema subentry, o=myorg and this holds an attributeTypes
263 operational attribute holding the descriptions of the 35 attributes
264 known to this server (each description is held as a single attribute
265 value of the attributeTypes attribute).
267 dn: cn=subschema subentry, o=myorg
268 cn: subschema subentry
269 objectClass: subschema
270 attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name )
271 attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )
272 attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY
273 objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
274 attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY
275 generalizedTimeMatch ORDERING generalizedTimeOrderingMatch
276 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-
277 MODIFICATION USAGE directoryOperation )
278 attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY
279 objectIdentifierFirstComponentMatch SYNTAX
280 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
281 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
282 SUBSTR caseIgnoreSubstringsMatch SYNTAX
283 1.3.6.1.4.1.1466.115.121.1.44{64} )
284 attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY
285 objectIdentifierFirstComponentMatch SYNTAX
286 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
288 plus another 28 - you get the idea.
291 The user creates an LDAP search operation with a baseObject set to
292 cn=subschema subentry, o=myorg, a scope of base, a filter set to
293 (objectClass=subschema), the list of attributes to be returned set to
294 "attributeTypes", and the ValuesReturnFilter set to
295 (attributeTypes=1.2.3.4.5)
297 The search result returned by the server would consist of the
300 dn: cn=subschema subentry, o=myorg
301 attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch
302 SUBSTR caseIgnoreSubstringsMatch SYNTAX
303 1.3.6.1.4.1.1466.115.121.1.44{64} )
306 (3) The final example shows how the control can be used to match on a
307 userCertificate attribute value with a particular key usage bit set
308 (in this case the key encipherment bit). Note that this example
309 requires the LDAP server to support the certificateMatch matching
310 rule defined in [9] and extensible matching.
312 The entry below represent a pkiUser object class stored in the
315 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University
317 cn: David Chadwick + serialNumber=123456
319 objectClass: organizationalPerson
321 objectClass: inetOrgPerson
323 mail: d.w.chadwick@salford.ac.uk
324 userCertificate: {binary representation of certificate including key
325 usage bit of digitalSignature (0)}
326 userCertificate: {binary representation of certificate including key
327 usage bit of nonRepudiation (1)}
328 userCertificate: {binary representation of certificate including key
329 usage bit of key encipherment (2)}
330 userCertificate: {binary representation of certificate including key
331 usage bit of data encipherment (3)}
333 An LDAP search operation is specified with a baseObject set to
334 o=University of Salford, c=gb, a subtree scope, a filter set to
335 (sn=chadwick) and the list of attributes to be returned set to
336 "userCertificate;binary". In addition, a ValuesReturnFilter control
337 is set to (userCertificate:2.5.13.35:=USE'001'B)
339 The search result returned by the server would consist of the
342 dn: cn=David Chadwick + serialNumber=123456, ou=people, o=University
344 userCertificate;binary: {binary representation of certificate with
345 key usage bit of key encipherment (2)}
348 6. Security Considerations
350 This [ID/standard/document] does not primarily discuss security
353 Note however that attribute values MUST only be returned if the
354 access controls applied by the LDAP server allow them to be returned,
355 and in this respect the effect of the ValuesReturnFilter control is
358 Note that the ValuesReturnFilter control may have a positive effect
359 on the deployment of public key infrastructures. Certain PKI
360 operations, like searching for specific certificates, become more
361 practical when combined with X.509 certificate matching rules at the
362 server, and more scalable, since the control avoids the downloading
363 of potentially large numbers of irrelevant certificates which would
364 have to be processed and filtered locally (which in some cases is
365 very difficult to perform).
370 The authors would like to thank members of the LDAPExt list for their
371 constructive comments on earlier versions of this
372 [ID/standard/document], and in particular to Harald Alvestrand who
373 first suggested having an attribute return filter and Bruce
374 Greenblatt who first proposed a syntax for this control.
378 Copyright (C) The Internet Society (date). All Rights Reserved.
380 This document and translations of it may be copied and furnished to
381 others, and derivative works that comment on or otherwise explain it
382 or assist in its implementation may be prepared, copied, published
383 and distributed, in whole or in part, without restriction of any
384 kind, provided that the above copyright notice and this paragraph are
385 included on all such copies and derivative works. However, this
386 document itself may not be modified in any way, such as by removing
387 the copyright notice or references to the Internet Society or other
388 Internet organizations, except as needed for the purpose of
389 developing Internet standards in which case the procedures for
390 copyrights defined in the Internet Standards process must be
391 followed, or as required to translate it into languages other than
394 The limited permissions granted above are perpetual and will not be
395 revoked by the Internet Society or its successors or assigns.
397 This document and the information contained herein is provided on an
398 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
399 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
400 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
401 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
402 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
407 [1] S. Bradner. "The Internet Standards Process -- Revision 3", RFC
409 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
410 Protocol (v3)", Dec. 1997, RFC 2251
411 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
412 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, Dec
414 [4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
416 [5] S.Bradner. "Key words for use in RFCs to Indicate Requirement
417 Levels", RFC 2119, March 1997.
418 [6] Draft ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory:
419 Abstract Service Definition.
420 [7] J. Sermersheim. "LDAP Control for a Duplicate Entry
421 Representation of Search Results", Internet Draft <draft-ietf-
422 ldapext-ldapv3-dupent-04.txt>, July 2000.
423 [8] G. Good. "The LDAP Data Interchange Format (LDIF) - Technical
424 Specification". RFC 2849, June 2000.
425 [9] D. Chadwick, S.Legg. "Internet X.509 Public Key Infrastructure -
426 Additional LDAP Schema for PKIs and PMIs", Internet Draft <draft-
427 pkix-ldap-schema-01.txt>, September 2000
428 [10] T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension for
429 Server Side Sorting of Search Results", RFC 2891, August 2000
430 [11] T. Howes. "The String Representation of LDAP Search Filters".
431 RFC 2254, December 1997.
433 10. Authors Addresses
437 University of Salford
441 Email: d.w.chadwick@salford.ac.uk
442 Tel: +44 161 295 5351
446 East Point Business Park
450 Email: sean.mullan@sun.com
453 11. Changes since version 2
455 i) Revised the examples to be more appropriate
456 ii) Section on interactions with other LDAP controls added
457 iii) Removed Editor's note concerning present filter
458 iv) Tightened wording about its applicability to other operations
459 and use of criticality field
461 Changes since version 3
463 i) Mandated that at least one of type and matchingRule in
464 simpleMatchingAssertion be present
465 ii) Fixed LDIF mistakes in the examples
466 iii) Additional minor editorials only