Note

This page has been converted into DocBook XML, and is available online as part of the Diameter User Guide, at the following location:

http://hudson.jboss.org/hudson/job/MobicentsBooks/lastSuccessfulBuild/artifact/diameter/index.html

No further updates will be made to this page.

Mobicents Diameter Core 

The Mobicents Diameter Core consists of the following components:

• Stack
• Multiplexer
• Message validator
  

Mobicents Diameter Stack

The Stack is the main component of Mobicents Diameter. It is the responsible for all the message sending/receiving mechanisms (including the ones for peer management), session management through it's State Machines.

Our stack is based on the work of java.net community, leaded by Erick Svensson, jDiameter. We've been working closely and forked into our own version as our demand was too high and required us to work on it as we need it. Anyway, there's still cooperation between both dev teams and changes applied to the java.net project should be (sooner or later) mirrored into ours, and the same happening the other way if desired.

Configuration

In order to configure the stack, a XML file can be used, where most options can be configured. An explanation of each item follows:

• LocalPeer – describe parameters of local peer such as:
  • OverloadMonitor (Optional) – overload monitor section
    Multiplicity: 0-1
    Type: Node
    • Entry
      Multiplicity: 1-N
      Type: Element
      • index – overload element index (Type: Integer; Default value: 0)
      • lowThreshold – overload low threshold (Type: Double; Default  value: 0)
      • highThreshold  - overload high threshold (Type: Double; Default value: 0)
• Parameters – describe parameters of diameter stack such as:
  • AcceptUndefinedPeer – accept connection from unknown peers
    Multiplicity: 0-1
    Type: Boolean
    Default value: false
    
  • DuplicateProtection – on/off duplication protection
    Multiplicity: 1
    Type: Boolean
    Default value: false
    
  • DuplicateTimer – life timer for duplication messages
    Multiplicity: 1
    Type: Long
    Default value: 4 minutes
    
• Networks – describe externals peer
  • Peers – set of external peers
    • Peer – external peer
      • attempt_connect (Type: Boolean; Default value: false)
  • Realms – all realms into diameter network
    • Realm – realm description
      • ApplicationID – realm application id’s (see above)
      • name – realm name (Type: String; Default value: ‘’)
      • peers – realm peers (split by ‘,’) (Type: String; Default value: ‘’)
      • local_action – local action name (Type: String; Default value: ‘localhost’)
      • dynamic – dynamic flag (Type: Boolean; Default value: false)
      • exp_time – experation time (Type: Long; Default value: 0)

This is what a configuration file should look like:

<?xml version="1.0"?>

<Configuration xmlns="http://www.jdiameter.org/jdiameter-server">

 

  <LocalPeer>

    <URI value="aaa://127.0.0.1:1812"/>

    <IPAddresses>

      <IPAddress value="127.0.0.1"/>

    </IPAddresses>

    <Realm value="mobicents.org"/>

    <VendorID value="193"/>

    <ProductName value="jDiameter"/>

    <FirmwareRevision value="1"/>

    <OverloadMonitor>

      <Entry index="1" lowThreshold="0.5" highThreshold="0.6">

        <ApplicationID>

          <VendorId value="193"/>

          <AuthApplId value="0"/>

          <AcctApplId value="19302"/>

        </ApplicationID>

      </Entry>

    </OverloadMonitor>

  </LocalPeer>

 

  <Parameters>

    <AcceptUndefinedPeer value="true"/>

    <DuplicateProtection value="true"/>

    <DuplicateTimer value="240000"/>

    <UseUriAsFqdn value="true"/> <!-- Needed for Ericsson SDK Emulator -->

    <QueueSize value="10000"/>

    <MessageTimeOut value="60000"/>

    <StopTimeOut value="10000"/>

    <CeaTimeOut value="10000"/>

    <IacTimeOut value="30000"/>

    <DwaTimeOut value="10000"/>

    <DpaTimeOut value="5000"/>

    <RecTimeOut value="10000"/>

  </Parameters>

 

  <Network>

    <Peers>

      <!-- This peer is a server, if it's a client attempt_connect should be set to false -->

      <Peer name="aaa://127.0.0.1:3868" attempt_connect="true" rating="1"/>

    </Peers>

    <Realms>

      <Realm name ="mobicents.org" peers="127.0.0.1" local_action="LOCAL" dynamic="false" exp_time="1">

        <ApplicationID>

          <VendorId value="193"/>

          <AuthApplId value="0"/>

          <AcctApplId value="19302"/>

        </ApplicationID>

      </Realm>

    </Realms>

  </Network>

 

  <Extensions/>

 

