[sipcore] 4244bis-05: Semantics of History-Info

["Worley, Dale R (Dale)" <[e-mail]>]

Here is a start for how I'd like to see section 5 organized.  The idea is to describe clearly what a particular History-Info header means when you look at it.  It correlates with the procedures described in the draft in the same way that the input/output specification of a module corresponds to the code of the module -- it allows you to verify that the code does what it is intended to do (and that the specification is correct).

---------------------------

   5.1 Syntax of History-Info

   The ABNF syntax for the History-info header field and header field
   parameters is as follows:

   History-Info = "History-Info" HCOLON hi-entry *(COMMA hi-entry)

   hi-entry = hi-targeted-to-uri *(SEMI hi-param)

   hi-targeted-to-uri = name-addr

   hi-param = hi-index / hi-target-param / hi-extension

   index-val =  1*DIGIT *("." 1*DIGIT)

   hi-index = "index" EQUAL index-val

   hi-target-param = rc-param / mp-param

   rc-param = "rc" EQUAL index-val

   mp-param = "mp" EQUAL index-val

   hi-extension = generic-param

   The ABNF definitions for "generic-param" and "name-addr" are from
   [RFC3261].

   This document also extends the "contact-params" for the Contact
   header field as defined in [RFC3261] with the "rc" and "mp" header
   field parameters defined above:

   contact-params =/ hi-target-param

   5.2 Semantics of History-Info

   The History-Info header fields of a request or response together
   form an ordered sequence of hi-entries.  The division of the
   hi-entries among one or more History-Info header fields is not
   significant.

   The hi-entries are a pre-order walk of a tree, the nodes of which
   represent requests derived from the same original request sent by
   the UAC.  The tree is organized by the derivation of requests by
   forwarding and forking, with each node's request being derived (by
   one or more steps) from its parent node's request.

[There are complexities if the UAC does not support History-Info, but
downstream entities do, particularly if a first History-Info is added
on two different forks -- both forks have hi-entries with index "1".]

   Because not all SIP entities support History-Info, the tree
   may not separately represent every forwarding and forking
   operation.  (Abstractly, the tree can be derived from the tree that
   would be recorded if all entities supported History-Info by
   collapsing certain contiguous sets of nodes.)

   In addition, if an entity that supports History-Info receives a
   request whose Request-URI is different from the URI recorded in the
   History-Info that should correspond to the request, then the entity
   knows that the Request-URI has been changed by an entity that does
   not support History-Info, and the entity will perform a preparatory
   normalization by adding an additional leaf to the tree showing the
   new Request-URI.  This operation is specified in section 9.

[Note that this introduces a problem:  Suppose the UAS sends
"History-Info: AOR;index=1", and a non-History-Info-supporting entity forks it
to two destinations, UAS A and UAS B, both of which support
History-Info.  UAS A normalizes the request to "History-Info:
AOR;index=1, UAS-A;index=1.1" while UAS B normalizes the request to
"History-Info: AOR;index=1, UAS-B;index=1.1".

These two normalized requests violate the rule that everybody expects
to be satisfied, viz., that all hi-entries in the entire forking
structure with the same index represent the same request.  As a
result, the responses from the two UASs cannot be merged in any useful
way.  In this particular case, we are saved from a mess by the fact
that the proxy will forward only one of the History-Info headers back,
but we have to check whether this good fortune holds in all
situations.]

   A SIP entity my perform "internal retargeting", multiple stages of
   retargeting that it models as more than one stage of forking, but
   without actually generating and sending a SIP request.  Internal
   retargeting may be described in the History-Info tree as one or
   more nodes, as long as the semantics of the History-Info values
   correctly describes the derivation of the various Request-URI
   values.

   Because of the above complications, the depth of a node within the
   tree does not equal the number of Via headers in the corresponding
   request, although the number of Via headers increases as one moves
   downward in the tree.

   As forwardings or forkings of a request are generated at a SIP
   entity, they are numbered in time order as 1, 2, 3, etc.  These
   numbers are the labels of the nodes of the tree, giving each node
   its index-val and determining the sequential ordering of the
   hi-entries.  The trees recorded in various requests of the
   forwarding/forking structure are different, but all hi-entries in
   the trees that share the same index-val represent the same request,
   and will have the same hi-targeted-to-uri (excepting for changes
   dictated by privacy processing and changing tel: URIs to sip:
   URIs).

