[sipcore] 4244bis: Syntax and semantics of History-Info

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

Here is a revision of the syntax and semantics of History-Info.  All of the open issues are listed at the left margin; the rest is formatted as if it is part of the draft.  I've updated it based on the discussions, but some of the issues may not reflect changes recently decided by the authors.

I hoped to add implementations of the "application" processing of chapter 11, but that will have to wait.

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

   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

For consistency's sake, I think this should be:
hi-targeted-to-uri = addr-spec / 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 field values 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 sequence of hi-entries form 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.  This organization is indicated by the "index"
   parameters of the hi-entries.

This deviates from the draft by assuming that entries added on behalf
of legacy entites are numbered within the tree structure rather than
being indexed just "1".

   However, the UAC may have originally sent several forks of the
   request (particularly if it received a 3xx response to the first
   request it sent).  Thus, the request forks sent by the UAC are
   considered children of an unrealized ancestral root request.  This
   ancestral request would be represented by an hi-entry at the
   beginning of the sequence, with an index consisting of zero
   integers, but this hi-entry is not included in History-Info.

Here we deal with the fact that the UAC can send several sibling
requests.

   Because not all SIP entities support History-Info, the tree may not
   separately represent every forwarding and forking operation.
   (Abstractly, the hi-entry 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 that does not contain History-Info or 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 upstream 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.

I have added that History-Info can be added de novo by an intermediate
entity even if "Supported: histinfo" is not present.  This behavior
may or may not be intended by section 9.1.  But if neither
History-Info nor Supported: histinfo is present in the incoming
request, the entity will not return History-Info upstream -- this rule
avoids the know problem cases.

What index is to be used for this new hi-entry?  I have been assuming
that it was constructed by adding .1 to the preceeding hi-entry index.
But I read the draft more carefully, and it says (top of 10.3) to use
just "1".

Note that even the rule I describe 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.  Unfortunately, both index 1.1 hi-entries can be sent upstream
(possibly to the UAC) in 1xx resonses forwarded from the two UASs.
This gets really ugly, because each intermediate SIP entity is
*required* to add the hi-entries that it learns from a 1xx to the
cache for the transaction, and it is *required* to send those cached
hi-entries upstream.  With carefully selected network delays, the two
1xx responses could race each other upstream, each alternately being
in the lead, causing some of the upstream caches to contain one 1.1
hi-entry and others to contain the other.

   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 necessarily 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; each node's
   index-val is assembled from the labels of the nodes from the root
   to itself, and it determines the sequential ordering of the
   hi-entries.  The trees recorded in the various requests and
   responses of the forwarding/forking structure differ, 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).

   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 itself (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" or a History-Info header.
   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 the 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 domain not associated
   with the forwarding SIP entity, some or all of the hi-entries may
   be anonymized as specified in section 10.1.  If a "Privacy:
   history" or "Privacy: header" header field is present, all
   hi-entries whose domain is associated with the forwarding SIP
   entity are anonymized.  Also, any hi-targeted-to-uri with such a
   domain 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 value 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, that
      indicate the relationships between the requests that carried the
      Request-URIs captured in the hi-entries.

   o  hi-target-param: An optional parameter indicating the mechanism
      by which the Request-URI captured in the hi-targeted-to-uri in
      the hi-entry was determined, and indicating the hi-entry that
      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?]

      If the Request-URI was generated by the SIP entity that sends
      the request based directly on the Request-URI of the incoming
      request, the value of the parameter is the index of the hi-entry
      for the incoming request, and the parameter name indicates the
      way in which the new Request-URI was derived.

      If the Request-URI was copied by the SIP entity that sends the
      request from a Contact header of a 3xx response to a sibling
      fork of this request, then the "rc" or "mp" header parameter (if
      any) of that Contact header is copied as the hi-target-param.

      (Any UAS that generates (rather than forwards upstream) a 3xx
      response must include in each Contact header an hi-target-param
      header parameter indicating the method by which the Contact URI
      was derived from the Request-URI it received.  The value of the
      parameter is the index of the hi-entry containing the received
      Request-URI.)

   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: gives the SIP status and possibly other protocol statuses
      received in the response to the request represented by the
      hi-entry.

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?  Also, if the 2xx
response has a Reason header containing a non-SIP code (e.g., what a
downstream gateway received from the far-side network), should it be
included?

   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 as specified in section 10.1.

   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