tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 5971

 
 
 

GIST: General Internet Signalling Transport

Part 6 of 6, p. 122 to 154
Prev RFC Part

 


prevText      Top      Up      ToC       Page 122 
Appendix A.  Bit-Level Formats and Error Messages

   This appendix provides formats for the various component parts of the
   GIST messages defined abstractly in Section 5.2.  The whole of this
   appendix is normative.

   Each GIST message consists of a header and a sequence of objects.
   The GIST header has a specific format, described in more detail in
   Appendix A.1 below.  An NSLP message is one object within a GIST
   message.  Note that GIST itself provides the NSLP message length
   information and signalling application identification.  General
   object formatting guidelines are provided in Appendix A.2 below,
   followed in Appendix A.3 by the format for each object.  Finally,
   Appendix A.4 provides the formats used for error reporting.

   In the following object diagrams, '//' is used to indicate a
   variable-sized field and ':' is used to indicate a field that is
   optionally present.  Any part of the object used for padding or
   defined as reserved (marked 'Reserved' or 'Rsv' or, in the case of
   individual bits, 'r' in the diagrams below) MUST be set to 0 on
   transmission and MUST be ignored on reception.

   The objects are encoded using big endian (network byte order).

A.1.  The GIST Common Header

   This header begins all GIST messages.  It has a fixed format, as
   shown below.

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Version    |   GIST hops   |        Message Length         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           NSLPID              |C|   Type      |S|R|E| Reserved|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Version (8 bits):  The GIST protocol version number.  This
      specification defines version number 1.

   GIST hops (8 bits):  A hop count for the number of GIST-aware nodes
      this message can still be processed by (including the
      destination).

   Message Length (16 bits):  The total number of 32-bit words in the
      message after the common header itself.

Top      Up      ToC       Page 123 
   NSLPID (16 bits):  IANA-assigned identifier of the signalling
      application to which the message refers.

   C-flag:  C=1 if the message has to be able to be interpreted in the
      absence of routing state (Section 5.2.1).

   Type (7 bits):  The GIST message type (Query, Response, etc.).

   S-flag:  S=1 if the IP source address is the same as the signalling
      source address, S=0 if it is different.

   R-flag:  R=1 if a reply to this message is explicitly requested.

   E-flag:  E=1 if the message was explicitly routed (Section 7.1.5).

   The rules governing the use of the R-flag depend on the GIST message
   type.  It MUST always be set (R=1) in Query messages, since these
   always elicit a Response, and never in Confirm, Data, or Error
   messages.  It MAY be set in an MA-Hello; if set, another MA-Hello
   MUST be sent in reply.  It MAY be set in a Response, but MUST be set
   if the Response contains a Responder-Cookie; if set, a Confirm MUST
   be sent in reply.  The E-flag MUST NOT be set unless the message type
   is a Data message.

   Parsing failures may be caused by unknown Version or Type values;
   inconsistent setting of the C-flag, R-flag, or E-flag; or a Message
   Length inconsistent with the set of objects carried.  In all cases,
   the receiver MUST if possible return a "Common Header Parse Error"
   message (Appendix A.4.4.1) with the appropriate subcode, and not
   process the message further.

A.2.  General Object Format

   Each object begins with a fixed header giving the object Type and
   object Length.  This is followed by the object Value, which is a
   whole number of 32-bit words long.

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |A|B|r|r|         Type          |r|r|r|r|        Length         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                             Value                           //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   A/B flags:  The bits marked 'A' and 'B' are extensibility flags,
      which are defined in Appendix A.2.1 below; the remaining bits
      marked 'r' are reserved.

Top      Up      ToC       Page 124 
   Type (12 bits):  An IANA-assigned identifier for the type of object.

   Length (12 bits):  Length has the units of 32-bit words, and measures
      the length of Value.  If there is no Value, Length=0.  If the
      Length is not consistent with the contents of the object, an
      "Object Value Error" message (Appendix A.4.4.10) with subcode 0
      "Incorrect Length" MUST be returned and the message dropped.

   Value (variable):  Value is (therefore) a whole number of 32-bit
      words.  If there is any padding required, the length and location
      are be defined by the object-specific format information; objects
      that contain variable-length (e.g., string) types may need to
      include additional length subfields to do so.

A.2.1.  Object Extensibility

   The leading 2 bits of the TLV header are used to signal the desired
   treatment for objects whose Type field is unknown at the receiver.
   The following three categories of objects have been identified and
   are described here.

   AB=00 ("Mandatory"):  If the object is not understood, the entire
      message containing it MUST be rejected with an "Object Type Error"
      message (Appendix A.4.4.9) with subcode 1 ("Unrecognised Object").

   AB=01 ("Ignore"):  If the object is not understood, it MUST be
      deleted and the rest of the message processed as usual.

   AB=10 ("Forward"):  If the object is not understood, it MUST be
      retained unchanged in any message forwarded as a result of message
      processing, but not stored locally.

   The combination AB=11 is reserved.  If a message is received
   containing an object with AB=11, it MUST be rejected with an "Object
   Type Error" message (Appendix A.4.4.9) with subcode 5 ("Invalid
   Extensibility Flags").

   These extensibility rules define only the processing within the GIST
   layer.  There is no requirement on GIST implementations to support an
   extensible service interface to signalling applications, so
   unrecognised objects with AB=01 or AB=10 do not need to be indicated
   to NSLPs.

Top      Up      ToC       Page 125 
A.3.  GIST TLV Objects

A.3.1.  Message-Routing-Information (MRI)

   Type:  Message-Routing-Information

   Length:  Variable (depends on MRM)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     MRM-ID    |N|  Reserved   |                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +
   //     Method-specific addressing information (variable)       //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   MRM-ID (8 bits):  An IANA-assigned identifier for the message routing
      method.

   N-flag:  If set (N=1), this means that NATs do not need to translate
      this MRM; if clear (N=0), it means that the method-specific
      information contains network or transport layer information that a
      NAT must process.

   The remainder of the object contains method-specific addressing
   information, which is described below.

A.3.1.1.  Path-Coupled MRM

   In the case of basic path-coupled routing, the addressing information
   takes the following format.  The N-flag has a value of 0 for this
   MRM.

