tech-invite   World Map
3GPP     Specs     Glossaries     UICC       IETF     RFCs     Groups     SIP     ABNFs       T+       Search     Home

RFC 3588

 
 
 

Diameter Base Protocol

Part 3 of 5, p. 56 to 90
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 56 
5.  Diameter Peers

   This section describes how Diameter nodes establish connections and
   communicate with peers.

5.1.  Peer Connections

   Although a Diameter node may have many possible peers that it is able
   to communicate with, it may not be economical to have an established
   connection to all of them.  At a minimum, a Diameter node SHOULD have
   an established connection with two peers per realm, known as the
   primary and secondary peers.  Of course, a node MAY have additional
   connections, if it is deemed necessary.  Typically, all messages for
   a realm are sent to the primary peer, but in the event that failover
   procedures are invoked, any pending requests are sent to the
   secondary peer.  However, implementations are free to load balance
   requests between a set of peers.

   Note that a given peer MAY act as a primary for a given realm, while
   acting as a secondary for another realm.

   When a peer is deemed suspect, which could occur for various reasons,
   including not receiving a DWA within an allotted timeframe, no new
   requests should be forwarded to the peer, but failover procedures are
   invoked.  When an active peer is moved to this mode, additional
   connections SHOULD be established to ensure that the necessary number
   of active connections exists.

   There are two ways that a peer is removed from the suspect peer list:

   1. The peer is no longer reachable, causing the transport connection
      to be shutdown.  The peer is moved to the closed state.

   2. Three watchdog messages are exchanged with accepted round trip
      times, and the connection to the peer is considered stabilized.

      In the event the peer being removed is either the primary or
      secondary, an alternate peer SHOULD replace the deleted peer, and
      assume the role of either primary or secondary.

5.2.  Diameter Peer Discovery

   Allowing for dynamic Diameter agent discovery will make it possible
   for simpler and more robust deployment of Diameter services.  In
   order to promote interoperable implementations of Diameter peer
   discovery, the following mechanisms are described.  These are based

Top      Up      ToC       Page 57 
   on existing IETF standards.  The first option (manual configuration)
   MUST be supported by all DIAMETER nodes, while the latter two options
   (SRVLOC and DNS) MAY be supported.

   There are two cases where Diameter peer discovery may be performed.
   The first is when a Diameter client needs to discover a first-hop
   Diameter agent.  The second case is when a Diameter agent needs to
   discover another agent - for further handling of a Diameter
   operation.  In both cases, the following 'search order' is
   recommended:

   1. The Diameter implementation consults its list of static (manually)
      configured Diameter agent locations.  These will be used if they
      exist and respond.

   2. The Diameter implementation uses SLPv2 [SLP] to discover Diameter
      services.  The Diameter service template [TEMPLATE] is included in
      Appendix A.

      It is recommended that SLPv2 security be deployed (this requires
      distributing keys to SLPv2 agents).  This is discussed further in
      Appendix A.  SLPv2 security SHOULD be used (requiring distribution
      of keys to SLPv2 agents) in order to ensure that discovered peers
      are authorized for their roles.  SLPv2 is discussed further in
      Appendix A.

   3. The Diameter implementation performs a NAPTR query for a server in
      a particular realm.  The Diameter implementation has to know in
      advance which realm to look for a Diameter agent in.  This could
      be deduced, for example, from the 'realm' in a NAI that a Diameter
      implementation needed to perform a Diameter operation on.

      3.1 The services relevant for the task of transport protocol
          selection are those with NAPTR service fields with values
          "AAA+D2x", where x is a letter that corresponds to a transport
          protocol supported by the domain.  This specification defines
          D2T for TCP and D2S for SCTP.  We also establish an IANA
          registry for NAPTR service name to transport protocol
          mappings.

          These NAPTR records provide a mapping from a domain, to the
          SRV record for contacting a server with the specific transport
          protocol in the NAPTR services field.  The resource record
          will contain an empty regular expression and a replacement
          value, which is the SRV record for that particular transport
          protocol.  If the server supports multiple transport
          protocols, there will be multiple NAPTR records, each with a
          different service value.  As per RFC 2915 [NAPTR], the client

Top      Up      ToC       Page 58 
          discards any records whose services fields are not applicable.
          For the purposes of this specification, several rules are
          defined.

      3.2 A client MUST discard any service fields that identify a
          resolution service whose value is not "D2X", for values of X
          that indicate transport protocols supported by the client.
          The NAPTR processing as described in RFC 2915 will result in
          discovery of the most preferred transport protocol of the
          server that is supported by the client, as well as an SRV
          record for the server.

          The domain suffixes in the NAPTR replacement field SHOULD
          match the domain of the original query.

   4. If no NAPTR records are found, the requester queries for those
      address records for the destination address,
      '_diameter._sctp'.realm or '_diameter._tcp'.realm.  Address
      records include A RR's, AAAA RR's or other similar records, chosen
      according to the requestor's network protocol capabilities.  If
      the DNS server returns no address records, the requestor gives up.

      If the server is using a site certificate, the domain name in the
      query and the domain name in the replacement field MUST both be
      valid based on the site certificate handed out by the server in
      the TLS or IKE exchange.  Similarly, the domain name in the SRV
      query and the domain name in the target in the SRV record MUST
      both be valid based on the same site certificate.  Otherwise, an
      attacker could modify the DNS records to contain replacement
      values in a different domain, and the client could not validate
      that this was the desired behavior, or the result of an attack

      Also, the Diameter Peer MUST check to make sure that the
      discovered peers are authorized to act in its role.
      Authentication via IKE or TLS, or validation of DNS RRs via DNSSEC
      is not sufficient to conclude this.  For example, a web server may
      have obtained a valid TLS certificate, and secured RRs may be
      included in the DNS, but this does not imply that it is authorized
      to act as a Diameter Server.

      Authorization can be achieved for example, by configuration of a
      Diameter Server CA.  Alternatively this can be achieved by
      definition of OIDs within TLS or IKE certificates so as to signify
      Diameter Server authorization.

   A dynamically discovered peer causes an entry in the Peer Table (see
   Section 2.6) to be created.  Note that entries created via DNS MUST
   expire (or be refreshed) within the DNS TTL.  If a peer is discovered

Top      Up      ToC       Page 59 
   outside of the local realm, a routing table entry (see Section 2.7)
   for the peer's realm is created.  The routing table entry's
   expiration MUST match the peer's expiration value.

5.3.  Capabilities Exchange

   When two Diameter peers establish a transport connection, they MUST
   exchange the Capabilities Exchange messages, as specified in the peer
   state machine (see Section 5.6).  This message allows the discovery
   of a peer's identity and its capabilities (protocol version number,
   supported Diameter applications, security mechanisms, etc.)

   The receiver only issues commands to its peers that have advertised
   support for the Diameter application that defines the command.  A
   Diameter node MUST cache the supported applications in order to
   ensure that unrecognized commands and/or AVPs are not unnecessarily
   sent to a peer.

   A receiver of a Capabilities-Exchange-Req (CER) message that does not
   have any applications in common with the sender MUST return a
   Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to
   DIAMETER_NO_COMMON_APPLICATION, and SHOULD disconnect the transport
   layer connection.  Note that receiving a CER or CEA from a peer
   advertising itself as a Relay (see Section 2.4) MUST be interpreted
   as having common applications with the peer.

   Similarly, a receiver of a Capabilities-Exchange-Req (CER) message
   that does not have any security mechanisms in common with the sender
   MUST return a Capabilities-Exchange-Answer (CEA) with the Result-Code
   AVP set to DIAMETER_NO_COMMON_SECURITY, and SHOULD disconnect the
   transport layer connection.

   CERs received from unknown peers MAY be silently discarded, or a CEA
   MAY be issued with the Result-Code AVP set to DIAMETER_UNKNOWN_PEER.
   In both cases, the transport connection is closed.  If the local
   policy permits receiving CERs from unknown hosts, a successful CEA
   MAY be returned.  If a CER from an unknown peer is answered with a
   successful CEA, the lifetime of the peer entry is equal to the
   lifetime of the transport connection.  In case of a transport
   failure, all the pending transactions destined to the unknown peer
   can be discarded.

   The CER and CEA messages MUST NOT be proxied, redirected or relayed.

   Since the CER/CEA messages cannot be proxied, it is still possible
   that an upstream agent receives a message for which it has no
   available peers to handle the application that corresponds to the
   Command-Code.  In such instances, the 'E' bit is set in the answer