</Configuration>

How to use

In order to use the stack, just import it as a library into your project.

Mobicents Diameter Multiplexer (Mux)

The Multiplexer is a component designed to provide a wrapper to the stack, ie, a more friendly API for the Diameter stack and be able to register different listeners to different Applications so it is possible to have more than one application sharing the same stack instance. It also provides a Diameter dictionary which is used to create messages and AVPs with their flags set correctly, releasing the application from worrying about it, and also useful for validation.

In the current version, only few API facilities are provided by the Mux but in the future it should be a complete wrapper for the stack, allowing the change to any other stack without changes to the applications using it (aswell as JSLEE Resource Adaptors).

Configuration

The only configuration needed for the Mux is the stack configuration file mentioned above. It should be found in "container\server\default\deploy\mobicents-diameter-mux-xxxx.sar\config\jdiameter-config.xml".

At the moment it is not possible to change this configuration in runtime, it is expected to be implemented in future versions.

How to use

To use the Mobicents Diameter Mux, deploy the SAR folder in your JBoss deploy folder. To register your application as a listener, you can use the following code snippet:

package org.mobicents.slee.resource.diameter.base;

 

import javax.management.InstanceNotFoundException;

import javax.management.MBeanException;

import javax.management.MBeanServer;

import javax.management.MalformedObjectNameException;

import javax.management.ObjectName;

import javax.management.ReflectionException;

 

import org.jboss.mx.util.MBeanServerLocator;

import org.jdiameter.api.Answer;

import org.jdiameter.api.ApplicationId;

import org.jdiameter.api.Request;

import org.mobicents.diameter.stack.DiameterListener;

import org.mobicents.diameter.stack.DiameterStackMultiplexerMBean;

 

public class MyDiameterApplication implements DiameterListener

{

  private DiameterStackMultiplexerMBean diameterMux = null;

 

  private DiameterStackMultiplexerMBean getMux() throws InstanceNotFoundException, MBeanException, ReflectionException, MalformedObjectNameException, NullPointerException

  {

    if(this.diameterMux == null)

    {

      MBeanServer server = MBeanServerLocator.locateJBoss();

 

      ObjectName diameterMultiplexerObjectName = new ObjectName("diameter.mobicents:service=DiameterStackMultiplexer");

 

      Object[] params = new Object[]{};

      String[] signature = new String[]{};

      String operation = "getMultiplexerMBean";

 

      Object object = server.invoke(diameterMultiplexerObjectName, operation, params, signature);

 

      if(object instanceof DiameterStackMultiplexerMBean)

      {

        this.diameterMux = (DiameterStackMultiplexerMBean) object;

      }

    }

 

    return this.diameterMux;

  }

 

  private void registerInMux()

  {

    ApplicationId shAppId = ApplicationId.createByAuthAppId(10415L, 16777217L);

   

    if(this.diameterMux != null)

    {

      this.diameterMux.registerListener(this, new ApplicationId[]{shAppId});

    }

  }

 

  public Answer processRequest( Request request )

  {

    // Your processing code goes here...

  }

 

  public void receivedSuccessMessage( Request request, Answer answer )

  {

    // Your processing code goes here...

  }

 

  public void timeoutExpired( Request request )

  {

    // Your processing code goes here...

  }

 

}

Validator