Top      Up      ToC       Page 126 
    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
                                   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |IP-Ver |P|T|F|S|A|B|D|Reserved |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                       Source Address                        //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                      Destination Address                    //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Source Prefix |  Dest Prefix  |   Protocol    | DS-field  |Rsv|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :       Reserved        |              Flow Label               :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                              SPI                              :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :          Source Port          :       Destination Port        :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   IP-Ver (4 bits):  The IP version number, 4 or 6.

   Source/Destination address (variable):  The source and destination
      addresses are always present and of the same type; their length
      depends on the value in the IP-Ver field.

   Source/Dest Prefix (each 8 bits):  The length of the mask to be
      applied to the source and destination addresses for address
      wildcarding.  In the normal case where the MRI refers only to
      traffic between specific host addresses, the Source/Dest Prefix
      values would both be 32 or 128 for IPv4 and IPv6, respectively.

   P-flag:  P=1 means that the Protocol field is significant.

   Protocol (8 bits):  The IP protocol number.  This MUST be ignored if
      P=0.  In the case of IPv6, the Protocol field refers to the true
      upper layer protocol carried by the packets, i.e., excluding any
      IP option headers.  This is therefore not necessarily the same as
      the Next Header value from the base IPv6 header.

   T-flag:  T=1 means that the Diffserv field (DS-field) is significant.

   DS-field (6 bits):  The Diffserv field.  See [6] and [24].

   F-flag:  F=1 means that flow label is present and is significant.  F
      MUST NOT be set if IP-Ver is not 6.

   Flow Label (20 bits):  The flow label; only present if F=1.  If F=0,
      the entire 32-bit word containing the Flow Label is absent.

Top      Up      ToC       Page 127 
   S-flag:  S=1 means that the SPI field is present and is significant.
      The S-flag MUST be 0 if the P-flag is 0.

   SPI field (32 bits):  The SPI field; see [36].  If S=0, the entire
      32-bit word containing the SPI is absent.

   A/B flags:  These can only be set if P=1.  If either is set, the port
      fields are also present.  The A flag indicates the presence of a
      source port, the B flag that of a destination port.  If P=0, the
      A/B flags MUST both be zero and the word containing the port
      numbers is absent.

   Source/Destination Port (each 16 bits):  If either of A (source), B
      (destination) is set, the word containing the port numbers is
      included in the object.  However, the contents of each field is
      only significant if the corresponding flag is set; otherwise, the
      contents of the field is regarded as padding, and the MRI refers
      to all ports (i.e., acts as a wildcard).  If the flag is set and
      Port=0x0000, the MRI will apply to a specific port, whose value is
      not yet known.  If neither of A or B is set, the word is absent.

   D-flag:  The Direction flag has the following meaning: the value 0
      means 'in the same direction as the flow' (i.e., downstream), and
      the value 1 means 'in the opposite direction to the flow' (i.e.,
      upstream).

   The MRI format defines a number of constraints on the allowed
   combinations of flags and fields in the object.  If these constraints
   are violated, this constitutes a parse error, and an "Object Value
   Error" message (Appendix A.4.4.10) with subcode 2 ("Invalid Flag-
   Field Combination") MUST be returned.

A.3.1.2.  Loose-End MRM

   In the case of the loose-end MRM, the addressing information takes
   the following format.  The N-flag has a value of 0 for this MRM.

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
                                   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |IP-Ver |D|      Reserved       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                       Source Address                        //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                      Destination Address                    //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      Up      ToC       Page 128 
   IP-Ver (4 bits):  The IP version number, 4 or 6.

   Source/Destination address (variable):  The source and destination
      addresses are always present and of the same type; their length
      depends on the value in the IP-Ver field.

   D-flag:  The Direction flag has the following meaning: the value 0
      means 'towards the edge of the network', and the value 1 means
      'from the edge of the network'.  Note that for Q-mode messages,
      the only valid value is D=0 (see Section 5.8.2).

A.3.2.  Session Identifier

   Type:  Session-Identifier

   Length:  Fixed (4 32-bit words)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                                                               +
   |                                                               |
   +                          Session ID                           +
   |                                                               |
   +                                                               +
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

A.3.3.  Network-Layer-Information (NLI)

   Type:  Network-Layer-Information

   Length:  Variable (depends on length of Peer-Identity and IP version)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   PI-Length   |    IP-TTL     |IP-Ver |        Reserved       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                  Routing State Validity Time                  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                       Peer Identity                         //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                     Interface Address                       //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      Up      ToC       Page 129 
   PI-Length (8 bits):  The byte length of the Peer Identity field.

   Peer Identity (variable):  The Peer Identity field.  Note that the
      Peer-Identity field itself is padded to a whole number of words.

   IP-TTL (8 bits):  Initial or reported IP layer TTL.

   IP-Ver (4 bits):  The IP version for the Interface Address field.

   Interface Address (variable):  The IP address allocated to the
      interface, matching the IP-Ver field.

   Routing State Validity Time (32 bits):  The time for which the
      routing state for this flow can be considered correct without a
      refresh.  Given in milliseconds.  The value 0 (zero) is reserved
      and MUST NOT be used.

A.3.4.  Stack-Proposal

   Type:  Stack-Proposal

   Length:  Variable (depends on number of profiles and size of each
      profile)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Prof-Count   |     Reserved                                  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                    Profile 1                                //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                                                               :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                    Profile N                                //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Prof-Count (8 bits): The number of profiles listed.  MUST be > 0.

   Each profile is itself a sequence of protocol layers, and the profile
   is formatted as a list as follows:

   o  The first byte is a count of the number of layers in the profile.
      MUST be > 0.

   o  This is followed by a sequence of 1-byte MA-Protocol-IDs as
      described in Section 5.7.

Top      Up      ToC       Page 130 
   o  The profile is padded to a word boundary with 0, 1, 2, or 3 zero
      bytes.  These bytes MUST be ignored at the receiver.

   If there are no profiles (Prof-Count=0), then an "Object Value Error"
   message (Appendix A.4.4.10) with subcode 1 ("Value Not Supported")
   MUST be returned; if a particular profile is empty (the leading byte
   of the profile is zero), then subcode 3 ("Empty List") MUST be used.
   In both cases, the message MUST be dropped.

