6. Diameter message processing
This section describes how Diameter requests and answers are created
and processed.
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.
- 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.
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.
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,
- 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.
+------------------+
| 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.
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.
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.
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.
This AVP SHOULD be placed as close to the Diameter header as
possible. 6.10
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.
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.
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.
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.
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.
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 ]
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.
The Proxy-State AVP (AVP Code 33) is of type OctetString, and
contains state local information, and MUST be treated as opaque data.
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.
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.
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.
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].
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 }
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.
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.
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.
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.
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).
