Section 4.1.11 "Controls" replacement text

["Kurt D. Zeilenga" <Kurt@OpenLDAP.org>]

The text in RFC 2251 relies, I believe, on the reader understanding
the X.511 service model, especially in regards to the meaning of
a control's criticality.

Comments?

Kurt

(Note: I defer chair action in regards to this replacement text to Bob.)


4.1.11. Controls 

LDAP provides, in Controls, a mechanism for extending existing
operations.

Each control contains extension information including a control
type (controlType) and, optionally, a value (controlValue) which
type-specific information.  The semantics of the extension information
contained in a control instance apply only to the message instance
the control was attached to.

Additionally, each control includes a field (criticality) which
allows the originator of the operation to indicate that the operation
must be performed as extended by the control (i.e., that performing
the operation without these extensions is unacceptable.)

Controls which are attached sent by clients are termed "request
controls" and those sent by servers are termed "request controls".
Where an extension calls for a particular response control to be
returned in response to a request control, the response and request
are termed to be "paired".

	Controls ::= SEQUENCE OF control Control 
    
	Control ::= SEQUENCE { 
		controlType             LDAPOID, 
		criticality             BOOLEAN DEFAULT FALSE, 
		controlValue            OCTET STRING OPTIONAL } 

The controlType field is the dotted-decimal representation of an
OBJECT IDENTIFIER which identifies the control, or the request
control and its paired response control.  This provides unambigous
naming of controls.

The criticality field applies only to request controls excepting
those attached to unbindRequest.  For these controls, the value
TRUE indicates that it is unacceptable to perform the operation
without making use of the extension information provided by the
control and FALSE otherwise.  Specifically,

  If the server recognizes the control type and it is appropriate
  for the operation, the server is to make use of the control when
  performing the operation.

  If the server does not recognize the control type or it is not
  appropriate for the operation, and the criticality field is TRUE,
  the server MUST NOT perform the operation, and for operations
  that have a response, MUST return unavailableCriticalExtension
  in the resultCode.

  If the control is unrecognized or inappropriate but the criticality
  field is FALSE, the server MUST ignore the control.

For all other controls (all response controls and controls attached
to the unbindRequest), the sender SHOULD provide a criticality value
of FALSE and, regardless of the value provided, receiver MUST ignore
the criticality value.

The controlValue contains information associated with the control
type.  Its format is defined in the specification of the control.
Implementations MUST be prepared to handle arbitrary contents of
the controlValue octet string, including zero bytes.  It is absent
only if there is no value information which is associated with a
control of its type. 

Servers list the controlType of all request controls they recognize
in the supportedControl attribute in the root DSE (Section 5.1 of
[Models]).

Controls SHOULD NOT be combined unless the semantics of the combination
has been specified. The semantics of control combinations, if
specified, are generally found in the control specification most
recently published. In the absence of combination semantics, the
behavior of the operation is undefined.  Additionally, unless
order-dependent semantics are given in a specification, the order
of a combination of controls in the SEQUENCE is ignored.

This document does not specify any controls. Controls may be specified
in other documents.  Documents detailing control extensions are to
provide for each control:

- the OBJECT IDENTIFIER assigned to the control,

- direction as to what value the sender should provide for the
  criticality field (note: the semantics of the criticality field
  are defined above should not be altered by the control's
  specification),

- and indication as to whether the controlValue field is to be
  provided and, if so, the format of the controlValue field
  (note: where the format of controlValue is defined in terms
  of ASN.1 and BER encoded according to Section 5.1, the ASN.1
  is assumed to follow the extensibility rules provided in
  Section 4),

- the semantics of the control, and

- optionally, semantics regarding the combination of the control
  with other controls.

Note: where the format of controlValue that are defined in terms of
ASN.1 and BER encoded according to Section 5.1, also follow the
extensibility rules in Section 4.