Top      Up      ToC       Page 60 
   message (see Section 7.) with the Result-Code AVP set to
   DIAMETER_UNABLE_TO_DELIVER to inform the downstream to take action
   (e.g., re-routing request to an alternate peer).

   With the exception of the Capabilities-Exchange-Request message, a
   message of type Request that includes the Auth-Application-Id or
   Acct-Application-Id AVPs, or a message with an application-specific
   command code, MAY only be forwarded to a host that has explicitly
   advertised support for the application (or has advertised the Relay
   Application Identifier).

5.3.1.  Capabilities-Exchange-Request

   The Capabilities-Exchange-Request (CER), indicated by the Command-
   Code set to 257 and the Command Flags' 'R' bit set, is sent to
   exchange local capabilities.  Upon detection of a transport failure,
   this message MUST NOT be sent to an alternate peer.

   When Diameter is run over SCTP [SCTP], which allows for connections
   to span multiple interfaces and multiple IP addresses, the
   Capabilities-Exchange-Request message MUST contain one Host-IP-
   Address AVP for each potential IP address that MAY be locally used
   when transmitting Diameter messages.

   Message Format

      <CER> ::= < Diameter Header: 257, REQ >
                { Origin-Host }
                { Origin-Realm }
             1* { Host-IP-Address }
                { Vendor-Id }
                { Product-Name }
                [ Origin-State-Id ]
              * [ Supported-Vendor-Id ]
              * [ Auth-Application-Id ]
              * [ Inband-Security-Id ]
              * [ Acct-Application-Id ]
              * [ Vendor-Specific-Application-Id ]
                [ Firmware-Revision ]
              * [ AVP ]

5.3.2.  Capabilities-Exchange-Answer

   The Capabilities-Exchange-Answer (CEA), indicated by the Command-Code
   set to 257 and the Command Flags' 'R' bit cleared, is sent in
   response to a CER message.

Top      Up      ToC       Page 61 
   When Diameter is run over SCTP [SCTP], which allows connections to
   span multiple interfaces, hence, multiple IP addresses, the
   Capabilities-Exchange-Answer message MUST contain one Host-IP-Address
   AVP for each potential IP address that MAY be locally used when
   transmitting Diameter messages.

   Message Format

      <CEA> ::= < Diameter Header: 257 >
                { Result-Code }
                { Origin-Host }
                { Origin-Realm }
             1* { Host-IP-Address }
                { Vendor-Id }
                { Product-Name }
                [ Origin-State-Id ]
                [ Error-Message ]
              * [ Failed-AVP ]
              * [ Supported-Vendor-Id ]
              * [ Auth-Application-Id ]
              * [ Inband-Security-Id ]
              * [ Acct-Application-Id ]
              * [ Vendor-Specific-Application-Id ]
                [ Firmware-Revision ]
              * [ AVP ]

5.3.3.  Vendor-Id AVP

   The Vendor-Id AVP (AVP Code 266) is of type Unsigned32 and contains
   the IANA "SMI Network Management Private Enterprise Codes" [ASSIGNNO]
   value assigned to the vendor of the Diameter application.  In
   combination with the Supported-Vendor-Id AVP (Section 5.3.6), this
   MAY be used in order to know which vendor specific attributes may be
   sent to the peer.  It is also envisioned that the combination of the
   Vendor-Id, Product-Name (Section 5.3.7) and the Firmware-Revision
   (Section 5.3.4) AVPs MAY provide very useful debugging information.

   A Vendor-Id value of zero in the CER or CEA messages is reserved and
   indicates that this field is ignored.

5.3.4.  Firmware-Revision AVP

   The Firmware-Revision AVP (AVP Code 267) is of type Unsigned32 and is
   used to inform a Diameter peer of the firmware revision of the
   issuing device.

Top      Up      ToC       Page 62 
   For devices that do not have a firmware revision (general purpose
   computers running Diameter software modules, for instance), the
   revision of the Diameter software module may be reported instead.

5.3.5.  Host-IP-Address AVP

   The Host-IP-Address AVP (AVP Code 257) is of type Address and is used
   to inform a Diameter peer of the sender's IP address.  All source
   addresses that a Diameter node expects to use with SCTP [SCTP] MUST
   be advertised in the CER and CEA messages by including a Host-IP-
   Address AVP for each address.  This AVP MUST ONLY be used in the CER
   and CEA messages.

5.3.6.  Supported-Vendor-Id AVP

   The Supported-Vendor-Id AVP (AVP Code 265) is of type Unsigned32 and
   contains the IANA "SMI Network Management Private Enterprise Codes"
   [ASSIGNNO] value assigned to a vendor other than the device vendor.
   This is used in the CER and CEA messages in order to inform the peer
   that the sender supports (a subset of) the vendor-specific AVPs
   defined by the vendor identified in this AVP.

5.3.7.  Product-Name AVP

   The Product-Name AVP (AVP Code 269) is of type UTF8String, and
   contains the vendor assigned name for the product.  The Product-Name
   AVP SHOULD remain constant across firmware revisions for the same
   product.

5.4.  Disconnecting Peer connections

   When a Diameter node disconnects one of its transport connections,
   its peer cannot know the reason for the disconnect, and will most
   likely assume that a connectivity problem occurred, or that the peer
   has rebooted.  In these cases, the peer may periodically attempt to
   reconnect, as stated in Section 2.1.  In the event that the
   disconnect was a result of either a shortage of internal resources,
   or simply that the node in question has no intentions of forwarding
   any Diameter messages to the peer in the foreseeable future, a
   periodic connection request would not be welcomed.  The
   Disconnection-Reason AVP contains the reason the Diameter node issued
   the Disconnect-Peer-Request message.

   The Disconnect-Peer-Request message is used by a Diameter node to
   inform its peer of its intent to disconnect the transport layer, and
   that the peer shouldn't reconnect unless it has a valid reason to do
   so (e.g., message to be forwarded).  Upon receipt of the message, the

Top      Up      ToC       Page 63 
   Disconnect-Peer-Answer is returned, which SHOULD contain an error if
   messages have recently been forwarded, and are likely in flight,
   which would otherwise cause a race condition.

   The receiver of the Disconnect-Peer-Answer initiates the transport
   disconnect.

5.4.1.  Disconnect-Peer-Request

   The Disconnect-Peer-Request (DPR), indicated by the Command-Code set
   to 282 and the Command Flags' 'R' bit set, is sent to a peer to
   inform its intentions to shutdown the transport connection.  Upon
   detection of a transport failure, this message MUST NOT be sent to an
   alternate peer.

   Message Format

      <DPR>  ::= < Diameter Header: 282, REQ >
                 { Origin-Host }
                 { Origin-Realm }
                 { Disconnect-Cause }

5.4.2.  Disconnect-Peer-Answer

   The Disconnect-Peer-Answer (DPA), indicated by the Command-Code set
   to 282 and the Command Flags' 'R' bit cleared, is sent as a response
   to the Disconnect-Peer-Request message.  Upon receipt of this
   message, the transport connection is shutdown.

   Message Format

      <DPA>  ::= < Diameter Header: 282 >
                 { Result-Code }
                 { Origin-Host }
                 { Origin-Realm }
                 [ Error-Message ]
               * [ Failed-AVP ]

5.4.3.  Disconnect-Cause AVP

   The Disconnect-Cause AVP (AVP Code 273) is of type Enumerated.  A
   Diameter node MUST include this AVP in the Disconnect-Peer-Request
   message to inform the peer of the reason for its intention to
   shutdown the transport connection.  The following values are
   supported:

