The Diameter Base Protocol(3.3)

Owned by Jenni Wallin
Oct 02, 2023
9 min read

The Diameter Base Protocol is a successor of the Radius Protocol. It is designed to provide an extensible framework for any services that require the support of authentication, authorization, and accounting (AAA), across several networks. The Diameter Base Protocol, unlike the Radius Protocol, also enables new access control features while maintaining flexibility for further extension.

According to RFC 6733, the Diameter Base Protocol alone does not offer much functionality. The Diameter Base Protocol should be regarded as a standard transport and management interface for AAA applications that provide a well-defined functionality subset. To increase functionality, predefined AAA applications are added. An AAA application usually consist of new command code and AVP definitions that map the semantics of the application. One example of a predefined application is the Diameter Credit-Control. For further information, see RFC 4006.

The Diameter Workflow Operation

There are two Diameter agents:

  • Diameter Stack

  • Diameter Request

Diameter Stack

The  Diameter Stack agent manages transport, decoding, and encoding of Diameter input messages. In order for a workflow to act as a Diameter server, you must use the Diameter Stack agent. The Diameter Stack agent communicates with the workflow by using the UDR type called RequestCycleUDR. When a request message arrives to the stack, the message is decoded, validated, and turned into a UDR of the pre-generated UDR type, as specified in the Commands tab in Diameter Application Profile (3.3). This UDR is inserted into the RequestCycleUDRs Request field and routed through the workflow. By using the APL function udrCreate the Answer field is populated with an appropriate answer message, and then RequestCycleUDR is routed back to the stack agent, for transmission of the answer.

It is possible to use multiple Diameter Stack agents in a workflow if that is required in the business logic. However, for the best possible performance, it is recommended to use one Diameter Stack agent per workflow.

A Diameter Stack workflow

Note!

  • Diameter Base Protocol commands such as Capability-Exchange-Request and Capability-Exchange-Answer, are handled internally by the Diameter Stack agent. You see an indication of execution of these commands on the Workflow Monitor in the debug mode. The Diameter Stack agent also publish MIM values that contain counters for the various commands.
  • AVPs (Attribute-Value pairs) from the Diameter Base Protocol are static, unchangeable, and always available .

Diameter Request

In order for a workflow to act as a Diameter client, you must use both the Diameter Request agent and the Diameter Stack agent. The Diameter Request agent simply references a Diameter Stack agent that is suitable for the outgoing route.

A RequestCycleUDR with a populated Request field is routed into the Diameter Request agent. This agent then uses the selected stack to send the message. A RequestCycleUDR containing the original Request field and a populated Answer field is then routed back into the workflow.

A Diameter Request workflow

Diameter Related UDR Types

You view the UDR types that are created by default in the Diameter agents (based on RFC 6733), in the UDR Internal Format Browser, in the Diameter folder. To open the browser, open an APL Editor. In the editing area right-click and select UDR Assistance.

The UDR Internal Format Browser

Each Command or AVP that is defined in the Diameter application profile configuration will result in a UDR type after it has been saved. Note that the base commands and AVPs in RFC 6733 are predefined and included automatically.

Note!

The BaseUDR and BaseCommand UDR types are internal and shall not be used in APL code.

RequestCycleUDR

The Diameter Stack agent and Diameter Request agent communicate with the workflow by using the UDR type RequestCycleUDR. For more information, see the sections above, Diameter Stack, and Diameter Request.

The following fields are included in the RequestCycleUDR:

Field
Description
Answer (BaseCommand (Diameter))

This field is populated with an "answer message UDR", before routed back by the workflow to the Diameter Stack agent. For the Diameter Request agent it will work the reversed way: after the answer field has been populated by the agent, the RequestCycleUDR is routed to the workflow.

Note!

In the answer message UDR, the fields Origin_Host and Origin_Realm will be automatically populated by the Diameter stack in case they are unconfigured, i e set to null. Otherwise, your configured values will be used.