A.3.5.  Stack-Configuration-Data

   Type:  Stack-Configuration-Data

   Length:  Variable (depends on number of protocols and size of each
      MA-protocol-options field)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   MPO-Count   |     Reserved                                  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           MA-Hold-Time                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                     MA-protocol-options 1                   //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                                                               :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                     MA-protocol-options N                   //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   MPO-Count (8 bits):  The number of MA-protocol-options fields present
      (these contain their own length information).  The MPO-Count MAY
      be zero, but this will only be the case if none of the MA-
      protocols referred to in the Stack-Proposal require option data.

   MA-Hold-Time (32 bits):  The time for which the messaging association
      will be held open without traffic or a hello message.  Note that
      this value is given in milliseconds, so the default time of 30
      seconds (Section 4.4.5) corresponds to a value of 30000.  The
      value 0 (zero) is reserved and MUST NOT be used.

Top      Up      ToC       Page 131 
   The MA-protocol-options fields are formatted as follows:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |MA-Protocol-ID |     Profile   |    Length     |D|  Reserved   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                         Options Data                        //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   MA-Protocol-ID (8 bits):  Protocol identifier as described in
      Section 5.7.

   Profile (8 bits):  Tag indicating which profile from the accompanying
      Stack-Proposal object this applies to.  Profiles are numbered from
      1 upwards; the special value 0 indicates 'applies to all
      profiles'.

   Length (8 bits):  The byte length of MA-protocol-options field that
      follows.  This will be zero-padded up to the next word boundary.

   D-flag:  If set (D=1), this protocol MUST NOT be used for a messaging
      association.

   Options Data (variable):  Any options data for this protocol.  Note
      that the format of the options data might differ depending on
      whether the field is in a Query or Response.

A.3.6.  Query-Cookie

   Type:  Query-Cookie

   Length:  Variable (selected by Querying node)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                        Query-Cookie                         //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The content is defined by the implementation.  See Section 8.5 for
   further discussion.

Top      Up      ToC       Page 132 
A.3.7.  Responder-Cookie

   Type:  Responder-Cookie

   Length:  Variable (selected by Responding node)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                      Responder-Cookie                       //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The content is defined by the implementation.  See Section 8.5 for
   further discussion.

A.3.8.  Hello-ID

   Type:  Hello-ID

   Length:  Fixed (1 32-bit word)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          Hello-ID                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The content is defined by the implementation.  See Section 5.2.2 for
   further discussion.

A.3.9.  NAT-Traversal

   Type:  NAT-Traversal

   Length:  Variable (depends on length of contained fields)

   This object is used to support the NAT traversal mechanisms described
   in Section 7.2.2.

Top      Up      ToC       Page 133 
    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | MRI-Length    | Type-Count    |  NAT-Count    |  Reserved     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //            Original Message-Routing-Information             //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                 List of translated objects                  //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Length of opaque information  |                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                              //
   //                Information replaced by NAT #1                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                                                               :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Length of opaque information  |                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                              //
   //                Information replaced by NAT #N                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   MRI-Length (8 bits):  The length of the included MRI payload in
      32-bit words.

   Original Message-Routing-Information (variable):  The MRI data from
      when the message was first sent, not including the object header.

   Type-Count (8 bits):  The number of objects in the 'List of
      translated objects' field.

   List of translated objects (variable):  This field lists the types of
      objects that were translated by every NAT through which the
      message has passed.  Each element in the list is a 16-bit field
      containing the first 16 bits of the object TLV header, including
      the AB extensibility flags, 2 reserved bits, and 12-bit object
      type.  The list is initialised by the first NAT on the path;
      subsequent NATs may delete elements in the list.  Padded with 2
      null bytes if necessary.

   NAT-Count (8 bits):  The number of NATs traversed by the message, and
      the number of opaque payloads at the end of the object.  The
      length fields for each opaque payload are byte counts, not
      including the 2 bytes of the length field itself.  Note that each
      opaque information field is zero-padded to the next 32-bit word
      boundary if necessary.

Top      Up      ToC       Page 134 
A.3.10.  NSLP-Data

   Type:  NSLP-Data

   Length:  Variable (depends on NSLP)

   This object is used to deliver data between NSLPs.  GIST regards the
   data as a number of complete 32-bit words, as given by the length
   field in the TLV; any padding to a word boundary must be carried out
   within the NSLP itself.

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                          NSLP Data                          //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

A.4.  Errors