[Also need to take care of the case where the UAC generates several
requests as forks of a theoretical ancestral request, as is used in
draft-ietf-bliss-call-completion.  It seems like they should have
index=1, index=2, index=3, etc.]

   In a request's History-Info, the only requests of the forking
   structure that are represented are the ones that are ancestral to
   the request, and subtrees that are siblings of ancestral nodes and
   have received non-100 responses (which may be recorded in Reason
   header fields in the hi-targeted-to-uri) (which must necessarily be
   earlier siblings) .

   Thus, the rightmost leaf (sequentially last) hi-entry in a request
   represents the request (and contains the Request-URI of the
   request) or it represents the latest ancestral request of this
   request that was constructed by a SIP entity that supports
   History-Info.

   A response contains a History-Info header only if the corresponding
   request contained "Supported: histinfo".  As non-100 responses
   propagate in the reverse direction in the forwarding/forking
   structure, the hi-entries that they carry are recorded at each SIP
   entity as part of the state of SIP transactions.  These hi-entries
   will be included in the History-Info of any responses and any
   additional requests that are generated.

   When a request or response is forwarded to a "different" domain,
   some or all of the hi-entries may be anonymized.  If a "Privacy:
   history" header field is present, all hi-entries are anonymized.
   Any hi-targeted-to-uri that contains a Privacy header with value
   "history" is anonymized.  An hi-entry is anonymized by replacing
   the URI part of the hi-targeted-to-uri with a URI with domain
   "anonymous.invalid".

   5.3 Semantics of an hi-entry value

   The following provides details for the information that is captured
   in the History-Info header field entry (hi-entry) for each target
   used for forwarding a request:

   o  hi-targeted-to-uri: A mandatory parameter for capturing the
      Request-URI for the specific request as it is forwarded.

   o  hi-index: A mandatory parameter for History-Info reflecting the
      chronological order of the information, indexed to also reflect
      the forking and nesting of requests.  The format for this
      parameter is a string of integers, separated by dots, to indicate the
      relationships between the requests that carried the Request-URIs
      captured in the hi-entries.

   o  hi-target-param: An optional parameter reflecting the mechanism by
      which the Request-URI captured in the hi-targeted-to-uri in the
      hi-entry was determined, and the captures Request-URI from which
      it was derived.  This parameter contains either an "rc"
      or "mp" header field parameter, which is interpreted as follows:

         "rc": The hi-targeted-to-URI is a contact bound to an AOR in an
         abstract location service, that AOR being the Request-URI that
         was retargeted.  The AOR-to-contact binding has been placed
         into the location service by a SIP Registrar that received a
         SIP REGISTER request.  The "rc" header field parameter contains
         the value of the hi-index in the hi-entry with an
         hi-targeted-to-uri that is the Request-URI that was
         retargeted

         "mp": The hi-targeted-to-URI represents a user other than the
         user associated with the Request-URI in the incoming request
         that was retargeted.  This occurs when a request is statically
         or dynamically retargeted to another user.  The "mp" header
         field parameter contains the value of the hi-index in the hi-
         entry with an hi-targeted-to-uri that is the Request-URI
         that was retargeted, thus identifying the "mapped from" target.

[What if a mapping is done in some other manner?  How do we record the
index-val of the value from which the new Request-URI was derived?]

   o  Extension (hi-extension): A parameter to allow for future optional
      extensions.  As per [RFC3261], any implementation not
      understanding an extension MUST ignore it.

   In addition to the parameters defined by the ABNF, an hi-entry may
   also include a Reason header field and/or a Privacy header field,
   which are both included in the "headers" component of the hi-
   targeted-to-uri as described below:

   o  Reason: An optional parameter for History-Info, reflected in the
      History-Info header field by including the Reason header field
      [RFC3326] included in the hi-targeted-to-uri.  A reason is
      included in the hi-targeted-to-uri of an hi-entry to reflect
      information received in the response to the request represented
      by the hi-entry.

[Need to detail exactly what can be included here.  It seems that
Reason may contain any non-2xx final SIP response code, as well as any
non-SIP response codes -- see
draft-jesske-dispatch-update3326-reason-responses.  2xx response codes
seem to be implicit in that the hi-entry is seen in a non-descendant
request or a response, but no SIP Response value is present.  Do we
want this irregularity for 2xx?]

   o  Privacy: An optional parameter for History-Info, reflected in the
      History-Info header field values by including the Privacy Header
      [RFC3323] included in the hi- targeted-to-uri or by adding the
      Privacy header field to the request.  The latter case indicates
      that the History-Info entries for the domain MUST be anonymized
      prior to forwarding, whereas the use of the Privacy header field
      included in the hi-targeted-to-uri means that a specific hi-entry
      MUST be anonymized.

[This specification is vague, as it should give some indication of when
anonymization is required.  The discussion of "Privacy: history" should
not be done here, as it is not part of the hi-entry.  It looks like section
10.1.1 is OK for this.  So I would revise the above paragraph to:

   o  Privacy: An optional parameter for History-Info, reflected in the
      History-Info header field values by including in the
      hi-targeted-to-uri a Privacy Header [RFC3323] with value "history".
      The Privacy header field
      included in an hi-targeted-to-uri means that a specific hi-entry
      MUST be anonymized under the conditions specified in section 10.1.2.

   Note that since both the Reason and Privacy parameters are included
   in the hi-targeted-to-uri, these fields will not be available in the
   case that the hi-targeted-to-uri is a Tel-URI [RFC3966].  In such
   cases, the Tel-URI SHOULD be transformed into a SIP URI per section
   19.1.6 of [RFC3261].

[Does this mean that if an entity desires or is required to apply Reason
or Privacy to an hi-entry containing a tel: URI, that it MUST convert it
to a sip: URI, and then proceed?  If so, it would be better stated:]

   Note that since both the Reason and Privacy parameters are included
   in the hi-targeted-to-uri, these fields cannot be applied if 
   the hi-targeted-to-uri is a Tel-URI [RFC3966].  If an entity desires
   or is required to apply such a parameter, the Tel-URI SHOULD be
   transformed into a SIP URI per section 19.1.6 of [RFC3261] and then
   the parameter is applied.

   5.4  History-Info Header Field Examples

   The following provides examples of the format for the History-info
   header field.  Note that the backslash and CRLF between the fields in
   the examples below are for readability purposes only.

   History-Info: <sip:[e-mail]>;index=1;foo=bar

   History-Info: <sip:[e-mail]?Reason=SIP%3B\
                 cause%3D302>;index=1.1,\
                 <sip:[e-mail]?Privacy=history&Reason=SIP%3B\
                 cause%3D486>;index=1.2;mp=1.1,\
                 <sip:45432@192.168.0.3>;index=1.3;rc=1.2

---------------------------------------

Dale