idnits 2.17.1 draft-ietf-ldapext-matchedval-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 6 instances of lines with non-ascii characters in the document. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 308 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The "Author's Address" (or "Authors' Addresses") section title is misspelled. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (8 September 1999) is 8994 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'ID/standard' on line 58 ** Obsolete normative reference: RFC 1777 (ref. '1') (Obsoleted by RFC 3494) ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (ref. '3') (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft David Chadwick 2 LDAPExt WG University of Salford 3 Intended Category: Standards Track Sean Mullan 4 Sun 5 Microsystems 6 Expires: 8 March 2000 8 September 1999 8 Returning Matched Values with LDAPv3 9 11 STATUS OF THIS MEMO 13 This document is an Internet-Draft and is in full conformance with 14 all the provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft expires on 8 March 2000. Comments and suggestions 32 on this document are encouraged. Comments on this document should be 33 sent to the LDAPExt working group discussion list: 34 ietf-ldapext@netscape.com 35 or directly to the authors. 37 ABSTRACT 39 This document describes a control for the Lightweight Directory 40 Access Protocol v3 that is used to return a subset of attribute 41 values from an entry, specifically, only those values that 42 contributed to the search filter evaluating to TRUE. Without support 43 for this control, a client must retrieve all of an attribute's values 44 and search for specific values locally. 46 1. Introduction 48 When reading an attribute from an entry using LDAP v2 [1] or LDAPv3 49 [2], it is normally only possible to read either the attribute type, 50 or the attribute type and all its values. It is not possible to 51 selectively read just a few of the attribute values. If an attribute 52 holds many values, for example, the userCertificate attribute, or the 53 subschema publishing operational attributes objectClasses and 54 attributeTypes [3], then it may be desirable for the user to be able 55 to selectively retrieve a subset of the values, specifically, those 56 attribute values that match the selection criteria as specified by 57 the user in the filter. Without the control specified in this 58 [ID/standard] a client must read all of the attribute's values and 59 filter out the unwanted values, necessitating the client to implement 60 the matching rules. It also requires the client to potentially read 61 and process many irrelevant values, which can be inefficient if the 62 values are large or complex, or there are many values stored per 63 attribute. 65 This Internet Draft specifies an LDAPv3 control to enable a user to 66 return only those values that matched (i.e. returned TRUE to) one or 67 more elements of the Search filter. This control can be especially 68 useful when used in conjunction with extensible matching rules that 69 match on one or more components of complex binary attribute values. 71 The control has been described in such a way as to be fully 72 compatible with the matchedValuesOnly boolean of the X.500 DAP [4] 73 Search argument, as amended in the latest version [6]. 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in RFC 2119 [5]. 79 2. The matchedValuesOnly Control 81 The matchedValuesOnly control MAY be critical or non-critical as 82 determined by the user. It is only applicable to the Search 83 operation, and SHALL be ignored by the server if it is present on any 84 other LDAP operation (even if marked critical on such operations). 86 The object identifier for this control is 1.2.826.0.1.3344810.2.2 88 The controlValue is absent. 90 If the server supports this control, the server MUST make use of the 91 control as follows: 93 (1) If the typesOnly parameter of the Search Request is TRUE, 94 the control has no effect and the Search Request SHOULD be 95 processed as if the control had not been specified. 97 (2) If the attributes parameter of the Search Request consists 98 of a list containing only the attribute with OID "1.1" 99 (specifying that no attributes are to be returned), the control 100 has no effect and the Search Request SHOULD be processed as if 101 the control had not been specified. 103 (3) For each attribute listed in the attributes parameter of the 104 Search Request, the server MUST apply the control as follows: 106 i) Every attribute value that evaluates TRUE against one or 107 more filters, excluding the ignored filters (see below), 108 is logically marked by the server as contributing to the 109 filter matching. 110 ii) Attributes that have no values marked as contributing, 111 have all their values returned to the user. 112 iii) Attributes that have one or more values marked as 113 contributing have only the contributing values returned to 114 the user, whilst the other values of the same attribute 115 (if there are any) are not returned. 117 Certain filters are ignored for the purposes of marking the attribute 118 values as contributing. These are: 120 the �present� filter, since this filter does not test against 121 any attribute values; 122 the �not� filter, since this would have the effect of marking 123 all the attribute values except the one(s) that matched the 124 non-negated filter. 126 3. Relationship to X.500 128 The matchedValuesOnly control defined in this document is derived 129 from the matchedValuesOnly boolean parameter of the X.511 (93) DAP 130 Search operation [4]. Note however that in X.511 (93), the 131 matchedValuesOnly parameter is ignored when used with an "equality" 132 match FilterItem, and so the user must use the extensibleMatch filter 133 along with the equality matching rule if only matched values are 134 wanted with equality matching. This slightly spurious equality match 135 restriction has been removed from the 2000 version of X.511 [6]. For 136 LDAP servers acting as a gateway to an X.500 directory, the matched 137 valuesOnly control can be directly mapped onto the X.511 138 matchedValuesOnly Search parameter as follows: 140 (1) If the matchedValuesOnly control is specified, the 141 matchedValuesOnly DAP parameter MUST be set to true. If the 142 control criticality value is TRUE then bit 17 of the DAP 143 criticalExtensions MUST be set. 145 (2) If an equality matching rule is specified in the filter of 146 the LDAPv3 search operation, then if operating with a pre-2000 147 edition DSA, the corresponding equality FilterItem contained in 148 the X.511 filter parameter MUST NOT be used, but rather the 149 extensibleMatch filter item MUST be used instead (the assertion 150 consisting of the equality matching rule, the attribute type to 151 match on, and the asserted value). When operating with DSAs 152 that support the 2000 DAP enhancement, the equality FilterItem 153 MAY be used. 155 4. Examples 157 (1) The first example simply shows how the control can be used to 158 selectively read a subset of attribute values. 160 The entry below represents a groupOfNames object class containing 161 several members from different organizations. 163 cn: Cross Organizational Standards Body 164 member: cn=joe, o=acme 165 member: cn=alice, o=acme 166 member: cn=bob, o=foo 167 member: cn=sue, o=bar 169 An LDAP search operation is specified with a baseObject set to the 170 DN of the entry, a baseObject scope, a filter set to 171 "member=*o=acme", and the list of attributes to be returned set to 172 "member". In addition, a matchedValuesOnly control is attached to the 173 search request. 175 The search results returned by the server would consist of the 176 following entry: 178 cn: Cross Organizational Standards Body 179 member: cn=joe, o=acme 180 member: cn=alice, o=acme 182 (2) The second example shows how the control has no effect on 183 attributes that do not participate in the search filter. 185 The entries below represent inetOrgPerson [7] object classes located 186 below some distinguished name in the directory. 188 cn: Sean Mullan 189 mail: sean.mullan@sun.com 190 mail: mullan@east.sun.com 191 telephoneNumber: +1 781 442 0926 192 telephoneNumber: 555-9999 194 cn: David Chadwick 195 mail: d.w.chadwick@salford.ac.uk 197 An LDAP search operation is specified with a baseObject set to the 198 DN of the entry, a subtree scope, a filter set to 199 "(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and 200 the list of attributes to be returned set to "mail telephoneNumber". 201 In addition, a matchedValuesOnly control is attached to the search 202 request. 204 The search results returned by the server would consist of the 205 following entries: 207 cn: Sean Mullan 208 mail: sean.mullan@sun.com 209 telephoneNumber: +1 781 442 0926 210 telephoneNumber: 555-9999 212 cn: David Chadwick 213 mail: d.w.chadwick@salford.ac.uk 215 Note that the control has no effect on the values returned for the 216 "telephoneNumber" attribute (all of the values are returned), since 217 it did not participate in the search filter. 219 5. Security Considerations 221 This Internet Draft does not discuss security issues at all. 223 Note that attribute values MUST only be returned if the access 224 controls applied by the LDAP server allow them to be returned, and in 225 this respect the effect of the matchedValuesOnly control is of no 226 consequence. 228 Note that the matchedValuesOnly control may have a positive effect on 229 the deployment of public key infrastructures. Certain PKI operations, 230 like searching for specific certificates, become more practical (when 231 combined with X.509 certificate matching rules at the server) and 232 more scalable, since the control avoids the downloading of 233 potentially large numbers of irrelevant certificates which would have 234 to be processed and filtered locally (which in some cases is very 235 difficult to perform). 237 6. Copyright 239 Copyright (C) The Internet Society (date). All Rights Reserved. 241 This document and translations of it may be copied and furnished to 242 others, and derivative works that comment on or otherwise explain it 243 or assist in its implementation may be prepared, copied, published 244 and distributed, in whole or in part, without restriction of any 245 kind, provided that the above copyright notice and this paragraph are 246 included on all such copies and derivative works. However, this 247 document itself may not be modified in any way, such as by removing 248 the copyright notice or references to the Internet Society or other 249 Internet organizations, except as needed for the purpose of 250 developing Internet standards in which case the procedures for 251 copyrights defined in the Internet Standards process must be 252 followed, or as required to translate it into languages other than 253 English. 255 The limited permissions granted above are perpetual and will not be 256 revoked by the Internet Society or its successors or assigns. 258 This document and the information contained herein is provided on an 259 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 260 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 261 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 262 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 263 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 265 7. References 267 [1] Yeong, W., Howes, T., and Kille, S. "Lightweight Directory Access 268 Protocol", RFC 1777, March 1995. 269 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 270 Protocol (v3)", Dec. 1997, RFC 2251 271 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, �Lightweight Directory 272 Access Protocol (v3): Attribute Syntax Definitions�, RFC 2252, Dec 273 1997 274 [4] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 275 1993. 276 [5] S.Bradner. "Key words for use in RFCs to Indicate Requirement 277 Levels", RFC 2119, March 1997. 278 [6] �FPDAMs to ISO/IEC 9594 Parts 1, 2, 3, 4, 5, 6, 7 and 9 to 279 support the ITU-T Rec. F.510 "Automated Directory Assistance, White 280 Pages Service Definitions"�, Collaborative ITU-T/SG7/Q15 and 281 JTC1/SC6/WG7 OSI Directory Meeting 7-15 April 1999, Orlando, USA 282 [7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class", 283 Internet Draft , April 1999. 285 8. Authors Addresses 287 David Chadwick 288 IS Institute 289 University of Salford 290 Salford M5 4WT 291 England 293 Email: d.w.chadwick@salford.ac.uk 295 Sean Mullan 296 Sun Microsystems Laboratories 297 One Network Drive 298 Burlington 299 MA 01803-0902 300 USA 302 Tel: +1 781 442-0926 Fax: +1 781 442-1692 303 Email: sean.mullan@sun.com 304 5