[Date Prev][Date Next] [Chronological] [Thread] [Top]
Re: Revised Matched Values Draft

To: "Kurt D. Zeilenga" <Kurt@OpenLDAP.org>
Subject: Re: Revised Matched Values Draft
From: "David Chadwick" <d.w.chadwick@salford.ac.uk>
Date: Tue, 11 Jul 2000 23:35:59 +0100
Cc: ietf-ldapext@netscape.com
In-reply-to: <4.3.2.7.0.20000701213030.00afe420@infidel.boolean.net>
Organization: University of Salford
References: <395E667D.20321.CB299BF@localhost>
Kurt

I have produced a version 03 including your comments as described 
below, but I wont release it until after Pittsburgh and any other 
comments that I get

> >1. Introduction
> >
> >When reading an attribute from an entry using LDAP v2 [1] or LDAPv3
> >[2],
> 
> I suggest not mentioning LDAP v2...

done

> 
> >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 [ID/standard] a client must 
> 
> s/[ID/standard]/document/

done

> 
> >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 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 Internet Draft specifies an LDAPv3 control to enable a user to
> 
> s/Internet Draft/document/

done

> 
> > 
> >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 RFC 2119 [5].
> >
> >
> >2. The valuesReturnFilter Control
> >
> >The valuesReturnFilter control MAY be critical or non-critical as
> >determined by the user. It is only applicable to the Search
> >operation, and SHALL be ignored by the server if it is present on any
> > other LDAP operation (even if marked critical on such operations).
> 
> I suggest that if this control is provided to non-search operations
> and marked critical that an unavailableCriticalExtension
> (unsupportedCriticalExtension) error should be returned.  This is
> consistent with RFC 2251, 4.1.12.

done

>    If the control is not appropriate for the operation and criticality
>    field is TRUE, the server MUST NOT perform the operation, and MUST
>    instead return the resultCode unsupportedCriticalExtension.
> 
> 
> >The object identifier for this control is 1.2.826.0.1.3344810.2.3
> >
> >
> >The controlValue is 
> >
> >        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 }
> >
> >         SimpleMatchingAssertion ::= SEQUENCE {
> >                matchingRule    [1] MatchingRuleId OPTIONAL,
> >                type            [2] AttributeDescription OPTIONAL,
> >                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. 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 SHOULD be 
> >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 SHOULD be 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:
> >
> >i) Every attribute value that evaluates TRUE against one or 
> >more elements of the ValuesReturnFilter is placed in the 
> >SearchResultEntry.
> >ii) Every attribute value that evaluates FALSE or undefined 
> >against all elements of the ValuesReturnFilter is not 
> >placed in the SearchResultEntry. An attribute that has no 
> >values selected is returned with an empty set of vals.
> >
> >Editor's Note. There is possibly a more efficient but slightly more
> >complex way of achieving the value filtering. An alternative is to
> >remove the 'present' SimpleFilterItem (which obviously evaluates true
> > for every attribute value of the 'present' attribute description),
> >and to say that any attribute whose type is not mentioned in the
> >ValuesReturnFilter is not filtered and has all its attribute values
> >returned. Comments please.
> 
> I prefer the specified approach as it appears easier to implement
> especially for servers which separate filter evaluation from attribute
> list processing. That is, in U-Mich derived servers, filter evaluation
> is done by database backends and attribute list processing is done by
> the frontend.  Implementing this control with the above design might
> prove to be more than slightly complex and the efficient gain may
> actually be quite slight.

Editors note removed

> 
> >3. Relationship to X.500
> >
> >The control is a superset of the matchedValuesOnly boolean of the
> >X.500 DAP [4] Search argument, as amended in the latest version [6].
> >Close examination of the matchedValuesOnly boolean by the LDAPExt
> >group revealed ambiguities and complexities in the MVO boolean that
> >could not easily be resolved. For example, are only those attribute
> >values that contributed to the overall truth of the filter governed
> >by the MVO boolean, or all values of attributes in the filter
> >governed by the MVO boolean, even if the filter item containing the
> >attribute evaluated to false. For this reason the LDAP 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. Examples
> >
> >(1) The first example simply shows how the control can be used to
> >selectively read a subset of attribute values. 
> >
> >The entry below represents a groupOfNames object class containing
> >several members from different organizations.
> 
> Please specify a DN, object classes, and ensure entry is valid per
> Standard Track schema in all examples. 

The examples are not that good and so I have redone them. 
Example one has been deleted completely. 
Please review in the revised ID when it is published

> You might specify that entries
> are provided in LDIF (RFC2849).