NOTE: in v1.0.1GA dictionary and validator had separate configuration files.
Validator is designed to allow validation of messages in terms of consistency with defining documents(RFCs, TS or any other). It allows to detect malformed messages - for instance Answer message containing Destination-Host AVP. Valdiator is also capable of validating Grouped AVPs(many levels), however currently it is not capable of validating content based on type:

• URI/Identity types
  
• Enum types against defined values

Current API is oriented to perform validation of whole messages in terms of AVP consisntency(this will change in next releases to allow user to perform validation if needed). Validator is jdiameter stack part so it can be used at application session level.
Validator consumes configuration file which should be present in classpath(more about configuration below). Filename is: dictionary.xml.

Dictionary

Dictionary is diameter MUX module. It has been designed to allow users of MUX to retreive AVP and message definition information like: bit flags, avp types.
Dictionary consumes configuration file which should be present in classpath(more about configuration below). Filename is: dictionary.xml.
It is based on Validator module which parses configuration file. Based on provided information dictionary builds its internal structures and provides information to 3rd party modules that make use of those definitions.

How to use:

  public static void setAvpAsFloat32(Message msg, int avpCode, long vendorId, AvpSet set, float value)
  {
    AvpRepresentation rep = AvpDictionary.INSTANCE.getAvp(avpCode, vendorId);

    if (rep != null) {
        set.addAvp(avpCode, value, vendorId, isMandatory, isProtected);
    }
    else {
       set.addAvp(avpCode, value, vendorId,  _DEFAULT_MANDATORY,  _DEFAULT_PROTECTED);
   
    }
  }

Dictionary & Validator Configuration

Validator and Dictionary are configured via single XML file. Validator is configured once it is created. Since MUX module creates stack validator is configured with dictionary.xml present in MUX classpath. This file can be found in /trunk/servers/diameter/code/mux/jar/META-INF. Dictionary build its internal data structures based on the same file. So it has exactly the same definitions as validator and there is no way to introduce missconfiguration.

Configuration

XML content follows rules:

• top element must be: <validator>
• each command must be indicated by tag: <command>
• each avp in command must be indicated by tag: <avp>

General structure is as follows:
<dictionary>
    <validator/>
    <vendor/>
    <typedefn/>
    <application>
          <avp/>
          <command/>
    <application>
</dictionary>

XSD file can be found here.

Each element supports certain properties that are vital part of configuration. Starting from docuemnt root:

 <dictionary> - this is root element, it does not support any attributes, its only purpose is to embed all other tags

• no attributes defined
  

<validator> 

• enabled - this is boolean attribute which takes either "true" or "false", default is "false" if not present. If set to true validation of messages in stack is enabled on send/receive.
  

<vendor> - defines mapping between vendor name, vendor id and vendor code.

• name - defines vendor name, like "3GPP"
• vendor-id - id assigned to this vendor by arbittrary body, generaly it equals name attribute
• code - long value assigned by arbittrary body.
  

<typedefn> - defines types for avps (simple avps)

• type-name - name of type
• type-parent - name of parent type (must match one of typedefn->type-name)
  

<application> - this element defines specific application

• id - long attribute which is unique per application, it is used in all messages as part of header.
• name - simple string representing name of applications, like: Sh, Cx
  

NOTE: avp element may change
 <avp> - most complex element. It can have various versions, depending on place where it is used.

• name - determines name of avp. This attribute is required in avp definition, since it is used to match avp definition to grouped avp reference(see below)
  
• code - determines integer code of avp, it is required.
• vendor-id - determines vendor-id reference to value defined in <vendor> element, if not present it defaults to "none".
  
• multiplicity - determines how many avps must/may be present. Defaults to 0+. Valid values are:

            0     The AVP MUST NOT be present in the message.
            0+    Zero or more instances of the AVP MAY be present in the
                  message.
            0-1   Zero or one instance of the AVP MAY be present in the
                  message.  It is considered an error if there are more than
                  one instance of the AVP.
            1     One instance of the AVP MUST be present in the message.
            1+    At least one instance of the AVP MUST be present in the
                  message.

