[Ietf-not43] inetResourcesControl text

[Eric A. Hall]

This is the new text on the control (renamed to reflect broader use). If
anybody sees any problems with this let me know.


5.3.1.	The inetResourcesControl server control

The inetResourcesControl server control is the master control object for
the FIRS service, and provides the version of each object class that is
available for use on the current server, and also lists the matching
filters that the server is willing to use for each of the listed object
classes.

The OID for inetResourcesControl is 1.3.6.1.4.1.7161.1.0.0. This value
MUST be provided in the OID field of the control.

The value section of the inetResourcesControl contains nested sequences of
data. The first element in each sequence identifies an class, while the
remainder of each sequence identifies the matching filters.

The structure of the value section of inetResourcesControl is illustrated
by the following ASN.1 definition:

  inetResourcesControlValue ::= SEQUENCE {
    objectClass		LDAPOID,
    matchingFilters	SEQUENCE OF matchingFilter }

  matchingFilter ::= LDAPSTRING

Each object class and matching filter MUST be presented as a string.
Object classes MUST be listed as OIDs so that clients can determine the
supported object classes according to their version. Matching filters MUST
also be provided as OIDs, except for the "stock" matching filter operators
defined in [RFC2251], which MUST be presented with the textual identifiers
shown therein.

At a minimum, servers MUST support the equalityMatch and extensibleMatch
filters from [RFC2251] for every object class listed, and SHOULD always
declare these filters. The Asterisk character ("*") MAY be provided as a
wildcard in the list of matching filters to indicate that the server will
accept any matching filter for the associated object class. Servers MUST
allow any supported matching filter to be used as part of an
extensibleMatch operation, and clients MAY assume that any allowed
operation will be acceptable as part of an extensibleMatch.

An example of an inetResourcesControl server control is shown below for
illustration purposes:

{ 1.3.6.1.4.1.7161.1.0.0, FALSE, {
	1.3.6.1.4.1.7161.1.3.1 {
		1.3.6.1.4.1.7161.1.0.3,
		equalityMatch,
		substringMatch,
		extensibleMatch } }, {
	2.16.840.1.113730.3.2.2 {
		equalityMatch,
		extensibleMatch } } }

Figure 4: An example inetResourcesControl server control.

In the example shown in Figure 4, the inetResourcesControl type is
identified by the OID of 1.3.6.1.4.1.7161.1.0.0, while the criticality
field is set to FALSE, as per the requirements in [RFC2251]. The contents
of the control value identify the current OID for the inetDnsDomain object
class, along with the OID for the inetDnsDomainMatch and the [RFC2251]
textual identifiers for the equalityMatch, substringMatch and
extensibleMatch operators, and also identifies the OID for the
inetOrgPerson object class along with the [RFC2251] textual identifiers of
the equalityMatch and extensibleMatch operators.

FIRS-compliant servers SHOULD return the inetResourcesControl server
control as an unsolicited response to a successful bind request. Clients
MUST use the OID of the inetResourcesControl for the purpose of validating
the contents of the control, and MUST use the OIDs of the listed object
classes to discover schema versioning information.

Servers MAY restrict the contents of the inetResourcesControl value
according to the authenticated identity of the client. For example,
servers can choose to enable computationally-intense searches for
authorized users while refusing to provide the same searches for anonymous
users.

If a client does not receive a usable inetResourcesControl control as part
of the bind response, the client SHOULD issue a request for the control
before proceeding. If a client is still unable to obtain a usable
inetResourcesControl server control, the client MAY choose a different
server for the partition, or MAY choose to assume that the equalityMatch
matching filter will be supported for any of the known types, or MAY
choose to undergo any other recovery efforts. In any event, clients SHOULD
NOT use the absence or contents of the control to completely abort query
processing unless all of the servers for a partition have refused to
provide service to the client.

For example, if the server advertises support for the inetDnsDomain object
class but does not advertise support for the inetDnsDomainMatch matching
filter, the client MAY issue discrete equality searches for each of the
specific domain name resources (note that this kind of query can fail to
produce referrals in some cases, but will usually produce at least some
answers).

In all cases, if any given server advertises support for a particular
object class or matching filter, the client MUST make use of the
server-provided service.

-- 
Eric A. Hall                                        http://www.ehsco.com/
Internet Core Protocols          http://www.oreilly.com/catalog/coreprot/