Extending the Diameter Dictionary

When extending the Diameter Dictionary, you may have to modify the create_config.info file to define a new vendor ID, define a new simple AVP, and map the AVP to an MDC field. For example, the Diameter Accounting application uses the Diameter Called-Station-Id AVP to identify the phone number called. To represent this data, the Diameter Dictionary identifies the Diameter Accounting application as the MtxDiamRoMsg message MDC and the Called-Station-Id as the CalledStationId field, respectively. The network element interface providing the messages, determines the network message type to use. For a complete list of the Diameter AVP to MDC field relationships, see the discussion about supported AVPs.

You can extend the MATRIXX Diameter Dictionary by running the config_engine.py script. All Diameter extensions are added to the ${MTX_CUSTOM_DIR}/diameter_dictionary.xml file and the ${MTX_CUSTOM_DIR}/mtx_config.xml file, both of which are read during system start-up to configure the Diameter protocol for MATRIXX. These configurations support the Diameter Base Protocol (RFC 6733 ).

For more information about the MATRIXX environment variables, see the discussion about container directories and environment variables in MATRIXX Installation and Upgrade.

Vendors

The vendors section defines unique vendor names and IDs to identify message origination. 3GPP and MATRIXX are supported by default.

Simple AVPs

The avp elements in the diameter_dictionary.xml file define the simple AVPs supported by MATRIXX. Each avp element completely defines one Attribute Value Pair and is the most frequently used element in the dictionary. AVP Attributes lists the AVP attributes.

Important: AVP names must be unique in the Diameter dictionary. When adding an AVP to the Diameter dictionary, you should prefix it with a customer-specific prefix. For example, adding the AVP Call-Reference-Number with the prefix XYZ results in the following in the diameter_dictionary.xml file:

<avp name="XYZCall-Reference-Number" code="99998" type_name="OctetString" vendor_name="XYZ Company"/>

For more information about adding an AVP to the Diameter dictionary, see the discussion about adding a simple AVP to the Diameter dictionary.

Table 1. AVP Attributes
Attribute	Description
name	AVP name. This is a required string that must be unique across all `avp` names and all `grouped_avp` names.
code	AVP ID code. This is a required integer that must be unique across all `avp` codes.
type_name	The data type as defined in the RFC6733 standard. One of: OctetString Integer32 Integer64 Unsigned32 Unsigned64 Float32 Float64 Grouped Address Time UTF8String DiameterIdentity DiameterURI Enumerated IPFilterRule QoSFilterRule TimeZone Note: The TimeZone data type is used to identify the type of data used in the 3GPP-MS-TimeZone AVP. The MSISDN field is defined as `OctetString` in the diameter_dictionary_base.xml file and is interpreted as such by External Diameter Gateway. TBCDString Important: A TBCDString (Telephony Binary Coded Decimal) represents digits from 0 through 9, , #, a, b, and c. There are two digits per octet, each digit encoded 0000 to 1001 (0 to 9), 1010 (), 1011 (#), 1100 (a), 1101 (b) or 1110 (c). 1111 is used as a filler when there is an odd number of digits. A TBCDString can be mapped only to an MDC String. When mapped to an MDC String, each half-byte is converted to an ASCII character as shown in TBCD String to ASCII Character Conversion. For each byte, its nibbles (half-bytes) are swapped when written to the packet. For example, a two byte MDC string has the hex value of 0x1234. When this field is mapped to a Diameter TCBDString AVP, it value is 0x2143. The reverse is also true. When a Diameter TCBDString AVP containing 0x2143 is received, when it is mapped to an MDC string the value will be 0x1234. The "0x" prefix is not stored in either the AVP or the MDC string. It is used only to denote that the value is expressed as hex digits.
mandatory	An optional Boolean value that sets whether the AVP is mandatory. If a mandatory AVP is received by a Diameter client, server, proxy, or translation agent and either the AVP or its value is unrecognized, the message must be rejected. The default is `true`.
needs_encrypt	An optional Boolean value that defines whether the AVP value should be encrypted or not. Use encryption for end-to-end security of the system. The default is `false`.
vendor_name	An optional string that must match one of the vendor names configured in the Diameter dictionary vendor element. When set, the AVP code belongs to the specific vendor code address space.

Note: Most AVPs are mapped to an MDC field, but this is not required. An AVP must be mapped to an MDC if it will be used during processing or if it will be returned on the Answer packet. Otherwise, it does not need to be mapped. If an AVP is not mapped, it still needs to be specified in the packet definition to prevent error messages being logged about unknown AVPs.

TBCD String to ASCII Character Conversion shows how TBCD digits are mapped to ASCII characters. When mapped to an MDC String, each half-byte is converted to an ASCII character.

Table 2. TBCD String to ASCII Character Conversion
TBCD Digit	ASCII Character
0	0
1	1
2	2
3	3
4	4
5	5
6	6
7	7
8	8
9	9
a	*
b	#
c	a
d	b
e	c
f	<empty>

Grouped AVPs

The grouped AVP elements define the grouped AVPs that are supported. A grouped AVP can contain any number of fixed, required, and optional AVPs.

Attention: All grouped AVPs must be defined in the diameter_dictionary.xml file before they are used in an AVP because Diameter Gateway uses a single-pass XML parser.

Map Functions

Map functions are a way to change an AVP value to a different MDC field value or an MDC field value to a different AVP value. The MATRIXX Engine currently uses mapping functions to return results as Diameter result codes.

Diameter Applications

The following Diameter applications are supported.

Common
The Common application provides the Diameter Capabilities-Exchange answer and request messages, Device-Watchdog answer and request messages, and Disconnect-Peer answer and request messages. When a Diameter client makes a transport connection to the MATRIXX Diameter Gateway, the Capabilities Exchange messages are exchanged, which allows the discovery of MATRIXX Engine and its capabilities (protocol version number, supported Diameter applications, and the like). The Device-Watchdog messages probe the transport connections and the Disconnect-Peer messages inform the Diameter peer of intent to disconnect the transport layer, and that the peer should not reconnect unless it has a valid reason to do so.
Diameter Network Access Server Application (NASREQ)
The NASREQ application provides network access with the Diameter Ro protocol answer and request messages. This application is used for sessions that are limited by time or usage amount.
Accounting
The Accounting application provides Diameter authorization and accounting capabilities from MATRIXX Charging Application to Diameter clients with the Diameter Ro protocol answer and request messages.
Credit-Control
The Credit-Control application (RFC 4006) provides the framework for communication between network applications and MATRIXX Charging Application for real-time charging and credit control.
DiameterWrappedMDC
The DiameterWrappedMDC application load balances MDC traffic through an F5 load balancer.
Policy-Control
The Policy-Control application provides Diameter policy control capabilities from MATRIXX Engine to Diameter clients with Diameter Sy protocol answer and request messages.
Gx
The Gx application provides policy credit control answer and request messages and RAR messages when communicating with a PCEF.
Sy
The Sy application provides answer and request messages when using a PCRF that is external to MATRIXX Engine.

Application Flags

Application Flags describes the Diameter application flags.

Table 3. Application Flags
Flag	Description
request	When set, the message is a request. Otherwise, it is an answer.
proxiable	When set, the message may be proxied, related, or redirected from another hop. Otherwise, it must be processed locally.
error	When set, the message contains a protocol error and the message will not conform.
potentially retransmitted message	This flag is set after a link failover procedure to assist in the removal of duplicate requests. It is set when the application resends a request not yet acknowledged, as an indication of a possible duplicate, due to a link failure.