Top      Up      ToC       Page 64 
   REBOOTING                         0
      A scheduled reboot is imminent.

   BUSY                              1
      The peer's internal resources are constrained, and it has
      determined that the transport connection needs to be closed.

   DO_NOT_WANT_TO_TALK_TO_YOU        2
      The peer has determined that it does not see a need for the
      transport connection to exist, since it does not expect any
      messages to be exchanged in the near future.

5.5.  Transport Failure Detection

   Given the nature of the Diameter protocol, it is recommended that
   transport failures be detected as soon as possible.  Detecting such
   failures will minimize the occurrence of messages sent to unavailable
   agents, resulting in unnecessary delays, and will provide better
   failover performance.  The Device-Watchdog-Request and Device-
   Watchdog-Answer messages, defined in this section, are used to pro-
   actively detect transport failures.

5.5.1.  Device-Watchdog-Request

   The Device-Watchdog-Request (DWR), indicated by the Command-Code set
   to 280 and the Command Flags' 'R' bit set, is sent to a peer when no
   traffic has been exchanged between two peers (see Section 5.5.3).
   Upon detection of a transport failure, this message MUST NOT be sent
   to an alternate peer.

   Message Format

      <DWR>  ::= < Diameter Header: 280, REQ >
                 { Origin-Host }
                 { Origin-Realm }
                 [ Origin-State-Id ]

5.5.2.  Device-Watchdog-Answer

   The Device-Watchdog-Answer (DWA), indicated by the Command-Code set
   to 280 and the Command Flags' 'R' bit cleared, is sent as a response
   to the Device-Watchdog-Request message.

Top      Up      ToC       Page 65 
   Message Format

      <DWA>  ::= < Diameter Header: 280 >
                 { Result-Code }
                 { Origin-Host }
                 { Origin-Realm }
                 [ Error-Message ]
               * [ Failed-AVP ]
                 [ Original-State-Id ]

5.5.3.  Transport Failure Algorithm

   The transport failure algorithm is defined in [AAATRANS].  All
   Diameter implementations MUST support the algorithm defined in the
   specification in order to be compliant to the Diameter base protocol.

5.5.4.  Failover and Failback Procedures

   In the event that a transport failure is detected with a peer, it is
   necessary for all pending request messages to be forwarded to an
   alternate agent, if possible.  This is commonly referred to as
   failover.

   In order for a Diameter node to perform failover procedures, it is
   necessary for the node to maintain a pending message queue for a
   given peer.  When an answer message is received, the corresponding
   request is removed from the queue.  The Hop-by-Hop Identifier field
   is used to match the answer with the queued request.

   When a transport failure is detected, if possible all messages in the
   queue are sent to an alternate agent with the T flag set.  On booting
   a Diameter client or agent, the T flag is also set on any records
   still remaining to be transmitted in non-volatile storage.  An
   example of a case where it is not possible to forward the message to
   an alternate server is when the message has a fixed destination, and
   the unavailable peer is the message's final destination (see
   Destination-Host AVP).  Such an error requires that the agent return
   an answer message with the 'E' bit set and the Result-Code AVP set to
   DIAMETER_UNABLE_TO_DELIVER.

   It is important to note that multiple identical requests or answers
   MAY be received as a result of a failover.  The End-to-End Identifier
   field in the Diameter header along with the Origin-Host AVP MUST be
   used to identify duplicate messages.

Top      Up      ToC       Page 66 
   As described in Section 2.1, a connection request should be
   periodically attempted with the failed peer in order to re-establish
   the transport connection.  Once a connection has been successfully
   established, messages can once again be forwarded to the peer.  This
   is commonly referred to as failback.

5.6.  Peer State Machine

   This section contains a finite state machine that MUST be observed by
   all Diameter implementations.  Each Diameter node MUST follow the
   state machine described below when communicating with each peer.
   Multiple actions are separated by commas, and may continue on
   succeeding lines, as space requires.  Similarly, state and next state
   may also span multiple lines, as space requires.

   This state machine is closely coupled with the state machine
   described in [AAATRANS], which is used to open, close, failover,
   probe, and reopen transport connections.  Note in particular that
   [AAATRANS] requires the use of watchdog messages to probe
   connections.  For Diameter, DWR and DWA messages are to be used.

   I- is used to represent the initiator (connecting) connection, while
   the R- is used to represent the responder (listening) connection.
   The lack of a prefix indicates that the event or action is the same
   regardless of the connection on which the event occurred.

   The stable states that a state machine may be in are Closed, I-Open
   and R-Open; all other states are intermediate.  Note that I-Open and
   R-Open are equivalent except for whether the initiator or responder
   transport connection is used for communication.

   A CER message is always sent on the initiating connection immediately
   after the connection request is successfully completed.  In the case
   of an election, one of the two connections will shut down.  The
   responder connection will survive if the Origin-Host of the local
   Diameter entity is higher than that of the peer; the initiator
   connection will survive if the peer's Origin-Host is higher.  All
   subsequent messages are sent on the surviving connection.  Note that
   the results of an election on one peer are guaranteed to be the
   inverse of the results on the other.

   For TLS usage, a TLS handshake will begin when both ends are in the
   open state.  If the TLS handshake is successful, all further messages
   will be sent via TLS.  If the handshake fails, both ends move to the
   closed state.

   The state machine constrains only the behavior of a Diameter
   implementation as seen by Diameter peers through events on the wire.

Top      Up      ToC       Page 67 
   Any implementation that produces equivalent results is considered
   compliant.

   state            event              action         next state
   -----------------------------------------------------------------
   Closed           Start            I-Snd-Conn-Req   Wait-Conn-Ack
                    R-Conn-CER       R-Accept,        R-Open
                                     Process-CER,
                                     R-Snd-CEA

   Wait-Conn-Ack    I-Rcv-Conn-Ack   I-Snd-CER        Wait-I-CEA
                    I-Rcv-Conn-Nack  Cleanup          Closed
                    R-Conn-CER       R-Accept,        Wait-Conn-Ack/
                                     Process-CER      Elect
                    Timeout          Error            Closed

   Wait-I-CEA       I-Rcv-CEA        Process-CEA      I-Open
                    R-Conn-CER       R-Accept,        Wait-Returns
                                     Process-CER,
                                     Elect
                    I-Peer-Disc      I-Disc           Closed
                    I-Rcv-Non-CEA    Error            Closed
                    Timeout          Error            Closed

   Wait-Conn-Ack/   I-Rcv-Conn-Ack   I-Snd-CER,Elect  Wait-Returns
   Elect            I-Rcv-Conn-Nack  R-Snd-CEA        R-Open
                    R-Peer-Disc      R-Disc           Wait-Conn-Ack
                    R-Conn-CER       R-Reject         Wait-Conn-Ack/
                                                      Elect
                    Timeout          Error            Closed

   Wait-Returns     Win-Election     I-Disc,R-Snd-CEA R-Open
                    I-Peer-Disc      I-Disc,          R-Open
                                     R-Snd-CEA
                    I-Rcv-CEA        R-Disc           I-Open
                    R-Peer-Disc      R-Disc           Wait-I-CEA
                    R-Conn-CER       R-Reject         Wait-Returns
                    Timeout          Error            Closed

   R-Open           Send-Message     R-Snd-Message    R-Open
                    R-Rcv-Message    Process          R-Open
                    R-Rcv-DWR        Process-DWR,     R-Open
                                     R-Snd-DWA
                    R-Rcv-DWA        Process-DWA      R-Open
                    R-Conn-CER       R-Reject         R-Open
                    Stop             R-Snd-DPR        Closing
                    R-Rcv-DPR        R-Snd-DPA,       Closed
                                           R-Disc

Top      Up      ToC       Page 68 
                    R-Peer-Disc      R-Disc           Closed
                    R-Rcv-CER        R-Snd-CEA        R-Open
                    R-Rcv-CEA        Process-CEA      R-Open

   I-Open           Send-Message     I-Snd-Message    I-Open
                    I-Rcv-Message    Process          I-Open
                    I-Rcv-DWR        Process-DWR,     I-Open
                                     I-Snd-DWA
                    I-Rcv-DWA        Process-DWA      I-Open
                    R-Conn-CER       R-Reject         I-Open
                    Stop             I-Snd-DPR        Closing
                    I-Rcv-DPR        I-Snd-DPA,       Closed
                                     I-Disc
                    I-Peer-Disc      I-Disc           Closed
                    I-Rcv-CER        I-Snd-CEA        I-Open
                    I-Rcv-CEA        Process-CEA      I-Open

   Closing          I-Rcv-DPA        I-Disc           Closed
                    R-Rcv-DPA        R-Disc           Closed
                    Timeout          Error            Closed
                    I-Peer-Disc      I-Disc           Closed
                    R-Peer-Disc      R-Disc           Closed

