Sync usage with man page.
[netbsd-mini2440.git] / external / bsd / openldap / dist / doc / rfc / rfc3876.txt
blob4e3f04650e675966a9136bffee5ac65c578dfc69
7 Network Working Group                                        D. Chadwick
8 Request for Comments: 3876                         University of Salford
9 Category: Standards Track                                      S. Mullan
10                                                         Sun Microsystems
11                                                           September 2004
14                    Returning Matched Values with the
15         Lightweight Directory Access Protocol version 3 (LDAPv3)
17 Status of this Memo
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.
25 Copyright Notice
27    Copyright (C) The Internet Society (2004).
29 Abstract
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.
38 1.  Introduction
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
58 Chadwick & Mullan           Standards Track                     [Page 1]
60 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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.
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.
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].
78 2.  The valuesReturnFilter Control
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.
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.
94    The object identifier for this control is 1.2.826.0.1.3344810.2.3.
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.
100            ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem
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 }
114 Chadwick & Mullan           Standards Track                     [Page 2]
116 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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}
125    All the above data types have their standard meanings as defined in
126    [2].
128    If the server supports this control, the server MUST make use of the
129    control as follows:
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.
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.
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.
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:
149       i)  Every attribute value that evaluates TRUE against one or more
150           elements of the ValuesReturnFilter is placed in the
151           corresponding SearchResultEntry.
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.
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.
170 Chadwick & Mullan           Standards Track                     [Page 3]
172 RFC 3876          Returning Matched Values with LDAPv3    September 2004
175 3.  Relationship to X.500
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.
190 4.  Relationship to other LDAP Controls
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.
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.
216    For these reasons, the ValuesReturnFilter control in a SearchRequest
217    SHOULD precede other controls that affect the number and ordering of
218    SearchResultEntrys.
226 Chadwick & Mullan           Standards Track                     [Page 4]
228 RFC 3876          Returning Matched Values with LDAPv3    September 2004
231 5.  Examples
233    All entries are provided in an LDAP Data Interchange Format
234    (LDIF)[11].
236    The string representation of the valuesReturnFilter in the examples
237    below uses the following ABNF [15] notation:
239    valuesReturnFilter = "(" 1*simpleFilterItem ")"
240    simpleFilterItem = "(" item ")"
242    where item is as defined below (adapted from RFC2254 [14]).
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]
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).
266    The entries below represent organizationalPerson object classes
267    located somewhere beneath the distinguished name dc=ac,dc=uk.
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
282 Chadwick & Mullan           Standards Track                     [Page 5]
284 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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
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=*)).
301    The search results returned by the server would consist of the
302    following entry:
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
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.
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.
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).
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
338 Chadwick & Mullan           Standards Track                     [Page 6]
340 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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 )
352    plus another 28 - you get the idea.
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))
360    The search result returned by the server would consist of the
361    following entry:
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} )
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.
373    The entry below represents a pkiUser object class stored in the
374    directory.
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}
394 Chadwick & Mullan           Standards Track                     [Page 7]
396 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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)).
405    The search result returned by the server would consist of the
406    following entry:
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}
412 6.  Security Considerations
414    This document does not primarily discuss security issues.
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.
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).
430 7.  IANA Considerations
432    The Matched Values control as an LDAP Protocol Mechanism [7] has been
433    registered as follows:
435       Subject: Request for LDAP Protocol Mechanism Registration
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
450 Chadwick & Mullan           Standards Track                     [Page 8]
452 RFC 3876          Returning Matched Values with LDAPv3    September 2004
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].
460 8.  Acknowledgements
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.
468 9.  References
470 9.1.  Normative References
472    [1]  Bradner, S., "The Internet Standards Process -- Revision 3", BCP
473         9, RFC 2026, October 1996.
475    [2]  Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
476         Protocol (w3)", RFC 2251, December 1997.
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.
482    [4]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
483         Levels", BCP 14, RFC 2119, March 1997.
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
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)
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.
506 Chadwick & Mullan           Standards Track                     [Page 9]
508 RFC 3876          Returning Matched Values with LDAPv3    September 2004
511 9.2.  Informative References
513    [8]  ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
514         1993.
516    [9]  ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract
517         Service Definition.
519    [10] Sermersheim, J., "LDAP Control for a Duplicate Entry
520         Representation of Search Results", Work in Progress, October
521         2000.
523    [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical
524         Specification", RFC 2849, June 2000.
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
530    [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for
531         Server Side Sorting of Search Results", RFC 2891, August 2000.
533    [14] Howes, T., "The String Representation of LDAP Search Filters",
534         RFC 2254, December 1997.
536    [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax
537         Specifications: ABNF", RFC 2234, November 1997.
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.
562 Chadwick & Mullan           Standards Track                    [Page 10]
564 RFC 3876          Returning Matched Values with LDAPv3    September 2004
567 10.  Authors' Addresses
569    David Chadwick
570    IS Institute
571    University of Salford
572    Salford M5 4WT
573    England
575    Phone: +44 161 295 5351
576    EMail: d.w.chadwick@salford.ac.uk
579    Sean Mullan
580    Sun Microsystems
581    One Network Drive
582    Burlington, MA 01803
583    USA
585    EMail: sean.mullan@sun.com
618 Chadwick & Mullan           Standards Track                    [Page 11]
620 RFC 3876          Returning Matched Values with LDAPv3    September 2004
623 11.  Full Copyright Statement
625    Copyright (C) The Internet Society (2004).
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.
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.
639 Intellectual Property
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.
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.
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.
663 Acknowledgement
665    Funding for the RFC Editor function is currently provided by the
666    Internet Society.
674 Chadwick & Mullan           Standards Track                    [Page 12]