en-US.Section-JDiameter-Validator-Configuration.xml Maven / Gradle / Ivy
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Diameter_User_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="jdiameter-validator-configuration">
<title>Validator Configuration</title>
<para>The Validator is configured with a single XML file. This file contains the structure definition for both messages and AVPs.</para>
<para>Upon creation of the Diameter Stack, the validator is initialized. It performs the initialization by looking up the <filename>dictionary.xml</filename> file in classpath.</para>
<note>
<para>
The configuration file contains more data that <literal>Validator</literal> uses to build its data base. This is because the <literal>Dictionary</literal> uses the same file to configure itself. It reuses the AVP definitions, with some extra information like AVP type and flags.
</para>
</note>
<para>The configuration file has the following structure:</para>
<programlisting role="XML">
<dictonary>
<validator enabled="true|false" sendLevel="OFF|MESSAGE|ALL" receiveLevel="OFF|MESSAGE|ALL" />
<vendor name="" vendor-id="" code=""/>
<typedefn type-name="" type-parent=""/>
<application id="" name="">
<avp ...>
<type type-name=""/>
<enum name="" code=""/>
<grouped>
<gavp name=""/>
<grouped/>
<avp/>
<command name="" code="" request="true|false"/>
<avp ...>
<type type-name=""/>
<enum name="" code=""/>
<grouped>
<gavp name=""/>
<grouped/>
<avp/>
<application>
<dictionary/></programlisting>
<variablelist>
<varlistentry>
<term><dictionary></term>
<listitem>
<para>
The root element that contains the child elements comprising the validator and dictionary components. This element does not support any attributes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><validator></term>
<listitem>
<para>
Specifies whether message validation is activated for sent and received stack messages. The element supports the following optional attributes:
</para>
<variablelist>
<varlistentry>
<term>enabled</term>
<listitem>
<para>Specifies whether the validator is activated or deactivated. If not specified, the validator is deactivated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>sendLevel</term>
<listitem>
<para>Determines the validation level for messages sent by the stack instance. Values determine if sent messages are not validated at all (<literal>OFF</literal>), only message level AVPs are checked (<literal>MESSAGE</literal>) or all AVPs are checked (<literal>ALL</literal>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>receiveLevel</term>
<listitem>
<para>Determines the validation level for messages received by the stack instance. Values determine if sent messages are not validated at all (<literal>OFF</literal>), only message level AVPs are checked (<literal>MESSAGE</literal>) or all AVPs are checked (<literal>ALL</literal>).</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><vendor></term>
<listitem>
<para>
Optional element that specifies the mapping between the vendor name, vendor ID, and vendor code. The element supports the following required attributes:
</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>Specifies the vendor name. For example, "Hewlett Packard".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>vendor-id</term>
<listitem>
<para>Specifies the unique ID associated with the vendor. For example, "HP".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>code</term>
<listitem>
<para>Specifies the alpha-numeric code allocated to the vendor by <orgname>IANA</orgname>. For example, "11". The value must be unique for each <vendor> declaration.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<example id="example-Vendor_XML_Attributes">
<title><vendor> XML Attributes</title>
<programlisting role="XML">...
<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" /></programlisting>
</example>
<!--***TODO: Developer: Correct the <typedefn> section so it meets RFC 3588 requirements. Content: refs in comments mayeb should be removed?-->
<variablelist>
<varlistentry>
<term><typedefn></term>
<listitem>
<para>
Defines the simple Attribute Value Pair (AVP) types. The element supports the following required attributes:
</para>
<variablelist>
<varlistentry>
<term>type-name</term>
<listitem>
<para>Specifies a type name in accordance with the acceptable base types defined in RFC 3588. For example; "Enumerated", "OctetString", "Integer32".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>type-parent</term>
<listitem>
<para>Specifies the parent type name used to define the base characteristics of the type. The values are restricted to defined <typedefn> elements. For example; "OctetString", "UTF8String", "IPAddress".</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<example id="example-Typedefn_XML_Attributes">
<title><typedefn> XML Attributes</title>
<programlisting role="XML"><!-- Primitive types, see http://tools.ietf.org/html/rfc3588#section-4.2 -->
<typedefn type-name="OctetString" />
<typedefn type-name="Float64" />
<typedefn type-name="Float32" />
<typedefn type-name="Integer64" />
<typedefn type-name="Integer32" />
<typedefn type-name="Unsigned64" />
<typedefn type-name="Unsigned32" />
<!-- derived avp types, see http://tools.ietf.org/html/rfc3588#section-4.3 -->
<typedefn type-name="Address" type-parent="OctetString" />
<typedefn type-name="Time" type-parent="OctetString" />
<typedefn type-name="UTF8String" type-parent="OctetString" />
<typedefn type-name="DiameterIdentity" type-parent="OctetString" /></programlisting>
</example>
<variablelist>
<varlistentry>
<term><application></term>
<listitem>
<para>
Defines the specific applications used within the dictionary. Two child elements are supported by <application>: <avp> and <command>.
</para>
<para>
The <application> element supports the following attributes:
</para>
<variablelist>
<varlistentry>
<term>id</term>
<listitem>
<para>Specifies the unique ID allocated to the application. The attribute is used in all messages and forms part of the message header.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>name</term>
<listitem>
<para>Optional attribute that specifies the logical name of the application.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>uri</term>
<listitem>
<para>Optional attribute that specifies a link to additional application information.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<example id="example-Application_XML_Attributes">
<title><application> XML Attributes</title>
<programlisting role="XML"><application id="16777216" name="3GPP Cx/Dx" uri="http://www.ietf.org/rfc/rfc3588.txt?number=3588"></programlisting>
</example>
<variablelist>
<varlistentry>
<term><avp></term>
<listitem>
<para>
Element containing information necessary to configure the Attribute Value Pairs. <xref linkend="table-avp_attributes"/> contains the complete list of supported attributes, and their available values (if applicable).
</para>
<para>
The <avp> element supports a number of child elements that are used to set finer parameters for the individual AVP. The supported elements are <type>, <enum>, and <grouped>.
</para>
<note>
<para>
Different sets of elements are supported by <avp> depending on its position in the dictionary.xml file.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<example id="example-Avp_Child_Elements_And_Attributes">
<title><avp> Child Elements and Attributes</title>
<programlisting role="XML"><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" />
<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="Line-Identifier" multiplicity="0+"/>
</grouped>
</avp></programlisting>
</example>
<variablelist>
<varlistentry>
<term><type></term>
<listitem>
<para>
Child element of <avp> that is used to match the AVP with the AVP type as defined in the <typedefn> element. The element supports the following mandatory attribute:
</para>
<variablelist>
<varlistentry>
<term>type-name</term>
<listitem>
<para>
Specifies the type-name of the element. This is used to match the type-name value in the <typedefn> element.
</para>
<note>
<para>
<type> is ignored if the <avp> element contains the <grouped> element.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><enum></term>
<listitem>
<para>
Child element of <avp> that specifies the enumeration value for the specified AVP. <enum> is used only when the type-name attribute of <type> is specified. The element supports the following mandatory attributes:
</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>Specifies the name of a constant value that applies to the AVP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>code</term>
<listitem>
<para>Specifies the integer value associated with the name of the constant. The value is passed as a value of the AVP, and maps to the name attribute.</para>
<note>
<para><enum> is ignored if the <avp> element contains the <grouped> element.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><grouped></term>
<listitem>
<para>
Child element of <avp> that specifies the AVP is a grouped type. A grouped AVP is one that has no <typedefn> element present. The element does not support any attributes, however the <gavp> element is allowed as a child element.
</para>
<para>
The <gavp>, which specifies a reference to a grouped AVP, supports one mandatory attribute:
</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>
Specifies the name of the grouped AVP member. The value must match the defined AVP name.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" pgwide="1" id="table-avp_attributes">
<title><avp> Attributes</title>
<tgroup cols="3" colsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<thead>
<row>
<entry>Attribute Name (optional in brackets)</entry>
<entry>Explicit Values (default in brackets)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry>
<entry/>
<entry>Specifies the name of the AVP. This is used to match the AVP definition to any grouped AVP references. For further information about grouped AVPs, refer to the element description in this section.</entry>
</row>
<row>
<entry>code</entry>
<entry/>
<entry>Specifies the integer code of the AVP.</entry>
</row>
<row>
<entry>(vendor-id)</entry>
<entry>(none)</entry>
<entry>Used to match the vendor ID reference to the value defined in the <vendor> element.</entry>
</row>
<row>
<entry>(multiplicity)</entry>
<entry/>
<entry>Specifies the number of acceptable AVPs in a message using an explicit value. </entry>
</row>
<row>
<entry/>
<entry>0</entry>
<entry>An AVP <emphasis>must not</emphasis> be present in the message.</entry>
</row>
<row>
<entry/>
<entry>(0+)</entry>
<entry>Zero or more instances of the AVP <emphasis>must be</emphasis> present in the message.</entry>
</row>
<row>
<entry/>
<entry>0-1</entry>
<entry>Zero, or one instance of the AVP <emphasis>may be</emphasis> present in the message. An error occurs if the message contains more than one instance of the AVP.</entry>
</row>
<row>
<entry/>
<entry>1</entry>
<entry>One instance of the AVP <emphasis>must be</emphasis> present in the message.</entry>
</row>
<row>
<entry/>
<entry>1+</entry>
<entry>At least one instance of the AVP <emphasis>must be</emphasis> present in the message.</entry>
</row>
<row>
<entry>may-encrypt</entry>
<entry>Yes | (No)</entry>
<entry>Specifies whether the AVP can be encrypted.</entry>
</row>
<row>
<entry>protected</entry>
<entry>may | must | mustnot</entry>
<entry>Determines actual state of AVP that is expected, if it MUST be encrypted , may or MUST NOT.</entry>
</row>
<row>
<entry>vendor-bit</entry>
<entry>must | mustnot</entry>
<entry>Specifies whether the Vendor ID should be set.</entry>
</row>
<row>
<entry>mandatory</entry>
<entry>may | must | mustnot</entry>
<entry>Determines if support for this AVP is mandatory in order to consume/process message.</entry>
</row>
<row>
<entry>vendor</entry>
<entry/>
<entry>Specifies the defined vendor code, which is used by the <command> child element.</entry>
</row>
</tbody>
</tgroup>
</table>
<example id="example-Avp_XML_Attributes">
<title><avp> XML Attributes</title>
<programlisting role="XML"><!-- MUST -->
<avp name="Session-Id" code="263" vendor="0" multiplicity="1" index="0" />
<avp name="Auth-Session-State" code="277" vendor="0" 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" />
<!-- 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" /></programlisting>
</example>
<variablelist>
<varlistentry>
<term><command></term>
<listitem>
<para>
Specifies the command for the application. The element supports the <avp> element, which specifies the structure of the command. The element supports the following attributes:
</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>
Optional parameter that specifies the message name for descriptive purposes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>code</term>
<listitem>
<para>
Mandatory parameter that specifies the integer code of the message.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>request</term>
<listitem>
<para>
Mandatory parameter that specifies whether the declared command is a request or answer. The available values are "true" (request) or "false" (answer).
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>If the <avp> element is specified in <command>, it does not support any child elements. The <avp> element only refers to defined AVPs when used in this context.</para>
</note>
<example id="example-Command_Elements_And_Attributes">
<title><command> Elements and Attributes</title>
<programlisting role="XML"><command name="User-Authorization" code="300" vendor-id="TGPP" request="true">
<avp name="Server-Assignment-Type" code="614" mandatory="must" vendor-bit="must" vendor-id="TGPP" may-encrypt="no"/>
</command></programlisting>
</example>
</section>
© 2015 - 2025 Weber Informatics LLC | Privacy Policy