Done


> 
> >cn: Cross Organizational Standards Body
> >member: cn=joe,o=acme
> >member: cn=alice,o=acme
> >member: cn=bob,o=foo
> >member: cn=sue,o=bar
> >
> >An LDAP search operation is specified with a baseObject set to the DN
> >of the entry, a baseObject scope, a filter set to "member=*o=acme",
> >and the list of attributes to be returned set to "member". In
> >addition, a ValuesReturnFilter control is set to "member=*o=acme".
> 
> Note that filter (which is missing parentheses) is should evaluation
> to Undefined as member attribute type does specify a substrings
> matching rule.

Noted. This is why I have redone the examples!

> 
> >The search results returned by the server would consist of the 
> >following entry:
> >
> >cn: Cross Organizational Standards Body
> >member: cn=joe, o=acme
> >member: cn=alice, o=acme
> >
> >
> >(2) The second example shows how the control can be set to match on
> >attributes that are (mail) and are not (telephoneNumber) part of the
> >search filter. It also shows how a user can filter some attribute
> >values (mail) and not others (telephoneNumber).
> 
> Note sure why you have parentheses around these attribute types.

It was to show which ones were which in the example, that's all. But 
its gone now.


> 
> >The entries below represent inetOrgPerson [7] object classes located
> >below some distinguished name in the directory.
> 
> I would suggest using organizationalPerson (w/ appropriate attributes)
> instead of inetOrgPerson as inetOrgPerson is Informational (though I
> don't be this use would cause a standard track maturity issue).

I would rather keep it as well as adding orgPerson, as I need the 
mail attribute.

> 
> >cn: Sean Mullan
> >mail: sean.mullan@sun.com
> >mail: mullan@east.sun.com
> >telephoneNumber: +1 781 442 0926
> >telephoneNumber: 555-9999
> >
> >cn: David Chadwick
> >mail: d.w.chadwick@salford.ac.uk
> >
> >An LDAP search operation is specified with a baseObject set to the DN
> >of the entry, a subtree scope, a filter set to
> >"(|(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk))", and
> > the list of attributes to be returned set to "mail telephoneNumber".
> > In addition, a ValuesReturnFilter control is set to
> >"mail=sean.mullan@sun.com, mail=d.w.chadwick@salford.ac.uk,
> >telephoneNumber=*"
> 
> Please use parentheses.  In fact, you may want to define a string
> format for ValuesReturnFilter.  I suggest something like:
> 
>   (:(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk)(teleph
>   oneNumber=*))
> 
> or if that looks too much like a search filter:
> 
>   {(mail=sean.mullan@sun.com)(mail=d.w.chadwick@salford.ac.uk)(telepho
>   neNumber=*)}

I think it would be a good idea for the LDAP group to settle on a 
character that can represent the ASN.1 type SEQUENCE, and 
another that can represent a SET. I need this also for my PKI and 
PMI schema document. Steven Legg is working on this at the 
moment, but lets assume for now that comma , represents 
SEQUENCE and + represents SET. Unfortunately we have not 
been too consistent in this in the past, as comma has represented 
both, and + has also represented SET (e.g. as in DNs)

> 
> >The search results returned by the server would consist of the 
> >following entries:
> >
> >cn: Sean Mullan
> >mail: sean.mullan@sun.com
> >telephoneNumber: +1 781 442 0926
> >telephoneNumber: 555-9999
> >
> >cn: David Chadwick
> >mail: d.w.chadwick@salford.ac.uk
> >
> >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.
> >
> >(3) The third example shows how one might retrieve a single attribute
> > type schema definition for the "gunk" attribute with OID 1.2.3.4.5
> >
> >Assume the subschema subentry is held somewhere below the root entry
> >with RDN "subschema subentry", 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). 
> >
> >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 
> >objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
> >attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY 
> >generalizedTimeMatch ORDERING generalizedTimeOrderingMatch
> >SYNTAX 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 
> >objectIdentifierFirstComponentMatch SYNTAX 
> >1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
> >attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 
> >SUBSTR caseIgnoreSubstringsMatch SYNTAX
> >1.3.6.1.4.1.1466.115.121.1.44{64} ) attributeTypes: ( 2.5.21.5 NAME
> >'attributeTypes' EQUALITY objectIdentifierFirstComponentMatch 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
> >root, a subtree scope, 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"
> 
> Per RFC 2251, subschema subentries should be retrieved using a search
> with a base of the subschema subentry's DN, scope base, and filter
> (objectclass=subschema).  Please use this procedure in your example.
> 

Done

> >The search result returned by the server would consist of the 
> >following entry:
> >
> >cn: subschema subentry
> >attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMatch 
> >SUBSTR caseIgnoreSubstringsMatch SYNTAX
> >1.3.6.1.4.1.1466.115.121.1.44{64} )
> >
> >(4) The final example shows how the control can be set to match on
> >attributes that are not part of the search filter. For example,
> >searching for all entries that have an email address in the sun.com
> >domain, and returning the telephone number for any attribute values
> >that start with "555". 
> >
> >The entries below represent inetOrgPerson [7] object classes located
> >below some distinguished name in the directory.
> >
> >cn: Sean Mullan
> >mail: sean.mullan@sun.com
> >mail: mullan@east.sun.com
> >telephoneNumber: +1 781 442 0926
> >telephoneNumber: 555-9999
> >
> >cn: David Chadwick
> >mail: d.w.chadwick@salford.ac.uk
> >
> >An LDAP search operation is specified with a baseObject set to the DN
> >of the entry, a subtree scope, a filter set to "mail=*sun.com", and
> >the list of attributes to be returned set to "telephoneNumber". In
> >addition, a ValuesReturnFilter control is set to
> >"telephoneNumber=555*"
> >
> >The search results returned by the server would consist of the 
> >following entry:
> >
> >cn: Sean Mullan
> >telephoneNumber: 555-9999
> >
> >
> >5. Security Considerations
> >
> >This Internet Draft does not discuss security issues at all. 
> 
> s/Internet Draft/document/