A.4.1.  Error Object

   Type:  Error

   Length:  Variable (depends on error)

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Error Class  |           Error Code          | Error Subcode |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |S|M|C|D|Q|       Reserved      |  MRI Length   |  Info Count   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                         Common Header                         +
   |                    (of original message)                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                          Session ID                           :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                    Message Routing Information                :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                 Additional Information Fields                 :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :                       Debugging Comment                       :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      Up      ToC       Page 135 
   The flags are:
   S - S=1 means the Session ID object is present.
   M - M=1 means MRI object is present.
   C - C=1 means a debug Comment is present after header.
   D - D=1 means the original message was received in D-mode.
   Q - Q=1 means the original message was received Q-mode encapsulated
       (can't be set if D=0).

   A GIST Error Object contains an 8-bit error-class (see
   Appendix A.4.3), a 16-bit error-code, an 8-bit error-subcode, and as
   much information about the message that triggered the error as is
   available.  This information MUST include the common header of the
   original message and MUST also include the Session ID and MRI objects
   if these could be decoded correctly.  These objects are included in
   their entirety, except for their TLV Headers.  The MRI Length field
   gives the length of the MRI object in 32-bit words.

   The Info Count field contains the number of Additional Information
   fields in the object, and the possible formats for these fields are
   given in Appendix A.4.2.  The precise set of fields to include
   depends on the error code/subcode.  For every error description in
   the error catalogue Appendix A.4.4, the line "Additional Info:"
   states what fields MUST be included; further fields beyond these MAY
   be included by the sender, and the fields may be included in any
   order.  The Debugging Comment is a null-terminated UTF-8 string,
   padded if necessary to a whole number of 32-bit words with more null
   characters.

A.4.2.  Additional Information Fields (AI)

   The Common Error Header may be followed by some Additional
   Information fields.  Each Additional Information field has a simple
   TLV format as follows:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          AI-Type              |         AI-Length             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                          AI-Value                           //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   The AI-Type is a 16-bit IANA-assigned value.  The AI-Length gives the
   number of 32-bit words in AI-Value; if an AI-Value is not present,
   AI-Length=0.  The AI-Types and AI-Lengths and AI-Value formats of the
   currently defined Additional Information fields are shown below.

Top      Up      ToC       Page 136 
   Message Length Info:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Calculated Length         |           Reserved            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   AI-Type: 1
   AI-Length: 1
   Calculated Length (16 bits): the length of the original message
   calculated by adding up all the objects in the message.  Measured in
   32-bit words.

   MTU Info:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           Link MTU            |           Reserved            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   AI-Type: 2
   AI-Length: 1
   Link MTU (16 bits): the IP MTU for a link along which a message
                       could not be sent.  Measured in bytes.

   Object Type Info:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Object Type           |           Reserved            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   AI-Type: 3
   AI-Length: 1
   Object type (16 bits): This provides information about the type
                          of object that caused the error.

   Object Value Info:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Rsv  |  Real Object Length   |            Offset             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   //                           Object                            //
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   AI-Type: 4
   AI-Length: variable (depends on object length)

Top      Up      ToC       Page 137 
   This object carries information about a TLV object that was found
   to be invalid in the original message.  An error message MAY contain
   more than one Object Value Info object.

   Real Object Length (12 bits):  Since the length in the original TLV
      header may be inaccurate, this field provides the actual length of
      the object (including the TLV header) included in the error
      message.  Measured in 32-bit words.

   Offset (16 bits):  The byte in the object at which the GIST node
      found the error.  The first byte in the object has offset=0.

   Object (variable):  The invalid TLV object (including the TLV
      header).

A.4.3.  Error Classes

   The first byte of the Error Object, "Error Class", indicates the
   severity level.  The currently defined severity levels are:

   0 (Informational):  reply data that should not be thought of as
      changing the condition of the protocol state machine.

   1 (Success):  reply data that indicates that the message being
      responded to has been processed successfully in some sense.

   2 (Protocol-Error):  the message has been rejected because of a
      protocol error (e.g., an error in message format).

   3 (Transient-Failure):  the message has been rejected because of a
      particular local node status that may be transient (i.e., it may
      be worthwhile to retry after some delay).

   4 (Permanent-Failure):  the message has been rejected because of
      local node status that will not change without additional out-of-
      band (e.g., management) operations.

   Additional error class values are reserved.

   The allocation of error classes to particular errors is not precise;
   the above descriptions are deliberately informal.  Actual error
   processing SHOULD take into account the specific error in question;
   the error class may be useful supporting information (e.g., in
   network debugging).

Top      Up      ToC       Page 138 
A.4.4.  Error Catalogue

   This section lists all the possible GIST errors, including when they
   are raised and what Additional Information fields MUST be carried in
   the Error Object.

A.4.4.1.  Common Header Parse Error

   Class:              Protocol-Error
   Code:               1
   Additional Info:    For subcode 3 only, Message Length Info carries
                       the calculated message length.

   This message is sent if a GIST node receives a message where the
   common header cannot be parsed correctly, or where an error in the
   overall message format is detected.  Note that in this case the
   original MRI and Session ID MUST NOT be included in the Error Object.
   This error code is split into subcodes as follows:

   0: Unknown Version:  The GIST version is unknown.  The (highest)
      supported version supported by the node can be inferred from the
      common header of the Error message itself.

   1: Unknown Type:  The GIST message type is unknown.

   2: Invalid R-flag:  The R-flag in the header is inconsistent with the
      message type.

   3: Incorrect Message Length:  The overall message length is not
      consistent with the set of objects carried.

   4: Invalid E-flag:  The E-flag is set in the header, but this is not
      a Data message.

   5: Invalid C-flag:  The C-flag was set on something other than a
      Query message or Q-mode Data message, or was clear on a Query
      message.

Top      Up      ToC       Page 139 
A.4.4.2.  Hop Limit Exceeded

   Class:              Permanent-Failure
   Code:               2
   Additional Info:    None

   This message is sent if a GIST node receives a message with a GIST
   hop count of zero, or a GIST node tries to forward a message after
   its GIST hop count has been decremented to zero on reception.  This
   message indicates either a routing loop or too small an initial hop
   count value.

A.4.4.3.  Incorrect Encapsulation

   Class:              Protocol-Error
   Code:               3
   Additional Info:    None

   This message is sent if a GIST node receives a message that uses an
   incorrect encapsulation method (e.g., a Query arrives over an MA, or
   the Confirm for a handshake that sets up a messaging association
   arrives in D-mode).

A.4.4.4.  Incorrectly Delivered Message

   Class:              Protocol-Error
   Code:               4
   Additional Info:    None

   This message is sent if a GIST node receives a message over an MA
   that is not associated with the MRI/NSLPID/SID combination in the
   message.

A.4.4.5.  No Routing State

   Class:              Protocol-Error
   Code:               5
   Additional Info:    None

   This message is sent if a node receives a message for which routing
   state should exist, but has not yet been created and thus there is no
   appropriate Querying-SM or Responding-SM.  This can occur on
   receiving a Data or Confirm message at a node whose policy requires
   routing state to exist before such messages can be accepted.  See
   also Section 6.1 and Section 6.3.

Top      Up      ToC       Page 140 
A.4.4.6.  Unknown NSLPID

   Class:              Permanent-Failure
   Code:               6
   Additional Info:    None

   This message is sent if a router receives a directly addressed
   message for an NSLP that it does not support.

A.4.4.7.  Endpoint Found

   Class:              Permanent-Failure
   Code:               7
   Additional Info:    None

   This message is sent if a GIST node at a flow endpoint receives a
   Query message for an NSLP that it does not support.

A.4.4.8.  Message Too Large

   Class:              Permanent-Failure
   Code:               8
   Additional Info:    MTU Info

   This message is sent if a router receives a message that it can't
   forward because it exceeds the IP MTU on the next or subsequent hops.

A.4.4.9.  Object Type Error

   Class:              Protocol-Error
   Code:               9
   Additional Info:    Object Type Info

   This message is sent if a GIST node receives a message containing a
   TLV object with an invalid type.  The message indicates the object
   type at fault in the additional info field.  This error code is split
   into subcodes as follows:

   0: Duplicate Object:  This subcode is used if a GIST node receives a
      message containing multiple instances of an object that may only
      appear once in a message.  In the current specification, this
      applies to all objects.

   1: Unrecognised Object:  This subcode is used if a GIST node receives
      a message containing an object that it does not support, and the
      extensibility flags AB=00.

Top      Up      ToC       Page 141 
   2: Missing Object:  This subcode is used if a GIST node receives a
      message that is missing one or more mandatory objects.  This
      message is also sent if a Stack-Proposal is sent without a
      matching Stack-Configuration-Data object when one was necessary,
      or vice versa.

   3: Invalid Object Type:  This subcode is used if the object type is
      known, but it is not valid for this particular GIST message type.

   4: Untranslated Object:  This subcode is used if the object type is
      known and is mandatory to interpret, but it contains addressing
      data that has not been translated by an intervening NAT.

   5: Invalid Extensibility Flags:  This subcode is used if an object is
      received with the extensibility flags AB=11.

A.4.4.10.  Object Value Error

   Class:              Protocol-Error
   Code:               10
   Additional Info:    1 or 2 Object Value Info fields as given below

   This message is sent if a node receives a message containing an
   object that cannot be properly parsed.  The error message contains a
   single Object Value Info object, except for subcode 5 as stated
   below.  This error code is split into subcodes as follows:

   0: Incorrect Length:  The overall length does not match the object
      length calculated from the object contents.

   1: Value Not Supported:  The value of a field is not supported by the
      GIST node.

   2: Invalid Flag-Field Combination:  An object contains an invalid
      combination of flags and/or fields.  At the moment, this only
      relates to the Path-Coupled MRI (Appendix A.3.1.1), but in future
      there may be more.

   3: Empty List:  At the moment, this only relates to Stack-Proposals.
      The error message is sent if a stack proposal with a length > 0
      contains only null bytes (a length of 0 is handled as "Value Not
      Supported").

   4: Invalid Cookie:  The message contains a cookie that could not be
      verified by the node.

Top      Up      ToC       Page 142 
   5: Stack-Proposal - Stack-Configuration-Data Mismatch:  This subcode
      is used if a GIST node receives a message in which the data in the
      Stack-Proposal object is inconsistent with the information in the
      Stack Configuration Data object.  In this case, both the Stack-
      Proposal object and Stack-Configuration-Data object MUST be
      included in separate Object Value Info fields in that order.

A.4.4.11.  Invalid IP-Layer TTL

   Class:              Permanent-Failure
   Code:               11
   Additional Info:    None

   This error indicates that a message was received with an IP-layer TTL
   outside an acceptable range, for example, that an upstream Query was
   received with an IP layer TTL of less than 254 (i.e., more than one
   IP hop from the sender).  The actual IP distance can be derived from
   the IP-TTL information in the NLI object carried in the same message.

A.4.4.12.  MRI Validation Failure

   Class:              Permanent-Failure
   Code:               12
   Additional Info:    Object Value Info

   This error indicates that a message was received with an MRI that
   could not be accepted, e.g., because of too much wildcarding or
   failing some validation check (cf. Section 5.8.1.2).  The Object
   Value Info includes the MRI so the error originator can indicate the
   part of the MRI that caused the problem.  The error code is divided
   into subcodes as follows:

   0: MRI Too Wild:  The MRI contained too much wildcarding (e.g., too
      short a destination address prefix) to be forwarded correctly down
      a single path.

   1: IP Version Mismatch:  The MRI in a path-coupled Query message
      refers to an IP version that is not implemented on the interface
      used, or is different from the IP version of the Query
      encapsulation (see Section 7.4).

   2: Ingress Filter Failure:  The MRI in a path-coupled Query message
      describes a flow that would not pass ingress filtering on the
      interface used.

Top      Up      ToC       Page 143 
Appendix B.  API between GIST and Signalling Applications

   This appendix provides an abstract API between GIST and signalling
   applications.  It should not constrain implementers, but rather help
   clarify the interface between the different layers of the NSIS
   protocol suite.  In addition, although some of the data types carry
   the information from GIST information elements, this does not imply
   that the format of that data as sent over the API has to be the same.

   Conceptually, the API has similarities to the sockets API,
   particularly that for unconnected UDP sockets.  An extension for an
   API like that for UDP connected sockets could be considered.  In this
   case, for example, the only information needed in a SendMessage
   primitive would be NSLP-Data, NSLP-Data-Size, and NSLP-Message-Handle
   (which can be null).  Other information that was persistent for a
   group of messages could be configured once for the socket.  Such
   extensions may make a concrete implementation more efficient but do
   not change the API semantics, and so are not considered further here.

B.1.  SendMessage

   This primitive is passed from a signalling application to GIST.  It
   is used whenever the signalling application wants to initiate sending
   a message.

   SendMessage ( NSLP-Data, NSLP-Data-Size, NSLP-Message-Handle,
                 NSLPID, Session-ID, MRI, SII-Handle,
                 Transfer-Attributes, Timeout, IP-TTL, GIST-Hop-Count )

   The following arguments are mandatory:

   NSLP-Data:  The NSLP message itself.

   NSLP-Data-Size:  The length of NSLP-Data.

   NSLP-Message-Handle:  A handle for this message that can be used by
      GIST as a reference in subsequent MessageStatus notifications
      (Appendix B.3).  Notifications could be about error conditions or
      about the security attributes that will be used for the message.
      A NULL handle may be supplied if the NSLP is not interested in
      such notifications.

   NSLPID:  An identifier indicating which NSLP this is.

   Session-ID:  The NSIS session identifier.  Note that it is assumed
      that the signalling application provides this to GIST rather than
      GIST providing a value itself.

Top      Up      ToC       Page 144 
   MRI:  Message routing information for use by GIST in determining the
      correct next GIST hop for this message.  The MRI implies the
      message routing method to be used and the message direction.

   The following arguments are optional:

   SII-Handle:  A handle, previously supplied by GIST, to a data
      structure that should be used to route the message explicitly to a
      particular GIST next hop.

   Transfer-Attributes:  Attributes defining how the message should be
      handled (see Section 4.1.2).  The following attributes can be
      considered:

      Reliability:  Values 'unreliable' or 'reliable'.

      Security:  This attribute allows the NSLP to specify what level of
         security protection is requested for the message (such as
         'integrity' or 'confidentiality') and can also be used to
         specify what authenticated signalling source and destination
         identities should be used to send the message.  The
         possibilities can be learned by the signalling application from
         prior MessageStatus or RecvMessage notifications.  If an NSLP-
         Message-Handle is provided, GIST will inform the signalling
         application of what values it has actually chosen for this
         attribute via a MessageStatus callback.  This might take place
         either synchronously (where GIST is selecting from available
         messaging associations) or asynchronously (when a new messaging
         association needs to be created).

      Local Processing:  This attribute contains hints from the
         signalling application about what local policy should be
         applied to the message -- in particular, its transmission
         priority relative to other messages, or whether GIST should
         attempt to set up or maintain forward routing state.

   Timeout:  Length of time GIST should attempt to send this message
      before indicating an error.

   IP-TTL:  The value of the IP layer TTL that should be used when
      sending this message (may be overridden by GIST for particular
      messages).

   GIST-Hop-Count:  The value for the hop count when sending the
      message.

Top      Up      ToC       Page 145 
B.2.  RecvMessage

   This primitive is passed from GIST to a signalling application.  It
   is used whenever GIST receives a message from the network, including
   the case of null messages (zero-length NSLP payload), typically
   initial Query messages.  For Queries, the results of invoking this
   primitive are used by GIST to check whether message routing state
   should be created (see the discussion of the 'Routing-State-Check'
   argument below).

   RecvMessage ( NSLP-Data, NSLP-Data-Size, NSLPID, Session-ID, MRI,
                 Routing-State-Check, SII-Handle, Transfer-Attributes,
                 IP-TTL, IP-Distance, GIST-Hop-Count,
                 Inbound-Interface )

   NSLP-Data:  The NSLP message itself (may be empty).

   NSLP-Data-Size:  The length of NSLP-Data (may be zero).

   NSLPID:  An identifier indicating which NSLP this message is for.

   Session-ID:  The NSIS session identifier.

   MRI:  Message routing information that was used by GIST in forwarding
      this message.  Implicitly defines the message routing method that
      was used and the direction of the message relative to the MRI.

   Routing-State-Check:  This boolean is True if GIST is checking with
      the signalling application to see if routing state should be
      created with the peer or the message should be forwarded further
      (see Section 4.3.2).  If True, the signalling application should
      return the following values via the RecvMessage call:

         A boolean indicating whether to set up the state.

         Optionally, an NSLP-Payload to carry in the generated Response
         or forwarded Query respectively.

      This mechanism could be extended to enable the signalling
      application to indicate to GIST whether state installation should
      be immediate or deferred (see Section 5.3.3 and Section 6.3 for
      further discussion).

   SII-Handle:  A handle to a data structure, identifying a peer address
      and interface.  Can be used to identify route changes and for
      explicit routing to a particular GIST next hop.

Top      Up      ToC       Page 146 
   Transfer-Attributes:  The reliability and security attributes that
      were associated with the reception of this particular message.  As
      well as the attributes associated with SendMessage, GIST may
      indicate the level of verification of the addresses in the MRI.
      Three attributes can be indicated:

      *  Whether the signalling source address is one of the flow
         endpoints (i.e., whether this is the first or last GIST hop).

      *  Whether the signalling source address has been validated by a
         return routability check.

      *  Whether the message was explicitly routed (and so has not been
         validated by GIST as delivered consistently with local routing
         state).

   IP-TTL:  The value of the IP layer TTL this message was received with
      (if available).

   IP-Distance:  The number of IP hops from the peer signalling node
      that sent this message along the path, or 0 if this information is
      not available.

   GIST-Hop-Count:  The value of the hop count the message was received
      with, after being decremented in the GIST receive-side processing.

   Inbound-Interface:  Attributes of the interface on which the message
      was received, such as whether it lies on the internal or external
      side of a NAT.  These attributes have only local significance and
      are defined by the implementation.

B.3.  MessageStatus

   This primitive is passed from GIST to a signalling application.  It
   is used to notify the signalling application that a message that it
   requested to be sent could not be dispatched, or to inform the
   signalling application about the transfer attributes that have been
   selected for the message (specifically, security attributes).  The
   signalling application can respond to this message with a return code
   to abort the sending of the message if the attributes are not
   acceptable.

  MessageStatus ( NSLP-Message-Handle, Transfer-Attributes, Error-Type )

   NSLP-Message-Handle:  A handle for the message provided by the
      signalling application in SendMessage.

Top      Up      ToC       Page 147 
   Transfer-Attributes:  The reliability and security attributes that
      will be used to transmit this particular message.

   Error-Type:  Indicates the type of error that occurred, for example,
      'no next node found'.

B.4.  NetworkNotification

   This primitive is passed from GIST to a signalling application.  It
   indicates that a network event of possible interest to the signalling
   application occurred.

   NetworkNotification ( NSLPID, MRI, Network-Notification-Type )

   NSLPID:  An identifier indicating which NSLP this is message is for.

   MRI:  Provides the message routing information to which the network
      notification applies.

   Network-Notification-Type:  Indicates the type of event that caused
      the notification and associated additional data.  Five events have
      been identified:

      Last Node:  GIST has detected that this is the last NSLP-aware
         node in the path.  See Section 4.3.4.

      Routing Status Change:  GIST has installed new routing state, has
         detected that existing routing state may no longer be valid, or
         has re-established existing routing state.  See Section 7.1.3.
         The new status is reported; if the status is Good, the SII-
         Handle of the peer is also reported, as for RecvMessage.

      Route Deletion:  GIST has determined that an old route is now
         definitely invalid, e.g., that flows are definitely not using
         it (see Section 7.1.4).  The SII-Handle of the peer is also
         reported.

      Node Authorisation Change:  The authorisation status of a peer has
         changed, meaning that routing state is no longer valid or that
         a signalling peer is no longer reachable; see Section 4.4.2.

      Communication Failure:  Communication with the peer has failed;
         messages may have been lost.

Top      Up      ToC       Page 148 
B.5.  SetStateLifetime

   This primitive is passed from a signalling application to GIST.  It
   indicates the duration for which the signalling application would
   like GIST to retain its routing state.  It can also give a hint that
   the signalling application is no longer interested in the state.

   SetStateLifetime ( NSLPID, MRI, SID, State-Lifetime )

   NSLPID:  Provides the NSLPID to which the routing state lifetime
      applies.

   MRI:  Provides the message routing information to which the routing
      state lifetime applies; includes the direction (in the D-flag).

   SID:  The session ID that the signalling application will be using
      with this routing state.  Can be wildcarded.

   State-Lifetime:  Indicates the lifetime for which the signalling
      application wishes GIST to retain its routing state (may be zero,
      indicating that the signalling application has no further interest
      in the GIST state).

B.6.  InvalidateRoutingState

   This primitive is passed from a signalling application to GIST.  It
   indicates that the signalling application has knowledge that the next
   signalling hop known to GIST may no longer be valid, either because
   of changes in the network routing or the processing capabilities of
   signalling application nodes.  See Section 7.1.

   InvalidateRoutingState ( NSLPID, MRI, Status, NSLP-Data,
                            NSLP-Data-Size, Urgent )

   NSLPID:  The NSLP originating the message.  May be null (in which
      case, the invalidation applies to all signalling applications).

   MRI:  The flow for which routing state should be invalidated;
      includes the direction of the change (in the D-flag).

   Status:  The new status that should be assumed for the routing state,
      one of Bad or Tentative (see Section 7.1.3).

   NSLP-Data, NSLP-Data-Size:  (optional) A payload provided by the NSLP
      to be used the next GIST handshake.  This can be used as part of a
      conditional peering process (see Section 4.3.2).  The payload will
      be transmitted without security protection.

Top      Up      ToC       Page 149 
   Urgent:  A hint as to whether rediscovery should take place
      immediately or only with the next signalling message.

Appendix C.  Deployment Issues with Router Alert Options

   The GIST peer discovery handshake (Section 4.4.1) depends on the
   interception of Q-mode encapsulated IP packets (Section 4.3.1 and
   Section 5.3.2) by routers.  There are two fundamental requirements on
   the process:

   1.  Packets relevant to GIST must be intercepted.

   2.  Packets not relevant to GIST must be forwarded transparently.

   This specification defines the GIST behaviour to ensure that both
   requirements are met for a GIST-capable node.  However, GIST packets
   will also encounter non-GIST nodes, for which requirement (2) still
   applies.  If non-GIST nodes block Q-mode packets, GIST will not
   function.  It is always possible for middleboxes to block specific
   traffic types; by using a normal UDP encapsulation for Q-mode
   traffic, GIST allows NATs at least to pass these messages
   (Section 7.2.1), and firewalls can be configured with standard
   policies.  However, where the Q-mode encapsulation uses a Router
   Alert Option (RAO) at the IP level this can lead to additional
   problems.  The situation is different for IPv4 and IPv6.

   The IPv4 RAO is defined by [13], which defines the RAO format with a
   2-byte value field; however, only one value (zero) is defined and
   there is no IANA registry for further allocations.  It states that
   unknown values should be ignored (i.e., the packets forwarded as
   normal IP traffic); however, it has also been reported that some
   existing implementations simply ignore the RAO value completely (i.e.
   process any packet with an RAO as though the option value was zero).
   Therefore, the use of non-zero RAO values cannot be relied on to make
   GIST traffic transparent to existing implementations.  (Note that it
   may still be valuable to be able to allocate non-zero RAO values for
   IPv4: this makes the interception process more efficient for nodes
   that do examine the value field, and makes no difference to nodes
   that *incorrectly* ignore it.  Whether or not non-zero RAO values are
   used does not change the GIST protocol operation, but needs to be
   decided when new NSLPs are registered.)

   The second stage of the analysis is therefore what happens when a
   non-GIST node that implements RAO handling sees a Q-mode packet.  The
   RAO specification simply states "Routers that recognize this option
   shall examine packets carrying it more closely (check the IP Protocol

Top      Up      ToC       Page 150 
   field, for example) to determine whether or not further processing is
   necessary".  There are two possible basic behaviours for GIST
   traffic:

   1.  The "closer examination" of the packet is sufficiently
       intelligent to realise that the node does not need to process it
       and should forward it.  This could either be by virtue of the
       fact that the node has not been configured to match IP-
       Protocol=UDP for RAO packets at all or that even if UDP traffic
       is intercepted the port numbers do not match anything locally
       configured.

   2.  The "closer examination" of the packet identifies it as UDP, and
       delivers it to the UDP stack on the node.  In this case, it can
       no longer be guaranteed to be processed appropriately.  Most
       likely, it will simply be dropped or rejected with an ICMP error
       (because there is no GIST process on the destination port to
       which to deliver it).

   Analysis of open-source operating system source code shows the first
   type of behaviour, and this has also been seen in direct GIST
   experiments with commercial routers, including the case when they
   process other uses of the RAO (i.e., RSVP).  However, it has also
   been reported that other RAO implementations will exhibit the second
   type of behaviour.  The consequence of this would be that Q-mode
   packets are blocked in the network and GIST could not be used.  Note
   that although this is caused by some subtle details in the RAO
   processing rules, the end result is the same as if the packet was
   simply blocked for other reasons (for example, many IPv4 firewalls
   drop packets with options by default).

   The GIST specification allows two main options for circumventing
   nodes that block Q-mode traffic in IPv4.  Whether to use these
   options is a matter of implementation and configuration choice.

   o  A GIST node can be configured to send Q-mode packets without the
      RAO at all.  This should avoid the above problems, but should only
      be done if it is known that nodes on the path to the receiver are
      able to intercept such packets.  (See Section 5.3.2.1.)

   o  If a GIST node can identify exactly where the packets are being
      blocked (e.g., from ICMP messages), or can discover some point on
      the path beyond the blockage (e.g., by use of traceroute or by
      routing table analysis), it can send the Q-mode messages to that
      point using IP-in-IP tunelling without any RAO.  This bypasses the
      input side processing on the blocking node, but picks up normal
      GIST behaviour beyond it.

Top      Up      ToC       Page 151 
   If in the light of deployment experience the problem of blocked
   Q-mode traffic turns out to be widespread and these techniques turn
   out to be insufficient, a further possibility is to define an
   alternative Q-mode encapsulation that does not use UDP.  This would
   require a specification change.  Such an option would be restricted
   to network-internal use, since operation through NATs and firewalls
   would be much harder with it.

   The situation with IPv6 is rather different, since in that case the
   use of non-zero RAO values is well established in the specification
   ([17]) and an IANA registry exists.  The main problem is that several
   implementations are still immature: for example, some treat any RAO-
   marked packet as though it was for local processing without further
   analysis.  Since this prevents any RAO usage at all (including the
   existing standardised ones) in such a network, it seems reasonable to
   assume that such implementations will be fixed as part of the general
   deployment of IPv6.

Appendix D.  Example Routing State Table and Handshake

   Figure 11 shows a signalling scenario for a single flow being managed
   by two signalling applications using the path-coupled message routing
   method.  The flow sender and receiver and one router support both;
   two other routers support one each.  The figure also shows the
   routing state table at node B.

Top      Up      ToC       Page 152 
       A                        B          C          D           E
   +------+                  +-----+    +-----+    +-----+    +--------+
   | Flow |    +-+    +-+    |NSLP1|    |NSLP1|    |     |    |  Flow  |
   |Sender|====|R|====|R|====|NSLP2|====|     |====|NSLP2|====|Receiver|
   |      |    +-+    +-+    |GIST |    |GIST |    |GIST |    |        |
   +------+                  +-----+    +-----+    +-----+    +--------+
             Flow Direction ------------------------------>>

   +------------------------------------+---------+--------+-----------+
   |     Message Routing Information    | Session | NSLPID |  Routing  |
   |                                    |    ID   |        |   State   |
   +------------------------------------+---------+--------+-----------+
   |    MRM = Path-Coupled; Flow ID =   |  0xABCD |  NSLP1 |    IP-A   |
   |   {IP-A, IP-E, proto/ports}; D=up  |         |        |           |
   |                                    |         |        |           |
   |    MRM = Path-Coupled; Flow ID =   |  0xABCD |  NSLP1 |   (null)  |
   |  {IP-A, IP-E, proto/ports}; D=down |         |        |           |
   |                                    |         |        |           |
   |    MRM = Path-Coupled; Flow ID =   |  0x1234 |  NSLP2 |    IP-A   |
   |   {IP-A, IP-E, proto/ports}; D=up  |         |        |           |
   |                                    |         |        |           |
   |    MRM = Path-Coupled; Flow ID =   |  0x1234 |  NSLP2 | Points to |
   |  {IP-A, IP-E, proto/ports}; D=down |         |        |   B-D MA  |
   +------------------------------------+---------+--------+-----------+

                     Figure 11: A Signalling Scenario

   The upstream state is just the same address for each application.
   For the downstream direction, NSLP1 only requires D-mode messages and
   so no explicit routing state towards C is needed.  NSLP2 requires a
   messaging association for its messages towards node D, and node C
   does not process NSLP2 at all, so the peer state for NSLP2 is a
   pointer to a messaging association that runs directly from B to D.
   Note that E is not visible in the state table (except implicitly in
   the address in the message routing information); routing state is
   stored only for adjacent peers.  (In addition to the peer
   identification, IP hop counts are stored for each peer where the
   state itself if not null; this is not shown in the table.)

   Figure 12 shows a GIST handshake setting up a messaging association
   for B-D signalling, with the exchange of Stack Proposals and MA-
   protocol-options in each direction.  The Querying node selects TLS/
   TCP as the stack configuration and sets up the messaging association
   over which it sends the Confirm.

Top      Up      ToC       Page 153 
    -------------------------- Query ---------------------------->
    IP(Src=IP#A; Dst=IP#E; RAO for NSLP2); UDP(Src=6789; Dst=GIST)
    D-mode magic number (0x4e04 bda5)
    GIST(Header(Type=Query; NSLPID=NSLP2; C=1; R=1; S=0)
         MRI(MRM=Path-Coupled; Flow=F; Direction=down)
         SessionID(0x1234) NLI(Peer='string1'; IA=IP#B)
         QueryCookie(0x139471239471923526)
         StackProposal(#Proposals=3;1=TLS/TCP; 2=TLS/SCTP; 3=TCP)
         StackConfigurationData(HoldTime=300; #MPO=2;
           TCP(Applicable: all; Data: null)
           SCTP(Applicable: all; Data: null)))

    <---------------------- Response ----------------------------
    IP(Src=IP#D; Dst=IP#B); UDP(Src=GIST; Dst=6789)
    D-mode magic number (0x4e04 bda5)
    GIST(Header(Type=Response; NSLPID=NSLP2; C=0; R=1; S=1)
         MRI(MRM=Path-Coupled; Flow=F; Direction=up)
         SessionID(0x1234) NLI(Peer='stringr2', IA=IP#D)
         QueryCookie(0x139471239471923526)
         ResponderCookie(0xacdefedcdfaeeeded)
         StackProposal(#Proposals=3; 1=TCP; 2=SCTP; 3=TLS/TCP)
         StackConfigurationData(HoldTime=200; #MPO=3;
           TCP(Applicable: 3; Data: port=6123)
           TCP(Applicable: 1; Data: port=5438)
           SCTP(Applicable: all; Data: port=3333)))

    -------------------------TCP SYN----------------------->
    <----------------------TCP SYN/ACK----------------------
    -------------------------TCP ACK----------------------->
    TCP connect(IP Src=IP#B; IP Dst=IP#D; Src Port=9166; Dst Port=6123)
    <-----------------------TLS INIT----------------------->

    ------------------------ Confirm ---------------------------->
    [Sent within messaging association]
    GIST(Header(Type=Confirm; NSLPID=NSLP2; C=0; R=0; S=1)
         MRI(MRM=Path-Coupled; Flow=F; Direction=down)
         SessionID(0x1234) NLI(Peer='string1'; IA=IP#B)
         ResponderCookie(0xacdefedcdfaeeeded)
         StackProposal(#Proposals=3; 1=TCP; 2=SCTP; 3=TLS/TCP)
         StackConfigurationData(HoldTime=300))

                Figure 12: GIST Handshake Message Sequence

Top      Up      ToC       Page 154 
Authors' Addresses

   Henning Schulzrinne
   Columbia University
   Department of Computer Science
   450 Computer Science Building
   New York, NY  10027
   US

   Phone: +1 212 939 7042
   EMail: hgs+nsis@cs.columbia.edu
   URI:   http://www.cs.columbia.edu


   Robert Hancock
   Roke Manor Research
   Old Salisbury Lane
   Romsey, Hampshire  SO51 0ZN
   UK

   EMail: robert.hancock@roke.co.uk
   URI:   http://www.roke.co.uk