5.6.1.  Incoming connections

   When a connection request is received from a Diameter peer, it is
   not, in the general case, possible to know the identity of that peer
   until a CER is received from it.  This is because host and port
   determine the identity of a Diameter peer; and the source port of an
   incoming connection is arbitrary.  Upon receipt of CER, the identity
   of the connecting peer can be uniquely determined from Origin-Host.

   For this reason, a Diameter peer must employ logic separate from the
   state machine to receive connection requests, accept them, and await
   CER.  Once CER arrives on a new connection, the Origin-Host that
   identifies the peer is used to locate the state machine associated
   with that peer, and the new connection and CER are passed to the
   state machine as an R-Conn-CER event.

   The logic that handles incoming connections SHOULD close and discard
   the connection if any message other than CER arrives, or if an
   implementation-defined timeout occurs prior to receipt of CER.

   Because handling of incoming connections up to and including receipt
   of CER requires logic, separate from that of any individual state
   machine associated with a particular peer, it is described separately
   in this section rather than in the state machine above.

Top      Up      ToC       Page 69 
5.6.2.  Events

   Transitions and actions in the automaton are caused by events.  In
   this section, we will ignore the -I and -R prefix, since the actual
   event would be identical, but would occur on one of two possible
   connections.

   Start          The Diameter application has signaled that a
                  connection should be initiated with the peer.

   R-Conn-CER     An acknowledgement is received stating that the
                  transport connection has been established, and the
                  associated CER has arrived.

   Rcv-Conn-Ack   A positive acknowledgement is received confirming that
                  the transport connection is established.

   Rcv-Conn-Nack  A negative acknowledgement was received stating that
                  the transport connection was not established.

   Timeout        An application-defined timer has expired while waiting
                  for some event.

   Rcv-CER        A CER message from the peer was received.

   Rcv-CEA        A CEA message from the peer was received.

   Rcv-Non-CEA    A message other than CEA from the peer was received.

   Peer-Disc      A disconnection indication from the peer was received.

   Rcv-DPR        A DPR message from the peer was received.

   Rcv-DPA        A DPA message from the peer was received.

   Win-Election   An election was held, and the local node was the
                  winner.

   Send-Message   A message is to be sent.

   Rcv-Message    A message other than CER, CEA, DPR, DPA, DWR or DWA
                  was received.

   Stop           The Diameter application has signaled that a
                  connection should be terminated (e.g., on system
                  shutdown).

Top      Up      ToC       Page 70 
5.6.3.  Actions

   Actions in the automaton are caused by events and typically indicate
   the transmission of packets and/or an action to be taken on the
   connection.  In this section we will ignore the I- and R-prefix,
   since the actual action would be identical, but would occur on one of
   two possible connections.

   Snd-Conn-Req   A transport connection is initiated with the peer.

   Accept         The incoming connection associated with the R-Conn-CER
                  is accepted as the responder connection.

   Reject         The incoming connection associated with the R-Conn-CER
                  is disconnected.

   Process-CER    The CER associated with the R-Conn-CER is processed.

   Snd-CER        A CER message is sent to the peer.

   Snd-CEA        A CEA message is sent to the peer.

   Cleanup        If necessary, the connection is shutdown, and any
                  local resources are freed.

   Error          The transport layer connection is disconnected, either
                  politely or abortively, in response to an error
                  condition.  Local resources are freed.

   Process-CEA    A received CEA is processed.

   Snd-DPR        A DPR message is sent to the peer.

   Snd-DPA        A DPA message is sent to the peer.

   Disc           The transport layer connection is disconnected, and
                  local resources are freed.

   Elect          An election occurs (see Section 5.6.4 for more
                  information).

   Snd-Message    A message is sent.

   Snd-DWR        A DWR message is sent.

   Snd-DWA        A DWA message is sent.

   Process-DWR    The DWR message is serviced.

Top      Up      ToC       Page 71 
   Process-DWA    The DWA message is serviced.

   Process        A message is serviced.

5.6.4.  The Election Process

   The election is performed on the responder.  The responder compares
   the Origin-Host received in the CER sent by its peer with its own
   Origin-Host.  If the local Diameter entity's Origin-Host is higher
   than the peer's, a Win-Election event is issued locally.

   The comparison proceeds by considering the shorter OctetString to be
   padded with zeros so that it length is the same as the length of the
   longer, then performing an octet-by-octet unsigned comparison with
   the first octet being most significant.  Any remaining octets are
   assumed to have value 0x80.

6.  Diameter message processing

   This section describes how Diameter requests and answers are created
   and processed.

6.1.  Diameter Request Routing Overview

   A request is sent towards its final destination using a combination
   of the Destination-Realm and Destination-Host AVPs, in one of these
   three combinations:

   -  a request that is not able to be proxied (such as CER) MUST NOT
      contain either Destination-Realm or Destination-Host AVPs.

   -  a request that needs to be sent to a home server serving a
      specific realm, but not to a specific server (such as the first
      request of a series of round-trips), MUST contain a Destination-
      Realm AVP, but MUST NOT contain a Destination-Host AVP.

   -  otherwise, a request that needs to be sent to a specific home
      server among those serving a given realm, MUST contain both the
      Destination-Realm and Destination-Host AVPs.

   The Destination-Host AVP is used as described above when the
   destination of the request is fixed, which includes:

   -  Authentication requests that span multiple round trips

   -  A Diameter message that uses a security mechanism that makes use
      of a pre-established session key shared between the source and the
      final destination of the message.

Top      Up      ToC       Page 72 
   -  Server initiated messages that MUST be received by a specific
      Diameter client (e.g., access device), such as the Abort-Session-
      Request message, which is used to request that a particular user's
      session be terminated.

   Note that an agent can forward a request to a host described in the
   Destination-Host AVP only if the host in question is included in its
   peer table (see Section 2.7).  Otherwise, the request is routed based
   on the Destination-Realm only (see Sections 6.1.6).

   The Destination-Realm AVP MUST be present if the message is
   proxiable.  Request messages that may be forwarded by Diameter agents
   (proxies, redirects or relays) MUST also contain an Acct-
   Application-Id AVP, an Auth-Application-Id AVP or a Vendor-Specific-
   Application-Id AVP.  A message that MUST NOT be forwarded by Diameter
   agents (proxies, redirects or relays) MUST not include the
   Destination-Realm in its ABNF.  The value of the Destination-Realm
   AVP MAY be extracted from the User-Name AVP, or other application-
   specific methods.

   When a message is received, the message is processed in the following
   order:

   1. If the message is destined for the local host, the procedures
      listed in Section 6.1.4 are followed.

   2. If the message is intended for a Diameter peer with whom the local
      host is able to directly communicate, the procedures listed in
      Section 6.1.5 are followed.  This is known as Request Forwarding.

   3. The procedures listed in Section 6.1.6 are followed, which is
      known as Request Routing.

   4. If none of the above is successful, an answer is returned with the
      Result-Code set to DIAMETER_UNABLE_TO_DELIVER, with the E-bit set.

   For routing of Diameter messages to work within an administrative
   domain, all Diameter nodes within the realm MUST be peers.

   Note the processing rules contained in this section are intended to
   be used as general guidelines to Diameter developers.  Certain
   implementations MAY use different methods than the ones described
   here, and still comply with the protocol specification.  See Section
   7 for more detail on error handling.