Done

> 
> I suggest you strike this statement as this section discussion
> security issues (though mute).  I suggest you revise the comments
> below into primary considerations.
> 
> >Note 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.
> 
> How do "search" versus "read" access to be applied.  That is, where
> "search" access is required to evaluation search filters and "read"
> access is required to return return attributes, is this mechanism
> considered part of "searching" or part of "reading"?  Though the
> mechanism uses filters, I'm thinking it's part of "reading" as the
> mechanism is only applied entries which match the search filter and
> scope.  Would treating the mechanism as part of "reading" be
> consistent with X.500/LDAP/vendor access controls?
> 

Actually I think that ValuesReturnFilter should be independent of the 
access control mechanism. In other words, search access is used 
as now to find the entries, then valuesReturnFilter filters the 
attributes free of any access contol provisions, then read access is 
applied as now to the filtered attributes to see if they can be 
returned or not. (You could in fact consider the ValuesReturnFilter 
as an access control applied by the user!! or maybe not)

> >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
> >practical (when combined with X.509 certificate matching rules at the
> > server) and more scalable, 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).
> >
> >
> >6. Acknowledgements
> >
> >The authors would like to thank members of the LDAPExt list for their
> > constructive comments on earlier versions of this draft, and in
> 
> s/draft/document/

Done

> 
> >particular to Harald Alvestrand who first suggested having an 
> >attribute return filter and Bruce Greenblatt who first proposed a
> >syntax for this control.
> >
> >7. Copyright
> >
> >Copyright (C) The Internet Society (date). All Rights Reserved.
> 
> Date should be specified.

I think that is left until the RFC is published is it not?

> 
> >8. References
> >
> >[7] M. Smith. "Definition of the inetOrgPerson LDAP Object Class",
> >Internet Draft <draft-smith-ldap-inetorgperson-03.txt>, April 1999.
> 
> Published as RFC 2798.

Done


Many thanks
David

> 
> 


***************************************************

David Chadwick
IS Institute, University of Salford, Salford M5 4WT
Tel +44 161 295 5351  Fax +44 161 745 8169
Mobile +44 790 167 0359
Email D.W.Chadwick@salford.ac.uk
Home Page  http://www.salford.ac.uk/its024/chadwick.htm
Understanding X.500  http://www.salford.ac.uk/its024/X500.htm
X.500/LDAP Seminars http://www.salford.ac.uk/its024/seminars.htm
Entrust key validation string MLJ9-DU5T-HV8J

***************************************************
Follow-Ups:
- RE: Revised Matched Values Draft
  - From: "Steven Legg" <steven.legg@adacel.com.au>
References:
- Revised Matched Values Draft
  - From: "David Chadwick" <d.w.chadwick@salford.ac.uk>
- Re: Revised Matched Values Draft
  - From: "Kurt D. Zeilenga" <Kurt@OpenLDAP.org>
Prev by Date: Re: Revised Matched Values Draft
Next by Date: Re: Revised Matched Values Draft
Index(es):
- Chronological
- Thread