From d57ab41dcdcdc005c51c8fab6c5fa7d9be3358ff Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Sat, 11 Sep 2004 22:10:00 +0000 Subject: [PATCH] Sync with HEAD --- .../draft-ietf-ldapext-matchedval-xx.txt | Bin 20478 -> 0 bytes doc/rfc/INDEX | 1 + doc/rfc/rfc3876.txt | 675 ++++++++++++++++++ 3 files changed, 676 insertions(+) delete mode 100644 doc/drafts/draft-ietf-ldapext-matchedval-xx.txt create mode 100644 doc/rfc/rfc3876.txt diff --git a/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt b/doc/drafts/draft-ietf-ldapext-matchedval-xx.txt deleted file mode 100644 index 14849a5decb7a662c9409c01360d200142d7bbcf..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20478 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 XW4qGG9Ulaf-LTN9ROpy_alQTzQIr>U diff --git a/doc/rfc/INDEX b/doc/rfc/INDEX index 33d6e31602..5f00a1c6ca 100644 --- a/doc/rfc/INDEX +++ b/doc/rfc/INDEX @@ -45,6 +45,7 @@ rfc3727.txt ASN.1 Module for LDAP Component Matching Rules (PS) rfc3771.txt LDAP: Intermediate Response Message (PS) rfc3829.txt LDAP Authorization Identity Controls (I) rfc3866.txt Language Tag and Ranges in LDAP (PS) +rfc3876.txt Returning Matched Values with LDAP (PS) Legend: STD Standard diff --git a/doc/rfc/rfc3876.txt b/doc/rfc/rfc3876.txt new file mode 100644 index 0000000000..4e3f04650e --- /dev/null +++ b/doc/rfc/rfc3876.txt @@ -0,0 +1,675 @@ + + + + + + +Network Working Group D. Chadwick +Request for Comments: 3876 University of Salford +Category: Standards Track S. Mullan + Sun Microsystems + September 2004 + + + Returning Matched Values with the + Lightweight Directory Access Protocol version 3 (LDAPv3) + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2004). + +Abstract + + This document describes a control for the Lightweight Directory + Access Protocol version 3 that is used to return a subset of + attribute values from an entry. Specifically, only those values that + match a "values return" filter. Without support for this control, a + client must retrieve all of an attribute's values and search for + specific values locally. + +1. Introduction + + When reading an attribute from an entry using the Lightweight + Directory Access Protocol version 3 (LDAPv3) [2], it is normally only + possible to read either the attribute type, or the attribute type and + all its values. It is not possible to selectively read just a few of + the attribute values. If an attribute holds many values, for + example, the userCertificate attribute, or the subschema publishing + operational attributes objectClasses and attributeTypes [3], then it + may be desirable for the user to be able to selectively retrieve a + subset of the values, specifically, those attribute values that match + some user defined selection criteria. Without the control specified + in this document, a client must read all of the attribute's values + and filter out the unwanted values, necessitating the client to + implement the matching rules. It also requires the client to + + + + + +Chadwick & Mullan Standards Track [Page 1] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + potentially read and process many irrelevant values, which can be + inefficient if the values are large or complex, or there are many + values stored per attribute. + + This document specifies an LDAPv3 control to enable a user to return + only those values that matched (i.e., returned TRUE to) one or more + elements of a newly defined "values return" filter. This control can + be especially useful when used in conjunction with extensible + matching rules that match on one or more components of complex binary + attribute values. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in BCP 14, RFC 2119 [4]. + +2. The valuesReturnFilter Control + + The valuesReturnFilter control is either critical or non-critical as + determined by the user. It only has meaning for the Search + operation, and SHOULD only be added to the Search operation by the + client. If the server supports the control and it is present on a + Search operation, the server MUST obey the control, regardless of the + value of the criticality flag. + + If the control is marked as critical, and either the server does not + support the control or the control is applied to an operation other + than Search, the server MUST return an unavailableCriticalExtension + error. If the control is not marked as critical, and either the + server does not support the control or the control is applied to an + operation other than Search, then the server MUST ignore the control. + + The object identifier for this control is 1.2.826.0.1.3344810.2.3. + + The controlValue is an OCTET STRING, whose value is the BER encoding + [6], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 [5] + type ValuesReturnFilter. + + ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem + + SimpleFilterItem ::= CHOICE { + equalityMatch [3] AttributeValueAssertion, + substrings [4] SubstringFilter, + greaterOrEqual [5] AttributeValueAssertion, + lessOrEqual [6] AttributeValueAssertion, + present [7] AttributeDescription, + approxMatch [8] AttributeValueAssertion, + extensibleMatch [9] SimpleMatchingAssertion } + + + + +Chadwick & Mullan Standards Track [Page 2] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + SimpleMatchingAssertion ::= SEQUENCE { + matchingRule [1] MatchingRuleId OPTIONAL, + type [2] AttributeDescription OPTIONAL, + --- at least one of the above must be present + matchValue [3] AssertionValue} + + All the above data types have their standard meanings as defined in + [2]. + + If the server supports this control, the server MUST make use of the + control as follows: + + 1) The Search Filter is first executed in order to determine which + entries satisfy the Search criteria (these are the filtered + entries). The control has no impact on this step. + + 2) If the typesOnly parameter of the Search Request is TRUE, the + control has no effect and the Search Request is processed as if + the control had not been specified. + + 3) If the attributes parameter of the Search Request consists of a + list containing only the attribute with OID "1.1" (specifying that + no attributes are to be returned), the control has no effect and + the Search Request is processed as if the control had not been + specified. + + 4) For each attribute listed in the attributes parameter of the + Search Request, the server MUST apply the control as follows to + each entry in the set of filtered entries: + + i) Every attribute value that evaluates TRUE against one or more + elements of the ValuesReturnFilter is placed in the + corresponding SearchResultEntry. + + ii) Every attribute value that evaluates FALSE or undefined + against all elements of the ValuesReturnFilter is not placed + in the corresponding SearchResultEntry. An attribute that has + no values selected is returned with an empty set of values. + + Note. If the AttributeDescriptionList (see [2]) is empty or + comprises "*", then the control MUST be applied against every user + attribute. If the AttributeDescriptionList contains a "+", then the + control MUST be applied against every operational attribute. + + + + + + + + +Chadwick & Mullan Standards Track [Page 3] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + +3. Relationship to X.500 + + The control is a superset of the matchedValuesOnly (MVO) boolean of + the X.500 Directory Access Protocol (DAP) [8] Search argument, as + amended in the latest version [9]. Close examination of the + matchedValuesOnly boolean by the LDAP Extensions (LDAPEXT) Working + Group revealed ambiguities and complexities in the MVO boolean that + could not easily be resolved. For example, it was not clear if the + MVO boolean governed only those attribute values that contributed to + the overall truth of the filter, or all of the attribute values, even + if the filter item containing the attribute was evaluated as false. + For this reason the LDAPEXT group decided to replace the MVO boolean + with a simple filter that removes any uncertainty as to whether an + attribute value has been selected or not. + +4. Relationship to other LDAP Controls + + The purpose of this control is to select zero, one, or more attribute + values from each requested attribute in a filtered entry, and to + discard the remainder. Once the attribute values have been discarded + by this control, they MUST NOT be re-instated into the Search results + by other controls. + + This control acts independently of other LDAP controls such as server + side sorting [13] and duplicate entries [10]. However, there might + be interactions between this control and other controls so that a + different set of Search Result Entries are returned, or the entries + are returned in a different order, depending upon the sequencing of + this control and other controls in the LDAP request. For example, + with server side sorting, if sorting is done first, and value return + filtering second, the set of Search Results may appear to be in the + wrong order since the value filtering may remove the attribute values + upon which the ordering was done. (The sorting document specifies + that entries without any sort key attribute values should be treated + as coming after all other attribute values.) Similarly with + duplicate entries, if duplication is performed before value + filtering, the set of Search Result Entries may contain identical + duplicate entries, each with an empty set of attribute values, + because the value filtering removed the attribute values that were + used to duplicate the results. + + For these reasons, the ValuesReturnFilter control in a SearchRequest + SHOULD precede other controls that affect the number and ordering of + SearchResultEntrys. + + + + + + + +Chadwick & Mullan Standards Track [Page 4] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + +5. Examples + + All entries are provided in an LDAP Data Interchange Format + (LDIF)[11]. + + The string representation of the valuesReturnFilter in the examples + below uses the following ABNF [15] notation: + + valuesReturnFilter = "(" 1*simpleFilterItem ")" + simpleFilterItem = "(" item ")" + + where item is as defined below (adapted from RFC2254 [14]). + + item = simple / present / substring / extensible + simple = attr filtertype value + filtertype = equal / approx / greater / less + equal = "=" + approx = "~=" + greater = ">=" + less = "<=" + extensible = attr [":" matchingrule] ":=" value + / ":" matchingrule ":=" value + present = attr "=*" + substring = attr "=" [initial] any [final] + initial = value + any = "*" *(value "*") + final = value + attr = AttributeDescription from Section 4.1.5 of [1] + matchingrule = MatchingRuleId from Section 4.1.9 of [1] + value = AttributeValue from Section 4.1.6 of [1] + + 1) The first example shows how the control can be set to return all + attribute values from one attribute type (e.g., telephoneNumber) + and a subset of values from another attribute type (e.g., mail). + + The entries below represent organizationalPerson object classes + located somewhere beneath the distinguished name dc=ac,dc=uk. + + dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk + cn: Sean Mullan + sn: Mullan + objectClass: organizationalPerson + objectClass: person + objectClass: inetOrgPerson + mail: sean.mullan@hotmail.com + mail: mullan@east.sun.com + telephoneNumber: + 781 442 0926 + telephoneNumber: 555-9999 + + + +Chadwick & Mullan Standards Track [Page 5] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk + cn: David Chadwick + sn: Chadwick + objectClass: organizationalPerson + objectClass: person + objectClass: inetOrgPerson + mail: d.w.chadwick@salford.ac.uk + + An LDAP search operation is specified with a baseObject set to the DN + of the search base (i.e., dc=ac,dc=uk), a subtree scope, a filter set + to (sn=mullan), and the list of attributes to be returned set to + "mail,telephoneNumber" or "*". In addition, a ValuesReturnFilter + control is set to ((mail=*hotmail.com)(telephoneNumber=*)). + + The search results returned by the server would consist of the + following entry: + + dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk + mail: sean.mullan@hotmail.com + telephoneNumber: + 781 442 0926 + telephoneNumber: 555-9999 + + Note that the control has no effect on the values returned for the + "telephoneNumber" attribute (all of the values are returned), since + the control specified that all values should be returned. + + 2) The second example shows how one might retrieve a single attribute + type subschema definition for the "gunk" attribute with OID + 1.2.3.4.5 from the subschema subentry. + + Assume the subschema subentry is held below the root entry with DN + cn=subschema subentry,o=myorg and this holds an attributeTypes + operational attribute holding the descriptions of the 35 attributes + known to this server (each description is held as a single attribute + value of the attributeTypes attribute). + + dn: cn=subschema subentry,o=myorg + cn: subschema subentry + objectClass: subschema + attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) + attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) + attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY obj + ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen + eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN + TAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- + MODIFICATION USAGE directoryOperation ) + attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY obj + + + +Chadwick & Mullan Standards Track [Page 6] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + ectIdentifierFirstComponentMatch SYNTAX 1.3. + 6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) + attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat + ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. + 6.1.4.1.1466.115.121.1.44{64} ) + attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj + ectIdentifierFirstComponentMatch SYNTAX 1.3. + 6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) + + plus another 28 - you get the idea. + + The user creates an LDAP search operation with a baseObject set to + cn=subschema subentry,o=myorg, a scope of base, a filter set to + (objectClass=subschema), the list of attributes to be returned set to + "attributeTypes", and the ValuesReturnFilter set to + ((attributeTypes=1.2.3.4.5)) + + The search result returned by the server would consist of the + following entry: + + dn: cn=subschema subentry,o=myorg + attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat + ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. + 6.1.4.1.1466.115.121.1.44{64} ) + + 3) The final example shows how the control can be used to match on a + userCertificate attribute value. Note that this example requires + the LDAP server to support the certificateExactMatch matching rule + defined in [12] as the EQUALITY matching rule for userCertificate. + + The entry below represents a pkiUser object class stored in the + directory. + + dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb + cn: David Chadwick + objectClass: person + objectClass: organizationalPerson + objectClass: pkiUser + objectClass: inetOrgPerson + sn: Chadwick + mail: d.w.chadwick@salford.ac.uk + userCertificate;binary: {binary representation of a certificate with + a serial number of 2468 issued by o=truetrust ltd,c=gb} + userCertificate;binary: {binary representation of certificate with a + serial number of 1357 issued by o=truetrust ltd,c=gb} + userCertificate;binary: {binary representation of certificate with a + serial number of 1234 issued by dc=certsRus,dc=com} + + + + +Chadwick & Mullan Standards Track [Page 7] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + An LDAP search operation is specified with a baseObject set to + o=University of Salford,c=gb, a subtree scope, a filter set to + (sn=chadwick), and the list of attributes to be returned set to + "userCertificate;binary". In addition, a ValuesReturnFilter control + is set to ((userCertificate=1357$o=truetrust ltd,c=gb)). + + The search result returned by the server would consist of the + following entry: + + dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb + userCertificate;binary: {binary representation of certificate with a + serial number of 1357 issued by o=truetrust ltd,c=gb} + +6. Security Considerations + + This document does not primarily discuss security issues. + + Note however that attribute values MUST only be returned if the + access controls applied by the LDAP server allow them to be returned, + and in this respect the effect of the ValuesReturnFilter control is + of no consequence. + + Note that the ValuesReturnFilter control may have a positive effect + on the deployment of public key infrastructures. Certain PKI + operations, like searching for specific certificates, become more + scalable, and more practical when combined with X.509 certificate + matching rules at the server, since the control avoids the + downloading of potentially large numbers of irrelevant certificates + which would have to be processed and filtered locally (which in some + cases is very difficult to perform). + +7. IANA Considerations + + The Matched Values control as an LDAP Protocol Mechanism [7] has been + registered as follows: + + Subject: Request for LDAP Protocol Mechanism Registration + + Object Identifier: 1.2.826.0.1.3344810.2.3 + Description: Matched Values Control + Person & email address to contact for further information: + David Chadwick + Usage: Control + Specification: RFC3876 + Author/Change Controller: IESG + Comments: none + + + + + +Chadwick & Mullan Standards Track [Page 8] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + + This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the + matchedValues control described here. This OID was assigned by + TrueTrust Ltd, under its BSI assigned English/Welsh Registered + Company number [16]. + +8. Acknowledgements + + The authors would like to thank members of the LDAPExt list for their + constructive comments on earlier versions of this document, and in + particular to Harald Alvestrand who first suggested having an + attribute return filter and Bruce Greenblatt who first proposed a + syntax for this control. + +9. References + +9.1. Normative References + + [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP + 9, RFC 2026, October 1996. + + [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access + Protocol (w3)", RFC 2251, December 1997. + + [3] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [5] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998, + Information Technology - Abstract Syntax Notation One (ASN.1): + Specification of Basic Notation + + [6] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998 + Information technology - ASN.1 encoding rules: Specification of + Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and + Distinguished Encoding Rules (DER) + + [7] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) + Considerations for the Lightweight Directory Access Protocol + (LDAP)", BCP 64, RFC 3383, September 2002. + + + + + + + + + +Chadwick & Mullan Standards Track [Page 9] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + +9.2. Informative References + + [8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", + 1993. + + [9] ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract + Service Definition. + + [10] Sermersheim, J., "LDAP Control for a Duplicate Entry + Representation of Search Results", Work in Progress, October + 2000. + + [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical + Specification", RFC 2849, June 2000. + + [12] Chadwick, D. and S.Legg, "Internet X.509 Public Key + Infrastructure - Additional LDAP Schema for PKIs", Work in + Progress, June 2002 + + [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for + Server Side Sorting of Search Results", RFC 2891, August 2000. + + [14] Howes, T., "The String Representation of LDAP Search Filters", + RFC 2254, December 1997. + + [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [16] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration + for Open System Standards Part 1: Procedures for the UK Name + Registration Authority. + + + + + + + + + + + + + + + + + + + + +Chadwick & Mullan Standards Track [Page 10] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + +10. Authors' Addresses + + David Chadwick + IS Institute + University of Salford + Salford M5 4WT + England + + Phone: +44 161 295 5351 + EMail: d.w.chadwick@salford.ac.uk + + + Sean Mullan + Sun Microsystems + One Network Drive + Burlington, MA 01803 + USA + + EMail: sean.mullan@sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Chadwick & Mullan Standards Track [Page 11] + +RFC 3876 Returning Matched Values with LDAPv3 September 2004 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (2004). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE + INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the IETF's procedures with respect to rights in IETF Documents can + be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Chadwick & Mullan Standards Track [Page 12] + -- 2.39.5