Top      Up      ToC       Page 73 
6.1.1.  Originating a Request

   When creating a request, in addition to any other procedures
   described in the application definition for that specific request,
   the following procedures MUST be followed:

   -  the Command-Code is set to the appropriate value

   -  the 'R' bit is set

   -  the End-to-End Identifier is set to a locally unique value

   -  the Origin-Host and Origin-Realm AVPs MUST be set to the
      appropriate values, used to identify the source of the message

   -  the Destination-Host and Destination-Realm AVPs MUST be set to the
      appropriate values as described in Section 6.1.

   -  an Acct-Application-Id AVP, an Auth-Application-Id or a Vendor-
      Specific-Application-Id AVP must be included if the request is
      proxiable.

6.1.2.  Sending a Request

   When sending a request, originated either locally, or as the result
   of a forwarding or routing operation, the following procedures MUST
   be followed:

   -  the Hop-by-Hop Identifier should be set to a locally unique value

   -  The message should be saved in the list of pending requests.

   Other actions to perform on the message based on the particular role
   the agent is playing are described in the following sections.

6.1.3.  Receiving Requests

   A relay or proxy agent MUST check for forwarding loops when receiving
   requests.  A loop is detected if the server finds its own identity in
   a Route-Record AVP.  When such an event occurs, the agent MUST answer
   with the Result-Code AVP set to DIAMETER_LOOP_DETECTED.

6.1.4.  Processing Local Requests

   A request is known to be for local consumption when one of the
   following conditions occur:

   -  The Destination-Host AVP contains the local host's identity,

Top      Up      ToC       Page 74 
   -  The Destination-Host AVP is not present, the Destination-Realm AVP
      contains a realm the server is configured to process locally, and
      the Diameter application is locally supported, or

   -  Both the Destination-Host and the Destination-Realm are not
      present.

   When a request is locally processed, the rules in Section 6.2 should
   be used to generate the corresponding answer.

6.1.5.  Request Forwarding

   Request forwarding is done using the Diameter Peer Table.  The
   Diameter peer table contains all of the peers that the local node is
   able to directly communicate with.

   When a request is received, and the host encoded in the Destination-
   Host AVP is one that is present in the peer table, the message SHOULD
   be forwarded to the peer.

6.1.6.  Request Routing

   Diameter request message routing is done via realms and applications.
   A Diameter message that may be forwarded by Diameter agents (proxies,
   redirects or relays) MUST include the target realm in the
   Destination-Realm AVP and one of the application identification AVPs
   Auth-Application-Id, Acct-Application-Id or Vendor-Specific-
   Application-Id.  The realm MAY be retrieved from the User-Name AVP,
   which is in the form of a Network Access Identifier (NAI).  The realm
   portion of the NAI is inserted in the Destination-Realm AVP.

   Diameter agents MAY have a list of locally supported realms and
   applications, and MAY have a list of externally supported realms and
   applications.  When a request is received that includes a realm
   and/or application that is not locally supported, the message is
   routed to the peer configured in the Realm Routing Table (see Section
   2.7).

6.1.7.  Redirecting requests

   When a redirect agent receives a request whose routing entry is set
   to REDIRECT, it MUST reply with an answer message with the 'E' bit
   set, while maintaining the Hop-by-Hop Identifier in the header, and
   include the Result-Code AVP to DIAMETER_REDIRECT_INDICATION.  Each of
   the servers associated with the routing entry are added in separate
   Redirect-Host AVP.

Top      Up      ToC       Page 75 
                  +------------------+
                  |     Diameter     |
                  |  Redirect Agent  |
                  +------------------+
                   ^    |    2. command + 'E' bit
    1. Request     |    |    Result-Code =
   joe@example.com |    |    DIAMETER_REDIRECT_INDICATION +
                   |    |    Redirect-Host AVP(s)
                   |    v
               +-------------+  3. Request  +-------------+
               | example.com |------------->| example.net |
               |    Relay    |              |   Diameter  |
               |    Agent    |<-------------|    Server   |
               +-------------+  4. Answer   +-------------+

                     Figure 5: Diameter Redirect Agent

   The receiver of the answer message with the 'E' bit set, and the
   Result-Code AVP set to DIAMETER_REDIRECT_INDICATION uses the hop-by-
   hop field in the Diameter header to identify the request in the
   pending message queue (see Section 5.3) that is to be redirected.  If
   no transport connection exists with the new agent, one is created,
   and the request is sent directly to it.

   Multiple Redirect-Host AVPs are allowed.  The receiver of the answer
   message with the 'E' bit set selects exactly one of these hosts as
   the destination of the redirected message.

6.1.8.  Relaying and Proxying Requests

   A relay or proxy agent MUST append a Route-Record AVP to all requests
   forwarded.  The AVP contains the identity of the peer the request was
   received from.

   The Hop-by-Hop identifier in the request is saved, and replaced with
   a locally unique value.  The source of the request is also saved,
   which includes the IP address, port and protocol.

   A relay or proxy agent MAY include the Proxy-Info AVP in requests if
   it requires access to any local state information when the
   corresponding response is received.  Proxy-Info AVP has certain
   security implications and SHOULD contain an embedded HMAC with a
   node-local key.  Alternatively, it MAY simply use local storage to
   store state information.

   The message is then forwarded to the next hop, as identified in the
   Realm Routing Table.

Top      Up      ToC       Page 76 
   Figure 6 provides an example of message routing using the procedures
   listed in these sections.

        (Origin-Host=nas.mno.net)    (Origin-Host=nas.mno.net)
        (Origin-Realm=mno.net)       (Origin-Realm=mno.net)
        (Destination-Realm=example.com)  (Destination-
                                         Realm=example.com)
                                     (Route-Record=nas.example.net)
    +------+      ------>      +------+      ------>      +------+
    |      |     (Request)     |      |      (Request)    |      |
    | NAS  +-------------------+ DRL  +-------------------+ HMS  |
    |      |                   |      |                   |      |
    +------+     <------       +------+     <------       +------+
   example.net    (Answer)   example.net     (Answer)   example.com
        (Origin-Host=hms.example.com)   (Origin-Host=hms.example.com)
        (Origin-Realm=example.com)      (Origin-Realm=example.com)

                  Figure 6: Routing of Diameter messages

6.2.  Diameter Answer Processing

   When a request is locally processed, the following procedures MUST be
   applied to create the associated answer, in addition to any
   additional procedures that MAY be discussed in the Diameter
   application defining the command:

   -  The same Hop-by-Hop identifier in the request is used in the
      answer.

   -  The local host's identity is encoded in the Origin-Host AVP.

   -  The Destination-Host and Destination-Realm AVPs MUST NOT be
      present in the answer message.

   -  The Result-Code AVP is added with its value indicating success or
      failure.

   -  If the Session-Id is present in the request, it MUST be included
      in the answer.

   -  Any Proxy-Info AVPs in the request MUST be added to the answer
      message, in the same order they were present in the request.

   -  The 'P' bit is set to the same value as the one in the request.

   -  The same End-to-End identifier in the request is used in the
      answer.

Top      Up      ToC       Page 77 
   Note that the error messages (see Section 7.3) are also subjected to
   the above processing rules.

6.2.1.  Processing received Answers

   A Diameter client or proxy MUST match the Hop-by-Hop Identifier in an
   answer received against the list of pending requests.  The
   corresponding message should be removed from the list of pending
   requests.  It SHOULD ignore answers received that do not match a
   known Hop-by-Hop Identifier.

6.2.2.  Relaying and Proxying Answers

   If the answer is for a request which was proxied or relayed, the
   agent MUST restore the original value of the Diameter header's Hop-
   by-Hop Identifier field.

   If the last Proxy-Info AVP in the message is targeted to the local
   Diameter server, the AVP MUST be removed before the answer is
   forwarded.

   If a relay or proxy agent receives an answer with a Result-Code AVP
   indicating a failure, it MUST NOT modify the contents of the AVP.
   Any additional local errors detected SHOULD be logged, but not
   reflected in the Result-Code AVP.  If the agent receives an answer
   message with a Result-Code AVP indicating success, and it wishes to
   modify the AVP to indicate an error, it MUST modify the Result-Code
   AVP to contain the appropriate error in the message destined towards
   the access device as well as include the Error-Reporting-Host AVP and
   it MUST issue an STR on behalf of the access device.

   The agent MUST then send the answer to the host that it received the
   original request from.