• index - determines index in message, currently there is only one avp with fixed index - SessionId. This is required. Indexing starts from zero (natural IT one). If location does not matter it must have "-1" as value
• may-encrypt - determines if avp can be ecnrypted, valid values are: "yes" and "no", defaluts to "no"
• protected - determines XXXX, valid values are: "may", "must" and "mustnot"
• vendor-bit - determines if vendor id should be set, valid values are: "must" and "mustnot"
• mandatory - determines XXXX, valid values are: "may", "must" and "mustnot"
• vendor - vendor code, this field is used in command element. Must have value of defined vendor->code
  

avp element support certain subelemnts:
 - <type> - defines type of avp

• type-name - reference defined type with <typedefn>

 - <enum> - defines constants for certain avps

• name - attribute which defines name of constant
• code - int code for constant - this is passed as value of avp, which maps to "name"

- <grouped> - uysed when avp is of type grouped (no typedefn present). It does not support any attribute. It has subelement <gavp>, which supports single attribute "name", this attribute value must match name of defined avp.


           
<command> - defines command for application.

• name - determines name of message, its meaning is only descriptive. its not required.
• code - determines integer code of message, this is required.
• request - determines if declared command is request or answer, one of boolean values is expected: "true" or "false". This is requried.

command supports subelement: <avp>, which defines structure of command.