The field EndToEndIdientifier is available as a read-only field and will always have the same value as in the "request message UDR".

AnswerReceivedTime (long)A timestamp indicating when the client receives the answer in nanoseconds.
AnswerSentTime (long)A timestamp indicating when the server sends the answer in nanoseconds.
Context (any)This is an internal working field that can be used in the workflow configuration to keep track of and use internal workflow information related to the request, when processing the answer. An example for a proxy workflow including TCP/IP and Diameter agents: When sending the RequestCycleUDR to the Diameter Request agent, the input TCPIPUDR is saved in the Context field. When the response is received from the Diameter agent, the TCPIPUDR can be read from the Context field and this TCPIPUDR can be used to send back the response to the TCP/IP agent.
ExcludePeers (list<string>)

You can populate this field with a list a list of peers, identified by their hostnames. When Round Robin is selected as the Realm Routing Strategy, these peers will be excluded from lookups in the Realm Routing Table.

You can use ExcludePeers to act on errors in the answers from a Diameter server. For instance, if a peer answers with the Result-Code AVP set to DIAMETER_TOO_BUSY 3004, you may want to exclude this peer in consecutive requests for some time.

IncomingRemotePeer (string)

This field is populated with the Diameter identity of the sending peer.

Note!

The field is read-only and will be automatically populated by the Diameter stack.

Request (BaseCommand (Diameter))

The Diameter Stack agent populates the Request field with the "request message UDR" before routing the RequestCycleUDR to the workflow. For the Diameter Request agent it will work the reversed way and request messages will be transmitted from the workflow to the Diameter Stack agent by using this field.

Note!

In the request message UDR, the fields Origin_Host and Origin_Realm will be automatically populated by the Diameter stack in case they are unconfigured, i e set to null. Otherwise, your configured values will be used.

The value of the field EndToEndIdientifier can be configured by using APL. If it is not configured, the value will be set by the stack sending out the request.

RequestReceivedTime (long)A timestamp indicating when the server receives the request in nanoseconds.
RequestSentTime (long)A timestamp indicating when the client sends the request in nanoseconds.
Session_Id(string)A Diameter Session-Id value that will be read from the Request field in the Diameter message. This is a read-only field.
Throttled(boolean)

This fl ag indicates whether the UDR has been throttled or not. Default is false , and if the UDR has been throttled, it will be set to true . 

Note!

If Throttled is true , the Answer field of the RequestCycleUDR will be set to null.

WrappedMZObject

The WrappedMZObject UDR does not map to a Diameter message but can be used to send data between workflows. WrappedMZObject is added as a field in the RequestCycleUDR (request or answer).

Note!

Since this is not a normal Diameter message, the receiver has to be another workflow.

The following fields are included in the WrappedMZObject UDR:


Field
Description
Data (any)The data to send to another workflow.
Destination_Host (string)The server host, the destination of the message.
Destination_Realm (string)The realm where to route the message.
Is_Request (boolean)Used to indicate if the message is a request or not.
Is_Unidirectional (boolean)To be used if when no reply is expected.

DiameterErrorUDR

When any of the following errors occurs, the Diameter Stack agent creates a DiameterErrorUDR:

  • Decoding and validation errors for known requests and answers (e g unknown or missing AVP)
  • Unknown request or answer (unknown command ID)
  • Failure in CER/CEA handshake (e g no common applications)
  • Request or answer sent before CER/CEA handshake

A DiameterErrorUDR is not created unless the erroneous incoming data is formatted as a Diameter command. It must contain a header followed by a payload.

The following fields are included in the DiameterErrorUDR UDR:

Field
Description
ErrorMessage (string)This field contains the error message.
IncomingMessage (BaseCommand(Diameter))This field is populated with the incoming message if it can be decoded.
IncomingRemotePeer (string)

This field contains the name of the source peer, as specified in the Diameter routing profile configuration. If the peer is unknown, this field contains the content of the Origin-Host AVP, provided that the incoming message can be decoded.