6.3.  Origin-Host AVP

   The Origin-Host AVP (AVP Code 264) is of type DiameterIdentity, and
   MUST be present in all Diameter messages.  This AVP identifies the
   endpoint that originated the Diameter message.  Relay agents MUST NOT
   modify this AVP.

   The value of the Origin-Host AVP is guaranteed to be unique within a
   single host.

   Note that the Origin-Host AVP may resolve to more than one address as
   the Diameter peer may support more than one address.

Top      Up      ToC       Page 78 
   This AVP SHOULD be placed as close to the Diameter header as
   possible. 6.10

6.4.  Origin-Realm AVP

   The Origin-Realm AVP (AVP Code 296) is of type DiameterIdentity.
   This AVP contains the Realm of the originator of any Diameter message
   and MUST be present in all messages.

   This AVP SHOULD be placed as close to the Diameter header as
   possible.

6.5.  Destination-Host AVP

   The Destination-Host AVP (AVP Code 293) is of type DiameterIdentity.
   This AVP MUST be present in all unsolicited agent initiated messages,
   MAY be present in request messages, and MUST NOT be present in Answer
   messages.

   The absence of the Destination-Host AVP will cause a message to be
   sent to any Diameter server supporting the application within the
   realm specified in Destination-Realm AVP.

   This AVP SHOULD be placed as close to the Diameter header as
   possible.

6.6.  Destination-Realm AVP

   The Destination-Realm AVP (AVP Code 283) is of type DiameterIdentity,
   and contains the realm the message is to be routed to.  The
   Destination-Realm AVP MUST NOT be present in Answer messages.
   Diameter Clients insert the realm portion of the User-Name AVP.
   Diameter servers initiating a request message use the value of the
   Origin-Realm AVP from a previous message received from the intended
   target host (unless it is known a priori).  When present, the
   Destination-Realm AVP is used to perform message routing decisions.

   Request messages whose ABNF does not list the Destination-Realm AVP
   as a mandatory AVP are inherently non-routable messages.

   This AVP SHOULD be placed as close to the Diameter header as
   possible.

6.7.  Routing AVPs

   The AVPs defined in this section are Diameter AVPs used for routing
   purposes.  These AVPs change as Diameter messages are processed by
   agents, and therefore MUST NOT be protected by end-to-end security.

Top      Up      ToC       Page 79 
6.7.1.  Route-Record AVP

   The Route-Record AVP (AVP Code 282) is of type DiameterIdentity.  The
   identity added in this AVP MUST be the same as the one received in
   the Origin-Host of the Capabilities Exchange message.

6.7.2.  Proxy-Info AVP

   The Proxy-Info AVP (AVP Code 284) is of type Grouped.  The Grouped
   Data field has the following ABNF grammar:

      Proxy-Info ::= < AVP Header: 284 >
                     { Proxy-Host }
                     { Proxy-State }
                   * [ AVP ]

6.7.3.  Proxy-Host AVP

   The Proxy-Host AVP (AVP Code 280) is of type DiameterIdentity.  This
   AVP contains the identity of the host that added the Proxy-Info AVP.

6.7.4.  Proxy-State AVP

   The Proxy-State AVP (AVP Code 33) is of type OctetString, and
   contains state local information, and MUST be treated as opaque data.

6.8.  Auth-Application-Id AVP

   The Auth-Application-Id AVP (AVP Code 258) is of type Unsigned32 and
   is used in order to advertise support of the Authentication and
   Authorization portion of an application (see Section 2.4).  The
   Auth-Application-Id MUST also be present in all Authentication and/or
   Authorization messages that are defined in a separate Diameter
   specification and have an Application ID assigned.

6.9.  Acct-Application-Id AVP

   The Acct-Application-Id AVP (AVP Code 259) is of type Unsigned32 and
   is used in order to advertise support of the Accounting portion of an
   application (see Section 2.4).  The Acct-Application-Id MUST also be
   present in all Accounting messages.  Exactly one of the Auth-
   Application-Id and Acct-Application-Id AVPs MAY be present.

6.10.  Inband-Security-Id AVP

   The Inband-Security-Id AVP (AVP Code 299) is of type Unsigned32 and
   is used in order to advertise support of the Security portion of the
   application.

Top      Up      ToC       Page 80 
   Currently, the following values are supported, but there is ample
   room to add new security Ids.

   NO_INBAND_SECURITY                0
      This peer does not support TLS.  This is the default value, if the
      AVP is omitted.

   TLS                               1
      This node supports TLS security, as defined by [TLS].

6.11.  Vendor-Specific-Application-Id AVP

   The Vendor-Specific-Application-Id AVP (AVP Code 260) is of type
   Grouped and is used to advertise support of a vendor-specific
   Diameter Application.  Exactly one of the Auth-Application-Id and
   Acct-Application-Id AVPs MAY be present.

   This AVP MUST also be present as the first AVP in all experimental
   commands defined in the vendor-specific application.

   This AVP SHOULD be placed as close to the Diameter header as
   possible.

   AVP Format

   <Vendor-Specific-Application-Id> ::= < AVP Header: 260 >
                                     1* [ Vendor-Id ]
                                     0*1{ Auth-Application-Id }
                                     0*1{ Acct-Application-Id }

6.12.  Redirect-Host AVP

   One or more of instances of this AVP MUST be present if the answer
   message's 'E' bit is set and the Result-Code AVP is set to
   DIAMETER_REDIRECT_INDICATION.

   Upon receiving the above, the receiving Diameter node SHOULD forward
   the request directly to one of the hosts identified in these AVPs.
   The server contained in the selected Redirect-Host AVP SHOULD be used
   for all messages pertaining to this session.

6.13.  Redirect-Host-Usage AVP

   The Redirect-Host-Usage AVP (AVP Code 261) is of type Enumerated.
   This AVP MAY be present in answer messages whose 'E' bit is set and
   the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION.

Top      Up      ToC       Page 81 
   When present, this AVP dictates how the routing entry resulting from
   the Redirect-Host is to be used.  The following values are supported:

   DONT_CACHE                        0
      The host specified in the Redirect-Host AVP should not be cached.
      This is the default value.

   ALL_SESSION                       1
      All messages within the same session, as defined by the same value
      of the Session-ID AVP MAY be sent to the host specified in the
      Redirect-Host AVP.

   ALL_REALM                         2
      All messages destined for the realm requested MAY be sent to the
      host specified in the Redirect-Host AVP.

   REALM_AND_APPLICATION             3
      All messages for the application requested to the realm specified
      MAY be sent to the host specified in the Redirect-Host AVP.

   ALL_APPLICATION                   4
      All messages for the application requested MAY be sent to the host
      specified in the Redirect-Host AVP.

   ALL_HOST                          5
      All messages that would be sent to the host that generated the
      Redirect-Host MAY be sent to the host specified in the Redirect-
      Host AVP.

   ALL_USER                          6
      All messages for the user requested MAY be sent to the host
      specified in the Redirect-Host AVP.

6.14.  Redirect-Max-Cache-Time AVP

   The Redirect-Max-Cache-Time AVP (AVP Code 262) is of type Unsigned32.
   This AVP MUST be present in answer messages whose 'E' bit is set, the
   Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION and the
   Redirect-Host-Usage AVP set to a non-zero value.

   This AVP contains the maximum number of seconds the peer and route
   table entries, created as a result of the Redirect-Host, will be
   cached.  Note that once a host created due to a redirect indication
   is no longer reachable, any associated peer and routing table entries
   MUST be deleted.

Top      Up      ToC       Page 82 
6.15.  E2E-Sequence AVP

   The E2E-Sequence AVP (AVP Code 300) provides anti-replay protection
   for end to end messages and is of type grouped.  It contains a random
   value (an OctetString with a nonce) and counter (an Integer).  For
   each end-to-end peer with which a node communicates (or remembers
   communicating) a different nonce value MUST be used and the counter
   is initiated at zero and increases by one each time this AVP is
   emitted to that peer.  This AVP MUST be included in all messages
   which use end-to-end protection (e.g., CMS signing or encryption).