Example:
<?xml version="1.0" encoding="UTF-8"?>

   <dictionary>
        <vendor vendor-id="None" code="0" name="None" />
        <vendor vendor-id="HP" code="11" name="Hewlett Packard" />
        <vendor vendor-id="Merit" code="61" name="Merit Networks" />
        <vendor vendor-id="Sun" code="42" name="Sun Microsystems, Inc." />
        <vendor vendor-id="USR" code="429" name="US Robotics Corp." />
        <vendor vendor-id="3GPP2" code="5535" name="3GPP2" />
        <vendor vendor-id="TGPP" code="10415" name="3GPP" />
        <vendor vendor-id="TGPPCX" code="16777216" name="3GPP CX/DX" />
        <vendor vendor-id="TGPPSH" code="16777217" name="3GPP SH" />
        <vendor vendor-id="Ericsson" code="193" name="Ericsson" />
        <vendor vendor-id="ETSI" code="13019" name="ETSI" />
        <vendor vendor-id="Vodafone" code="12645" name="Vodafone" />

        <typedefn type-name="OctetString" />
        <typedefn type-name="UTF8String" type-parent="OctetString" />
        <typedefn type-name="IPAddress" type-parent="OctetString" />
        <typedefn type-name="DiameterIdentity" type-parent="OctetString" />
        <typedefn type-name="IPFilterRule" type-parent="OctetString" />
        <typedefn type-name="QOSFilterRule" type-parent="OctetString" />
        <typedefn type-name="MIPRegistrationRequest" type-parent="OctetString" />
        <typedefn type-name="Integer32" />
        <typedefn type-name="VendorId" type-parent="Unsigned32" />
        <typedefn type-name="AppId" type-parent="Unsigned32" />
        <typedefn type-name="Float64" />
        <typedefn type-name="Integer64" />
        <typedefn type-name="Unsigned32" />
        <typedefn type-name="Time" />
        <typedefn type-name="Unsigned64" />
        <typedefn type-name="Enumerated" type-parent="Integer32" />
        <typedefn type-name="DiameterURI" type-parent="UTF8String" />



        <application id="16777216" name="3GPP Cx/Dx" uri="http://www.ietf.org/rfc/rfc3588.txt?number=3588">
        <!-- 3GPP Cx/Dx Application -->
        <!--
        < User-Authorization-Request> ::=            < Diameter Header: 300, REQ, PXY, 16777216 >
                                < Session-Id >
                                { Vendor-Specific-Application-Id }
                                { Auth-Session-State }
                                { Origin-Host }
                                { Origin-Realm }
                                [ Destination-Host ]
                                { Destination-Realm }
                                { User-Name }
                                *[ Supported-Features ]
                                { Public-Identity }
                                { Visited-Network-Identifier }
                                [ User-Authorization-Type ]
                                [ UAR-Flags ]
                                *[ AVP ]
                                *[ Proxy-Info ]
                                *[ Route-Record ]
                                -->
           <command name="User-Authorization" code="300" vendor-id="TGPP" request="true">
               <avp name="Session-Id" code="263" vendor="0" multiplicity="1" index="0" />
               <avp name="Vendor-Specific-Application-Id" code="260" vendor="0" multiplicity="1" index="-1" />
               <avp name="Auth-Session-State" code="277" vendor="0" multiplicity="1" index="-1" />
               <avp name="Origin-Host" code="264" vendor="0" multiplicity="1" index="-1" />
               <avp name="Origin-Realm" code="296" vendor="0" multiplicity="1" index="-1" />
               <avp name="Destination-Realm" code="283" vendor="0" multiplicity="1" index="-1" />
               <avp name="User-Name" code="1" vendor="0" multiplicity="1" index="-1" />
               <avp name="Public-Identity" code="601" vendor="10415" multiplicity="1" index="-1" />
              <avp name="Visited-Network-Identifier" code="600"  vendor="10415" multiplicity="1" index="-1" />
               <!-- MAY -->
               <avp name="Destination-Host" code="293" vendor="0" multiplicity="0-1" index="-1" />
               <avp name="Supported-Features" code="628" vendor="10415" multiplicity="0+" index="-1" />
               <avp name="User-Authorization-Type" code="623" vendor="10415" multiplicity="0-1" index="-1"/>
               <avp name="UAR-Flags" code="637"  vendor="10415" multiplicity="0-1" index="-1"/>
               <avp name="Proxy-Info" code="284" vendor="0" multiplicity="0+" index="-1" />
               <avp name="Route-Record" code="282" vendor="0" multiplicity="0+" index="-1" />

               <!-- FORBBIDEN -->
               <avp name="Auth-Application-Id" code="258" vendor="0" multiplicity="0" index="-1" />
               <avp name="Error-Reporting-Host" code="294" vendor="0" multiplicity="0" index="-1" />
               <avp name="Experimental-Result" code="297" vendor="0" multiplicity="0" index="-1" />
               <avp name="Result-Code" code="268" vendor="0" multiplicity="0" index="-1" />
           
           </command>

           .....

           <!--  CX/DX -->
        <avp name="Visited-Network-Identifier" code="600" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="OctetString" />
        </avp>
        <avp name="Public-Identity" code="601" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="UTF8String" />
        </avp>
        <avp name="Server-Name" code="602" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="UTF8String" />
        </avp>
        <avp name="Server-Capabilities" code="603" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <grouped>
                <gavp name="Mandatory-Capability" multiplicity="0+"/>
                <gavp name="Optional-Capability" multiplicity="0+"/>
                <gavp name="Server-Name" multiplicity="0+"/>
            </grouped>
        </avp>
        <avp name="Mandatory-Capability" code="604" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="Unsigned32" />
        </avp>
        <avp name="Optional-Capability" code="605" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="Unsigned32" />
        </avp>
        <avp name="User-Data" code="606" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="OctetString" />
        </avp>
        <avp name="SIP-Number-Auth-Items" code="607" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="Unsigned32" />
        </avp>
        <avp name="SIP-Authentication-Scheme" code="608" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="UTF8String" />
        </avp>
        <avp name="SIP-Authenticate" code="609" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="OctetString" />
        </avp>
        <avp name="SIP-Authorization" code="610" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="OctetString" />
        </avp>
        <avp name="SIP-Authentication-Context" code="611" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="OctetString" />
        </avp>
        <avp name="SIP-Auth-Data-Item" code="612" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <grouped>
                <gavp name="SIP-Item-Number" multiplicity="0-1"/>
                <gavp name="SIP-Authentication-Scheme" multiplicity="0-1"/>
                <gavp name="SIP-Authenticate" multiplicity="0-1"/>
                <gavp name="SIP-Authorization" multiplicity="0-1"/>
                <gavp name="SIP-Authentication-Context" multiplicity="0-1"/>
                <gavp name="Confidentiality-Key" multiplicity="0-1"/>
                <gavp name="Integrity-Key" multiplicity="0-1"/>
                <gavp name="SIP-Digest-Authenticate" multiplicity="0-1"/>
                <gavp name="Line-Identifier" multiplicity="0+"/>
            </grouped>
        </avp>
        <avp name="SIP-Item-Number" code="613" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="Unsigned32" />
        </avp>

        <avp name="Server-Assignment-Type" code="614" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no">
            <type type-name="Unsigned32" />
            <enum name="NO_ASSIGMENT" code="0" />
            <enum name="REGISTRATION" code="1" />
            <enum name="RE_REGISTRATION" code="2" />
            <enum name="UNREGISTERED_USER" code="3" />
            <enum name="TIMEOUT_DEREGISTRATION" code="4" />
            <enum name="USER_DEREGISTRATION" code="5" />
            <enum name="TIMEOUT_DEREGISTRATION_STORE_SERVER_NAME" code="6" />
            <enum name="USER_DEREGISTRATION_STORE_SERVER_NAME" code="7" />
            <enum name="ADMINISTRATIVE_DEREGISTRATION" code="8" />
            <enum name="AUTHENTICATION_FAILURE" code="9" />
            <enum name="AUTHENTICATION_TIMEOUT" code="10" />
            <enum name="DEREGISTRATION_TOO_MUCH_DATA" code="11" />
        </avp>


        ......

      </application>
   </dictionary>