RawIncomingMessage (bytearray)This field contains the original Diameter message.
ResultCode (int)This fields contains the Diameter result code.
SentAnswer (BaseCommand(Diameter))This field is populated with the answer message, if any.
OriginalData (bytearray)This field is always empty.

You can configure the Diameter Stack agent to route UDRs of this type to the workflow. For more information, see Advanced Tab in Diameter Stack Agent Configuration(3.3).

ConnectionLost UDR

The ConnectionLost UDR is sent whenever a connection to a peer is lost, regardless of the reason for the connection going down, i e, whether it is a controlled shutdown or,  for example, a network failure.

FieldDescription
Message (string)This field contains the connection related message indicating the reason for the lost connection.
PeerName (string)This field contains the name of the peer to which the connection is lost.

You can configure the Diameter Stack agent to route UDRs of this type to the workflow. For more information, see Advanced Tab in Diameter Stack Agent Configuration(3.3).

Special Error Handling

The Diameter Stack agent produces three  error answers with internal result codes.

  • No suitable route

    When there is no peer or realm in the Diameter Routing profile that matches the content of the AVPs that are used for routing, a message with the error code 4997 is returned.

    The following AVPs are used for routing:

    • Destination-Host 

    • Destination-Realm 

    • Acct-Application-Id 

    • Auth-Application-Id 

    • Vendor-Specific-Application-Id

This error may also occur when all the peers of a realm are specified in the ExcludePeers field of a RequestCycle UDR and Round Robin is the selected Realm Routing Strategy.

  • Connection to peer not open

    When connection with the peer that is receiving the request is not established, a message with the error code 4998 is returned.

  • Timed out waiting for answer

    When a request is sent to a peer and no answer is received within a configurable timeout, a message with the error code 4999 is returned.

Peer Failover Handling

The connections to peers are monitored through the standard Diameter watchdog as described in RFC 6733 and RFC 3539. Possible states of the connections are: OKAY, SUSPECT, DOWN, REOPEN, INITIAL. These states are used by Diameter Stack agent for peer selection, failover handling, and to determine when messages should be routed to the workflow.

The diagram below illustrates a failover scenario where a CCR (Credit Control Request) message is routed from a workflow.

Handling of Outstanding Request at Peer Failover

  1. A CCR message is routed from a workflow to a Diameter Stack agent.
  2. The Diameter Stack agent routes the CCR message to Peer 1. The peer connection status of Peer 1 is OKAY.
  3. Peer 1 does not respond within the timeout period that is configured in the Diameter Stack agent and an Error Answer Message is routed back to the workflow.
  4. The workflow is configured to act on the Error Answer Message and resends the CCR message. 
  5. Since the Diameter Stack agent does not receive an answer after the first CCR message, it sends a DWR (Diameter Watchdog Request) message to Peer 1.
  6. The watchdog timer interval TWINIT expires without a response from Peer.
  7. The Diameter Stack agent sends a second DWR message to Peer 1.
  8. The workflow makes a third attempt at sending the CCR message.

  9. In the meantime, TWINIT has expired twice and the connection state for Peer 1 has changed to SUSPECT. This triggers the Diameter Stack agent to resend the CCR message to a different peer.

  10. Diameter requests are only routed to peers with status REOPEN and SUSPECT as a last resort, i e when there are no peers with status INITIAL or OKAY. For this reason the Diameter agent now immediately routes the CCR message to another available peer (Peer 2 in this example).
  11. TWINIT has now expired three times and the peer connection status has changed to DOWN. This means that messages are no longer routed to this peer.
  12. Peer 2 responds with a Credit Control Answer (CCA) message to the Diameter Request agent, which then routes the message back to the workflow.


For simplicity of the example above, TWINIT appears longer than the Diameter answer timeout. In a production configuration this is typically not the case. 

For information about how to configure the Diameter answer timeout and TWINIT, see Diameter Stack Agent(3.3). For information about how to configure Diameter peers, see Diameter Routing Profile (3.3).