7.  Error Handling

   There are two different types of errors in Diameter; protocol and
   application errors.  A protocol error is one that occurs at the base
   protocol level, and MAY require per hop attention (e.g., message
   routing error).  Application errors, on the other hand, generally
   occur due to a problem with a function specified in a Diameter
   application (e.g., user authentication, Missing AVP).

   Result-Code AVP values that are used to report protocol errors MUST
   only be present in answer messages whose 'E' bit is set.  When a
   request message is received that causes a protocol error, an answer
   message is returned with the 'E' bit set, and the Result-Code AVP is
   set to the appropriate protocol error value.  As the answer is sent
   back towards the originator of the request, each proxy or relay agent
   MAY take action on the message.

                          1. Request        +---------+ Link Broken
                +-------------------------->|Diameter |----///----+
                |     +---------------------|         |           v
         +------+--+  | 2. answer + 'E' set | Relay 2 |     +--------+
         |Diameter |<-+ (Unable to Forward) +---------+     |Diameter|
         |         |                                        |  Home  |
         | Relay 1 |--+                     +---------+     | Server |
         +---------+  |   3. Request        |Diameter |     +--------+
                      +-------------------->|         |           ^
                                            | Relay 3 |-----------+
                                            +---------+

           Figure 7:  Example of Protocol Error causing answer message

   Figure 7 provides an example of a message forwarded upstream by a
   Diameter relay.  When the message is received by Relay 2, and it
   detects that it cannot forward the request to the home server, an
   answer message is returned with the 'E' bit set and the Result-Code
   AVP set to DIAMETER_UNABLE_TO_DELIVER.  Given that this error falls

Top      Up      ToC       Page 83 
   within the protocol error category, Relay 1 would take special
   action, and given the error, attempt to route the message through its
   alternate Relay 3.

         +---------+ 1. Request  +---------+ 2. Request  +---------+
         | Access  |------------>|Diameter |------------>|Diameter |
         |         |             |         |             |  Home   |
         | Device  |<------------|  Relay  |<------------| Server  |
         +---------+  4. Answer  +---------+  3. Answer  +---------+
                    (Missing AVP)           (Missing AVP)

              Figure 8: Example of Application Error Answer message

   Figure 8 provides an example of a Diameter message that caused an
   application error.  When application errors occur, the Diameter
   entity reporting the error clears the 'R' bit in the Command Flags,
   and adds the Result-Code AVP with the proper value.  Application
   errors do not require any proxy or relay agent involvement, and
   therefore the message would be forwarded back to the originator of
   the request.

   There are certain Result-Code AVP application errors that require
   additional AVPs to be present in the answer.  In these cases, the
   Diameter node that sets the Result-Code AVP to indicate the error
   MUST add the AVPs.  Examples are:

   -  An unrecognized AVP is received with the 'M' bit (Mandatory bit)
      set, causes an answer to be sent with the Result-Code AVP set to
      DIAMETER_AVP_UNSUPPORTED, and the Failed-AVP AVP containing the
      offending AVP.

   -  An AVP that is received with an unrecognized value causes an
      answer to be returned with the Result-Code AVP set to
      DIAMETER_INVALID_AVP_VALUE, with the Failed-AVP AVP containing the
      AVP causing the error.

   -  A command is received with an AVP that is omitted, yet is
      mandatory according to the command's ABNF.  The receiver issues an
      answer with the Result-Code set to DIAMETER_MISSING_AVP, and
      creates an AVP with the AVP Code and other fields set as expected
      in the missing AVP.  The created AVP is then added to the Failed-
      AVP AVP.

   The Result-Code AVP describes the error that the Diameter node
   encountered in its processing.  In case there are multiple errors,
   the Diameter node MUST report only the first error it encountered

Top      Up      ToC       Page 84 
   (detected possibly in some implementation dependent order).  The
   specific errors that can be described by this AVP are described in
   the following section.

7.1.  Result-Code AVP

   The Result-Code AVP (AVP Code 268) is of type Unsigned32 and
   indicates whether a particular request was completed successfully or
   whether an error occurred.  All Diameter answer messages defined in
   IETF applications MUST include one Result-Code AVP.  A non-successful
   Result-Code AVP (one containing a non 2xxx value other than
   DIAMETER_REDIRECT_INDICATION) MUST include the Error-Reporting-Host
   AVP if the host setting the Result-Code AVP is different from the
   identity encoded in the Origin-Host AVP.

   The Result-Code data field contains an IANA-managed 32-bit address
   space representing errors (see Section 11.4).  Diameter provides the
   following classes of errors, all identified by the thousands digit in
   the decimal notation:

      -  1xxx (Informational)
      -  2xxx (Success)
      -  3xxx (Protocol Errors)
      -  4xxx (Transient Failures)
      -  5xxx (Permanent Failure)

   A non-recognized class (one whose first digit is not defined in this
   section) MUST be handled as a permanent failure.

7.1.1.  Informational

   Errors that fall within this category are used to inform the
   requester that a request could not be satisfied, and additional
   action is required on its part before access is granted.

   DIAMETER_MULTI_ROUND_AUTH         1001
      This informational error is returned by a Diameter server to
      inform the access device that the authentication mechanism being
      used requires multiple round trips, and a subsequent request needs
      to be issued in order for access to be granted.

7.1.2.  Success

   Errors that fall within the Success category are used to inform a
   peer that a request has been successfully completed.

   DIAMETER_SUCCESS                   2001
      The Request was successfully completed.

Top      Up      ToC       Page 85 
   DIAMETER_LIMITED_SUCCESS           2002
      When returned, the request was successfully completed, but
      additional processing is required by the application in order to
      provide service to the user.

7.1.3.  Protocol Errors

   Errors that fall within the Protocol Error category SHOULD be treated
   on a per-hop basis, and Diameter proxies MAY attempt to correct the
   error, if it is possible.  Note that these and only these errors MUST
   only be used in answer messages whose 'E' bit is set.

   DIAMETER_COMMAND_UNSUPPORTED       3001
      The Request contained a Command-Code that the receiver did not
      recognize or support.  This MUST be used when a Diameter node
      receives an experimental command that it does not understand.

   DIAMETER_UNABLE_TO_DELIVER         3002
      This error is given when Diameter can not deliver the message to
      the destination, either because no host within the realm
      supporting the required application was available to process the
      request, or because Destination-Host AVP was given without the
      associated Destination-Realm AVP.

   DIAMETER_REALM_NOT_SERVED          3003
      The intended realm of the request is not recognized.

   DIAMETER_TOO_BUSY                  3004
      When returned, a Diameter node SHOULD attempt to send the message
      to an alternate peer.  This error MUST only be used when a
      specific server is requested, and it cannot provide the requested
      service.

   DIAMETER_LOOP_DETECTED             3005
      An agent detected a loop while trying to get the message to the
      intended recipient.  The message MAY be sent to an alternate peer,
      if one is available, but the peer reporting the error has
      identified a configuration problem.

   DIAMETER_REDIRECT_INDICATION       3006
      A redirect agent has determined that the request could not be
      satisfied locally and the initiator of the request should direct
      the request directly to the server, whose contact information has
      been added to the response.  When set, the Redirect-Host AVP MUST
      be present.

   DIAMETER_APPLICATION_UNSUPPORTED   3007
      A request was sent for an application that is not supported.

Top      Up      ToC       Page 86 
   DIAMETER_INVALID_HDR_BITS          3008
      A request was received whose bits in the Diameter header were
      either set to an invalid combination, or to a value that is
      inconsistent with the command code's definition.

   DIAMETER_INVALID_AVP_BITS          3009
      A request was received that included an AVP whose flag bits are
      set to an unrecognized value, or that is inconsistent with the
      AVP's definition.

   DIAMETER_UNKNOWN_PEER              3010
      A CER was received from an unknown peer.