How to use

To use one needs:
 - instance of validator
 - xml configuration file if it should not be default file. (NOTE that change will be global for jvm.)

Currently the API defines the following methods:

• public void validate(Message msg) throws JAvpNotAllowedException - if validtor is on it will do its best to perform operation on passed message.
• public void validate(int commandCode, long appId, boolean isRequest, AvpSet destination, Avp avp) - similar as above, however validation is performed against passed "avp" - where AvpSet is messages avp set.
• public boolean isCountValidForMultiplicity(int commandCode, long appId, boolean isRequest, AvpSet destination, int avpCode, long avpVendor) - determines avp count is valid in passed set. Message is determined by commandCode,appId and isRequest.
• public boolean isAllowed(int commandCode, long appId, boolean isRequest, int avpCode, long avpVendor) - similar check as above, however its a bit narrow - checks only if multiplicity is not "0".
• public boolean hasRepresentation(int commandCode, long appId, boolean isRequest, int avpCode, long avpVendor) - determines two things - if there is message and avp representation it returns true, otherwise its false.
• also public static final DiameterMessageValidator getInstance() and public boolean isOn() are of use.
  

 
Examples usage:

             if (!validator.isOn())
                return;

            if (!validator.isAllowed(msg.getCommandCode(), msg.getApplicationId(), msg.isRequest(), avpCode, vendorId)) {
                throw new AvpNotAllowedException("Avp defined by code: " + avpCode + ", vendorId: " + vendorId + " is not allowed in message - code: " + msg.getCommandCode() + ", appId: "
                        + msg.getApplicationId() + ", isRequest: " + msg.isRequest(), avpCode, vendorId);
            }

            if (validator.hasRepresentation(msg.getCommandCode(), msg.getApplicationId(), msg.isRequest(), avpCode, vendorId)) {
                // we are allowed to add this to msg
                if (validator.isCountValidForMultiplicity(msg.getCommandCode(), msg.getApplicationId(), msg.isRequest(), msg.getAvps(), avpCode, vendorId)) {
                    // its ok.
                    return;
                } else if (isAvpRemoveAllowed()) {
                   // lets remove some avps.
                } else {
                    throw new AvpNotAllowedException("Avp not allowed, count exceeded.", avpCode, vendorId);
                }
            }else
            {
                //Default we dont do a thing.
            }