The XML messages are diameter-like, in that each message contains a diameter header followed by diameter rules for AVP encoding (see the following figure).
Basic Structure of a Diameter-like XML Message
XML messages are of the following three types:
- Requests
- Answers (success or error)
All three messages types are constructed in a similar and generic format as illustrated in Figure Basic Structure of a Diameter-like XML Message.
All outgoing messages from the XML APIs are constructed with all mandatory and optional parameters, while the parsing of incoming messages do take into consideration the optionally of each and every single attribute.
XML Version
This metadata is a preamble to the XML message.
Optional for incoming messages, and always present in outgoing messages
Example:
<?xml version="1.0" encoding="utf-8"?>
Diameter Message XML Element
Start and end tag of the XML message. Encapsulates all other element and attributes contained in the XML message.
Example:
<diameter-message>
.......
</diameter-message>
Mandatory parameters of three types:
Command Code
“The Command-Code field in a diameter message is three octets, and is used to communicate the command associated with the message.” An example of a Command Code for request and answer messages: STR for Session-Termination-Request and STA for Session-Termination-Answer.
Type: ubit32
Maximum of 3 bytes,
Range: 1 – 16777215 (0xFFFFFF); encoded in decimal.
The information that appears in quotation marks are direct quotes for the respective standard.
Hop-by-Hop Identifier
The Hop-by-Hop Identifier (hh-id) is an unsigned 32-bit integer field that is used in matching requests and replies. The Hop-by-Hop identifier in a request must be unique on a given connection at any given time. An answer message must have the same Hop-by-Hop Identifier value that was found in the corresponding request.
Type: ubit32; encoded in decimal.
End-to-End Identifier
The End-to-End Identifier is an unsigned32-bit integer field, and is used to detect duplicate messages. Originators of request messages MUST insert a unique identifier on each message. The End-to-End Identifier MUST remain locally unique for a period of at least 4 minutes, even across reboots. An answer message MUST have the same End-to-End Identifier value that was found in the corresponding request.
Type: ubit32; encoded in decimal.
Optional parameters are of two types:
Flags
The flags parameter is the information that differentiates between a request and answer. For example:
128 : request
64 : Proxyable
32 : error
0 : answer
Type: ubit8
Default value: 192 (Request and Proxyable)
Application ID
“Application-ID is four octets and is used to identify to which application the message is applicable for.”
Type: ubit32
Default value: 0
Example:
<header application-id="0" cmd-code="257" flags="0" hh-id="1" ee-id="1234"/>
Attribute-value Pairs
“AVPs are a method of encapsulating information relevant to the Diameter message.”
AVP parameters are of two types: Mandatory and Optional.
When present, the provided value overrides the default value.
Example:
<avp vendor-id="0" avp-code="264" flags="64" avp-name="Origin-Host" type="DiameterIdentity" encoding="string" value="hhdsc1.sonus.com"/>
Mandatory Parameters
AVPs parameters are mandatory where absence of an attribute causes errors or connection aborts.
Mandatory AVPs are of two types:
AVP Value (value)
AVP Value parameters are one of three format types:
HexString
This type of encoding is cumbersome, but very flexible. It may be used to represent AVPs of any types. It may be used to represent UTF8String AVPs where the expected values are not printable ASCII strings.
This type of AVP Values are in the form of space separated hex pairs such as
“00 0a ab cd”
“ef”
“EF”
“” (empty string)
The string is case insensitive, the values A-F and a-f are equivalent. Each token must be a pair, and the spaces are mandatory. The following are NOT allowed.
“000a”
“00 a ab cd”
Internally, the hex string is stored as a vector of unsigned characters, where each (space separated) token in the hex string is stored as one byte.
This record type may be applied to any type of AVP. For integral types, the number of tokens in the hex string must match the expected length of the AVP (4 tokens for a 32 bit integral AVP, 8 bytes for a 64 bit integral AVP).
String
AVP Value in the form of a printable ASCII string. Internally, the string is stored as a vector of unsigned characters, where each character in the string is stored as one byte using its ASCII value. This value is applicable for AVPs of type octet-string and their descendants, but not to integral types.
Integer
Used to represent the values of enumerated or other integral AVPs. AVP Value must be a string that represents a decimal encoded integer. If the AVP is a signed integer type then a “-” prefix is optionally allowed. The string must represent an integer that can fit in the expected AVP size (4 bytes or 8 bytes). Internally, the integer is stored as a vector of unsigned characters.
AVP Code (avp-code)
“The AVP Code, combined with the Vendor-Id field, identifies the attribute uniquely. AVP numbers 1 through 255 are reserved for backward compatibility with RADIUS, without setting the Vendor-Id field. AVP numbers 256 and above are used for Diameter, which are allocated by IANA.”
Example:
Origin-Host AVP (AVP Code 264), Vendor ID AVP (0)
Optional Parameters
AVP parameters are optional where a default value is provided for the attribute.
Optional parameters are of five types:
AVP Flags (flags)
The AVP Flags field informs the receiver how each attribute must be handled.
Type: ubit8
Format: V M P r r r r r
Bits:
The r (reserved) bits are unused and SHOULD be set to 0 by the sender, and ignored by the receiver.
The P bit indicates the need for encryption for end-to-end security.
The M Bit, known as the Mandatory bit, indicates whether support of the AVP is required.
The V bit, known as the Vendor-Specific bit, indicates whether the optional Vendor-ID field is present in the AVP header. When set the AVP Code belongs to the specific vendor code address space.
Default Value: P bit (0x20)
AVP Vendor ID (vendor-id)
“Vendor-Id is a four-octet field that contains the vendor's assigned SMI Network Management Private Enterprise Codes from IANA.” Vendor-Id is used in conjunction with Vendor's specific AVPs to make sure these AVPs can be identified in their private AVP codes namespace and do not collide with any other external ones. “Absence of a Vendor-Id in an XML message or a Vendor-Id value of zero defaults to the IETF IANA controlled AVP codes namespace.”
Type: ubit32
Default value: 0
AVP Name (avp-name)
The AVP name is optional, and is used to look up AVP details in the Ribbon dictionary. For more information, refer to the Configuring Ribbon DSC Definitions section in the Ribbon DSC Application Guide.
If the API fails to lookup the provided AVP Name in the dictionary, the default AVP fields are used (AVP Code = 0, AVP Type = Unknown, Vendor Id = 0). This usually results in insufficient information for the message to be routed properly.
Type: string
AVP Type (type)
All AVP data fields must be either base data type or derived data type.
Base data type AVP:
- Octet-string: HexString
- Enumerated: s32 - 4 byte integer
- Unsigned32: 4 byte integer
- Unsigned64: 8 byte integer
- Integer32: 4 byte integer
- Integer64: 8 byte integer
- Float32: 4 byte floating point
- Float64: 8 byte floating point
- Grouped AVPs: sequence of nested AVPs
Example:
<avp avp-name="Parent1">
<avp avp-name="Parent2">
<avp avp-name="Vendor-Id" value="10415" />
<avp avp-name="Auth-Application-Id" value="16777217" />
</avp>
</avp>
In the example above, one can observe that the AVP value in grouped AVPs is only provided if the AVP is a child (leaf) AVP and not a parent AVP. In other words, an AVP within a set of grouped AVPs should either provide a child AVP or an AVP value, but not both.
Derived data type:
Direction (in or out)
Source and destination IP address (possibly masked)
Protocol
Source and destination port (lists or ranges)
TCP flags
IP fragment flag
IP options
ICMP types”
- DiameterURI:
“The DiameterURI MUST follow the Uniform Resource Identifiers (URI) syntax rules specified below:
"aaa://" FQDN [ port ] [ transport ] [ protocol ]
"aaas://" FQDN [ port ] [ transport ] [ protocol ]
FQDN = Fully Qualified Host Name
port = One of the ports used to listen for incoming connections.
If absent, the default Diameter port (3868) is assumed.
transport = ";transport=" transport-protocol
One of the transports used to listen for incoming connections. If absent, the default SCTP
[SCTP] protocol is assumed.
transport-protocol = ( "tcp" / "sctp" / "udp" )
protocol = ";protocol=" aaa-protocol
If absent, the default AAA protocol is diameter.
aaa-protocol = ( "diameter" / "radius" )
The following are examples of valid Diameter host identities:
aaa://host.example.com;transport=tcp
aaa://host.example.com:6666;transport=tcp
aaa://host.example.com;protocol=diameter
aaa://host.example.com:6666;protocol=diameter
AVP Encoding (encoding)
Not currently used by the XML APIs for the incoming XML messages to DSC. However, this is properly included in all outgoing messages from DSC.
Encoding is currently decided based on combinations of the format of the AVP value and the AVP type provided in the message. The encoding for cases of absence or unknown AVP types are defaulted to octet-string encoding.
Various Types of Encoding
| AVP Type | Encoding |
|---|
UTF8String DiameterIdentity DiameterURI OctetString Unsigned64 Unknown AVP type IPFilterRule | octet-string or string |
Address Time | octet-string |
Unsigned32 | u32 or octet-string |
Integer32 Enumerated | s32 or octet-string |
Unsigned64 | u64 or octet-string |
Integer64 | s64 or octet-string |
Float32 | f32 or octet-string |
Float64 | f64 or octet-string |