7.1.4.  Transient Failures

      Errors that fall within the transient failures category are used
      to inform a peer that the request could not be satisfied at the
      time it was received, but MAY be able to satisfy the request in
      the future.

   DIAMETER_AUTHENTICATION_REJECTED   4001
      The authentication process for the user failed, most likely due to
      an invalid password used by the user.  Further attempts MUST only
      be tried after prompting the user for a new password.

   DIAMETER_OUT_OF_SPACE              4002
      A Diameter node received the accounting request but was unable to
      commit it to stable storage due to a temporary lack of space.

   ELECTION_LOST                      4003
      The peer has determined that it has lost the election process and
      has therefore disconnected the transport connection.

7.1.5.  Permanent Failures

      Errors that fall within the permanent failures category are used
      to inform the peer that the request failed, and should not be
      attempted again.

   DIAMETER_AVP_UNSUPPORTED           5001
      The peer received a message that contained an AVP that is not
      recognized or supported and was marked with the Mandatory bit.  A
      Diameter message with this error MUST contain one or more Failed-
      AVP AVP containing the AVPs that caused the failure.

   DIAMETER_UNKNOWN_SESSION_ID        5002
      The request contained an unknown Session-Id.

Top      Up      ToC       Page 87 
   DIAMETER_AUTHORIZATION_REJECTED    5003
      A request was received for which the user could not be authorized.
      This error could occur if the service requested is not permitted
      to the user.

   DIAMETER_INVALID_AVP_VALUE         5004
      The request contained an AVP with an invalid value in its data
      portion.  A Diameter message indicating this error MUST include
      the offending AVPs within a Failed-AVP AVP.

   DIAMETER_MISSING_AVP               5005
      The request did not contain an AVP that is required by the Command
      Code definition.  If this value is sent in the Result-Code AVP, a
      Failed-AVP AVP SHOULD be included in the message.  The Failed-AVP
      AVP MUST contain an example of the missing AVP complete with the
      Vendor-Id if applicable.  The value field of the missing AVP
      should be of correct minimum length and contain zeroes.

   DIAMETER_RESOURCES_EXCEEDED        5006
      A request was received that cannot be authorized because the user
      has already expended allowed resources.  An example of this error
      condition is a user that is restricted to one dial-up PPP port,
      attempts to establish a second PPP connection.

   DIAMETER_CONTRADICTING_AVPS        5007
      The Home Diameter server has detected AVPs in the request that
      contradicted each other, and is not willing to provide service to
      the user.  One or more Failed-AVP AVPs MUST be present, containing
      the AVPs that contradicted each other.

   DIAMETER_AVP_NOT_ALLOWED           5008
      A message was received with an AVP that MUST NOT be present.  The
      Failed-AVP AVP MUST be included and contain a copy of the
      offending AVP.

   DIAMETER_AVP_OCCURS_TOO_MANY_TIMES 5009
      A message was received that included an AVP that appeared more
      often than permitted in the message definition.  The Failed-AVP
      AVP MUST be included and contain a copy of the first instance of
      the offending AVP that exceeded the maximum number of occurrences

   DIAMETER_NO_COMMON_APPLICATION     5010
      This error is returned when a CER message is received, and there
      are no common applications supported between the peers.

   DIAMETER_UNSUPPORTED_VERSION       5011
      This error is returned when a request was received, whose version
      number is unsupported.

Top      Up      ToC       Page 88 
   DIAMETER_UNABLE_TO_COMPLY          5012
      This error is returned when a request is rejected for unspecified
      reasons.

   DIAMETER_INVALID_BIT_IN_HEADER     5013
      This error is returned when an unrecognized bit in the Diameter
      header is set to one (1).

   DIAMETER_INVALID_AVP_LENGTH        5014
      The request contained an AVP with an invalid length.  A Diameter
      message indicating this error MUST include the offending AVPs
      within a Failed-AVP AVP.

   DIAMETER_INVALID_MESSAGE_LENGTH    5015
      This error is returned when a request is received with an invalid
      message length.

   DIAMETER_INVALID_AVP_BIT_COMBO     5016
      The request contained an AVP with which is not allowed to have the
      given value in the AVP Flags field.  A Diameter message indicating
      this error MUST include the offending AVPs within a Failed-AVP
      AVP.

   DIAMETER_NO_COMMON_SECURITY        5017
      This error is returned when a CER message is received, and there
      are no common security mechanisms supported between the peers.  A
      Capabilities-Exchange-Answer (CEA) MUST be returned with the
      Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY.

7.2.  Error Bit

   The 'E' (Error Bit) in the Diameter header is set when the request
   caused a protocol-related error (see Section 7.1.3).  A message with
   the 'E' bit MUST NOT be sent as a response to an answer message.
   Note that a message with the 'E' bit set is still subjected to the
   processing rules defined in Section 6.2.  When set, the answer
   message will not conform to the ABNF specification for the command,
   and will instead conform to the following ABNF:

Top      Up      ToC       Page 89 
   Message Format

   <answer-message> ::= < Diameter Header: code, ERR [PXY] >
                     0*1< Session-Id >
                        { Origin-Host }
                        { Origin-Realm }
                        { Result-Code }
                        [ Origin-State-Id ]
                        [ Error-Reporting-Host ]
                        [ Proxy-Info ]
                      * [ AVP ]

   Note that the code used in the header is the same than the one found
   in the request message, but with the 'R' bit cleared and the 'E' bit
   set.  The 'P' bit in the header is set to the same value as the one
   found in the request message.

7.3.  Error-Message AVP

   The Error-Message AVP (AVP Code 281) is of type UTF8String.  It MAY
   accompany a Result-Code AVP as a human readable error message.  The
   Error-Message AVP is not intended to be useful in real-time, and
   SHOULD NOT be expected to be parsed by network entities.

7.4.  Error-Reporting-Host AVP

   The Error-Reporting-Host AVP (AVP Code 294) is of type
   DiameterIdentity.  This AVP contains the identity of the Diameter
   host that sent the Result-Code AVP to a value other than 2001
   (Success), only if the host setting the Result-Code is different from
   the one encoded in the Origin-Host AVP.  This AVP is intended to be
   used for troubleshooting purposes, and MUST be set when the Result-
   Code AVP indicates a failure.

7.5.  Failed-AVP AVP

   The Failed-AVP AVP (AVP Code 279) is of type Grouped and provides
   debugging information in cases where a request is rejected or not
   fully processed due to erroneous information in a specific AVP.  The
   value of the Result-Code AVP will provide information on the reason
   for the Failed-AVP AVP.

   The possible reasons for this AVP are the presence of an improperly
   constructed AVP, an unsupported or unrecognized AVP, an invalid AVP
   value, the omission of a required AVP, the presence of an explicitly
   excluded AVP (see tables in Section 10), or the presence of two or
   more occurrences of an AVP which is restricted to 0, 1, or 0-1
   occurrences.

Top      Up      ToC       Page 90 
   A Diameter message MAY contain one Failed-AVP AVP, containing the
   entire AVP that could not be processed successfully.  If the failure
   reason is omission of a required AVP, an AVP with the missing AVP
   code, the missing vendor id, and a zero filled payload of the minimum
   required length for the omitted AVP will be added.

   AVP Format

      <Failed-AVP> ::= < AVP Header: 279 >
                    1* {AVP}

7.6.  Experimental-Result AVP

   The Experimental-Result AVP (AVP Code 297) is of type Grouped, and
   indicates whether a particular vendor-specific request was completed
   successfully or whether an error occurred.  Its Data field has the
   following ABNF grammar:

   AVP Format

      Experimental-Result ::= < AVP Header: 297 >
                                 { Vendor-Id }
                                 { Experimental-Result-Code }

   The Vendor-Id AVP (see Section 5.3.3) in this grouped AVP identifies
   the vendor responsible for the assignment of the result code which
   follows.  All Diameter answer messages defined in vendor-specific
   applications MUST include either one Result-Code AVP or one
   Experimental-Result AVP.

7.7.  Experimental-Result-Code AVP

   The Experimental-Result-Code AVP (AVP Code 298) is of type Unsigned32
   and contains a vendor-assigned value representing the result of
   processing the request.

   It is recommended that vendor-specific result codes follow the same
   conventions given for the Result-Code AVP regarding the different
   types of result codes and the handling of errors (for non 2xxx
   values).



(page 90 continued on part 4)

Next RFC Part