doc/src/diameter_dict.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE fileref SYSTEM "fileref.dtd" [
  <!ENTITY format
           '<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso>'>
  <!ENTITY records
           '<seealso marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso>'>
  <!ENTITY types
           '<seealso marker="#DATA_TYPES">DATA TYPES</seealso>'>
  <!ENTITY % also SYSTEM "seealso.ent" >
  <!ENTITY % here SYSTEM "seehere.ent" >
  %also;
  %here;
]>

<fileref>
<header>

<copyright>
<year>2011</year>
<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

</legalnotice>

<title>diameter_dict(4)</title>
<prepared>Anders Svensson</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>%VSN%</rev>
<file>diameter_dict.xml</file>
</header>

<!-- ===================================================================== -->

<file>diameter_dict</file>
<filesummary>Dictionary interface of the diameter application.</filesummary>

<description>
<p>
A diameter service, as configured with &mod_start_service;,
specifies one or more supported Diameter applications.
Each Diameter application specifies a dictionary module that knows how
to encode and decode its messages and AVPs.
The dictionary module is in turn generated from a file that defines
these messages and AVPs.
The format of such a file is defined in &format; below.
Users add support for their specific applications by creating
dictionary files, compiling them to Erlang modules using
either &man_compile; or &man_make; and configuring the
resulting dictionaries modules on a service.</p>

<p>
Dictionary module generation also results in a hrl file that defines
records for the messages and Grouped AVPs defined by the
dictionary, these records being what a user of the diameter
application sends and receives, modulo other possible formats as
discussed in &man_app;.
These records and the underlying Erlang data types corresponding to
Diameter data formats are discussed in &records; and &types;
respectively.
The generated hrl also contains macro definitions for the possible values of
AVPs of type Enumerated.</p>

<p>
The diameter application includes five dictionary modules
corresponding to applications defined in section 2.4 of &the_rfc;:
<c>diameter_gen_base_rfc3588</c> and <c>diameter_gen_base_rfc6733</c>
for the Diameter Common Messages application with application
identifier 0,
<c>diameter_gen_accounting</c> (for RFC 3588) and
<c>diameter_gen_acct_rfc6733</c> for the Diameter Base Accounting
application with application identifier 3 and
<c>diameter_gen_relay</c> the Relay application with application
identifier 0xFFFFFFFF.</p>

<p>
The Common Message and Relay applications are the only applications
that diameter itself has any specific knowledge of.
The Common Message application is used for messages that diameter
itself handles: CER/CEA, DWR/DWA and DPR/DPA.
The Relay application is given special treatment with regard to
encode/decode since the messages and AVPs it handles are not specifically
defined.</p>

<marker id="FILE_FORMAT"/>
</description>

<!-- ===================================================================== -->

<section>
<title>FILE FORMAT</title>

<p>
A dictionary file consists of distinct sections.
Each section starts with a tag followed by zero or more arguments
and ends at the the start of the next section or end of file.
Tags consist of an ampersand character followed by a keyword and are
separated from their arguments by whitespace.
Whitespace separates individual tokens but is otherwise insignificant.</p>

<p>
The tags, their arguments and the contents of each corresponding
section are as follows.
Each section can occur multiple times unless otherwise specified.
The order in which sections are specified is unimportant.</p>

<taglist>

<tag>
<marker id="id"/><c>@id Number</c></tag>
<item>
<p>
Defines the integer Number as the Diameter Application Id of the
application in question.
Can occur at most once and is required if the dictionary defines
<c>@messages</c>.
The section has empty content.</p>

<p>
The Application Id is set in the Diameter Header of outgoing messages
of the application, and the value in the header of an incoming message
is used to identify the relevant dictionary module.</p>

<p>
Example:</p>

<pre>
@id 16777231
</pre>

</item>

<tag>
<marker id="name"/><c>@name Mod</c></tag>
<item>
<p>
Defines the name of the generated dictionary module.
Can occur at most once and defaults to the name of the dictionary file
minus any extension.
The section has empty content.</p>

<p>
Note that a dictionary module should have a unique name so as not collide
with existing modules in the system.</p>

<p>
Example:</p>

<pre>
@name etsi_e2
</pre>

</item>

<tag>
<marker id="prefix"/><c>@prefix Name</c></tag>
<item>
<p>
Defines Name as the prefix to be added to record and constant names
(followed by a <c>'_'</c> character) in the generated dictionary
module and hrl.
Can occur at most once.
The section has empty content.</p>

<p>
A prefix is optional but can be be used to disambiguate between record
and constant names resulting from similarly named messages and AVPs in
different Diameter applications.</p>

<p>
Example:</p>

<pre>
@prefix etsi_e2
</pre>

</item>

<tag>
<marker id="vendor"/><c>@vendor Number Name</c></tag>
<item>
<p>
Defines the integer Number as the the default Vendor-Id of AVPs for
which the V flag is set.
Name documents the owner of the application
but is otherwise unused.
Can occur at most once and is required if an AVP sets the V flag and
is not otherwise assigned a Vendor-Id.
The section has empty content.</p>

<p>
Example:</p>

<pre>
@vendor 13019 ETSI
</pre>

</item>

<tag>
<marker id="avp_vendor_id"/><c>@avp_vendor_id Number</c></tag>
<item>
<p>
Defines the integer Number as the Vendor-Id of the AVPs listed in the
section content, overriding the <c>@vendor</c> default.
The section content consists of AVP names.</p>

<p>
Example:</p>

<pre>
@avp_vendor_id 2937

WWW-Auth
Domain-Index
Region-Set
</pre>

</item>

<tag>
<marker id="inherits"/><c>@inherits Mod</c></tag>
<item>
<p>
Defines the name of a dictionary module containing AVP
definitions that should be imported into the current dictionary.
The section content consists of the names of those AVPs whose
definitions should be imported from the dictionary, an empty list
causing all to be imported.
Any listed AVPs must not be defined in the current dictionary and
it is an error to inherit the same AVP from more than one
dictionary.</p>

<p>
Note that an inherited AVP that sets the V flag takes its Vendor-Id
from either <c>@avp_vendor_id</c> in the inheriting dictionary or
<c>@vendor</c> in the inherited dictionary.
In particular, <c>@avp_vendor_id</c> in the inherited dictionary is
ignored.
Inheriting from a dictionary that specifies the required <c>@vendor</c>
is equivalent to using <c>@avp_vendor_id</c> with a copy of the
dictionary's definitions but the former makes for easier reuse.</p>

<p>
All dictionaries should typically inherit &the_rfc; AVPs from
<c>diameter_gen_base_rfc6733</c>.</p>

<p>
Example:</p>

<pre>
@inherits diameter_gen_base_rfc6733
</pre>
</item>

<tag>
<marker id="avp_types"/><c>@avp_types</c></tag>
<item>
<p>
Defines the name, code, type and flags of individual AVPs.
The section consists of definitions of the form</p>

<p><c>Name Code Type Flags</c></p>

<p>
where Code is the integer AVP code, Type identifies an AVP Data Format
as defined in section &types; below,
and Flags is a string of V, M and P characters indicating the flags to be
set on an outgoing AVP or a single <c>'-'</c> (minus) character if
none are to be set.</p>

<p>
Example:</p>

<pre>
@avp_types

Location-Information   350  Grouped     MV
Requested-Information  353  Enumerated   V
</pre>

<warning>
<p>
The P flag has been deprecated by &the_rfc;.</p>
</warning>

</item>

<tag>
<marker id="custom_types"/><c>@custom_types Mod</c></tag>
<item>
<p>
Specifies AVPs for which module Mod provides encode/decode functions.
The section contents consists of AVP names.
For each such name, <c>Mod:Name(encode|decode, Type, Data, Opts)</c> is
expected to provide encode/decode for values of the AVP, where Name is
the name of the AVP, Type is it's type as declared in the
<c>@avp_types</c> section of the dictionary, Data is the value to
encode/decode, and Opts is a term that is passed through encode/decode.</p>

<p>
Example:</p>

<pre>
@custom_types rfc4005_avps

Framed-IP-Address
</pre>
</item>

<tag>
<marker id="codecs"/><c>@codecs Mod</c></tag>
<item>
<p>
Like <c>@custom_types</c> but requires the specified module to export
<c>Mod:Type(encode|decode, Name, Data, Opts)</c> rather than
<c>Mod:Name(encode|decode, Type, Data, Opts)</c>.</p>

<p>
Example:</p>

<pre>
@codecs rfc4005_avps

Framed-IP-Address
</pre>
</item>

<tag>
<marker id="messages"/><c>@messages</c></tag>
<item>
<p>
Defines the messages of the application.
The section content consists of definitions of the form specified in
section 3.2 of &the_rfc;, "Command Code Format Specification".</p>

<!-- RFC 4740 RTR/RTA -->
<pre>
@messages

RTR ::= &lt; Diameter Header: 287, REQ, PXY >
        &lt; Session-Id >
        { Auth-Application-Id }
        { Auth-Session-State }
        { Origin-Host }
        { Origin-Realm }
        { Destination-Host }
        { SIP-Deregistration-Reason }
        [ Destination-Realm ]
        [ User-Name ]
      * [ SIP-AOR ]
      * [ Proxy-Info ]
      * [ Route-Record ]
      * [ AVP ]

RTA ::= &lt; Diameter Header: 287, PXY >
        &lt; Session-Id >
        { Auth-Application-Id }
        { Result-Code }
        { Auth-Session-State }
        { Origin-Host }
        { Origin-Realm }
        [ Authorization-Lifetime ]
        [ Auth-Grace-Period ]
        [ Redirect-Host ]
        [ Redirect-Host-Usage ]
        [ Redirect-Max-Cache-Time ]
      * [ Proxy-Info ]
      * [ Route-Record ]
      * [ AVP ]
</pre>

</item>

<tag>
<marker id="grouped"/><c>@grouped</c></tag>
<item>
<p>
Defines the contents of the AVPs of the application having type
Grouped.
The section content consists of definitions of the form specified in
section 4.4 of &the_rfc;, "Grouped AVP Values".</p>

<p>
Example:</p>

<pre>
@grouped

SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
                              { SIP-Reason-Code }
                              [ SIP-Reason-Info ]
                            * [ AVP ]
</pre>

<p>
Specifying a Vendor-Id in the definition of a grouped AVP is
equivalent to specifying it with <c>@avp_vendor_id</c>.</p>
</item>

<tag>
<marker id="enum"/><c>@enum Name</c></tag>
<item>
<p>
Defines values of AVP Name having type Enumerated.
Section content consists of names and corresponding integer values.
Integer values can be prefixed with 0x to be interpreted as
hexadecimal.</p>

<p>
Note that the AVP in question can be defined in an inherited
dictionary in order to introduce additional values to an enumeration
otherwise defined in another dictionary.</p>

<p>
Example:</p>

<pre>
@enum SIP-Reason-Code

PERMANENT_TERMINATION    0
NEW_SIP_SERVER_ASSIGNED  1
SIP_SERVER_CHANGE        2
REMOVE_SIP_SERVER        3
</pre>
</item>

<tag>
<marker id="end"/><c>@end</c></tag>
<item>
<p>
Causes parsing of the dictionary to terminate:
any remaining content is ignored.</p>
</item>

</taglist>

<p>
Comments can be included in a dictionary file using semicolon:
characters from a semicolon to end of line are ignored.</p>

<marker id="MESSAGE_RECORDS"/>
</section>

<!-- ===================================================================== -->

<section>
<title>MESSAGE RECORDS</title>

<p>
The hrl generated from a dictionary specification defines records for the
messages and grouped AVPs defined in <c>@messages</c> and
<c>@grouped</c> sections.
For each message or grouped AVP definition, a record is defined whose
name is the message or AVP name, prefixed with any dictionary prefix
defined with <c>@prefix</c>, and whose fields are the names of the AVPs
contained in the message or grouped AVP in the order specified in the
definition in question.
For example, the grouped AVP</p>

<pre>
SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
                              { SIP-Reason-Code }
                              [ SIP-Reason-Info ]
                            * [ AVP ]
</pre>

<p>
will result in the following record definition given an empty
prefix.</p>

<pre>
-record('SIP-Deregistration-Reason', {'SIP-Reason-Code',
                                      'SIP-Reason-Info',
                                      'AVP'}).
</pre>

<p>
The values encoded in the fields of generated records depends on the
type and number of times the AVP can occur.
In particular, an AVP which is specified as occurring exactly once is
encoded as a value of the AVP's type while an AVP with any other
specification is encoded as a list of values of the AVP's type.
The AVP's type is as specified in the AVP definition, the &the_rfc;
types being described below.</p>

<marker id="DATA_TYPES"/>
</section>

<!-- ===================================================================== -->

<section>
<title>DATA TYPES</title>

<p>
The data formats defined in sections 4.2 ("Basic AVP Data
Formats") and 4.3 ("Derived AVP Data Formats") of &the_rfc; are encoded
as values of the types defined here.
Values are passed to &mod_call;
in a request record when sending a request, returned in a resulting
answer record and passed to a &app_handle_request;
callback upon reception of an incoming request.</p>

<p>
In cases in which there is a choice between string() and binary() types
for OctetString() and derived types, the representation is determined
by the value of &mod_string_decode;.</p>

<p>
<em>Basic AVP Data Formats</em></p>

<marker id="OctetString"/>
<marker id="Integer32"/>
<marker id="Integer64"/>
<marker id="Unsigned32"/>
<marker id="Unsigned64"/>
<marker id="Float32"/>
<marker id="Float64"/>
<marker id="Grouped"/>

<pre>
OctetString() = string() | binary()
Integer32()   = -2147483647..2147483647
Integer64()   = -9223372036854775807..9223372036854775807
Unsigned32()  = 0..4294967295
Unsigned64()  = 0..18446744073709551615
Float32()     = '-infinity' | float() | infinity
Float64()     = '-infinity' | float() | infinity
Grouped()     = record()
</pre>

<p>
On encode, an OctetString() can be specified as an iolist(),
excessively large floats (in absolute value) are equivalent to
<c>infinity</c> or <c>'-infinity'</c> and excessively large integers
result in encode failure.
The records for grouped AVPs are as discussed in the previous
section.</p>

<p>
<em>Derived AVP Data Formats</em></p>

<marker id="Address"/>
<pre>
Address() = OctetString()
          | tuple()
</pre>

<p>
On encode, an OctetString() IPv4 address is parsed in the usual
x.x.x.x format while an IPv6 address is parsed in any of the formats
specified by section  2.2 of RFC 2373, "Text Representation of
Addresses".
An IPv4 tuple() has length 4 and contains values of type 0..255.
An IPv6 tuple() has length 8 and contains values of type 0..65535.
The tuple representation is used on decode.</p>

<marker id="Time"/>
<pre>
Time() = {date(), time()}

where

  date() = {Year, Month, Day}
  time() = {Hour, Minute, Second}

  Year   = integer()
  Month  = 1..12
  Day    = 1..31
  Hour   = 0..23
  Minute = 0..59
  Second = 0..59
</pre>

<p>
Additionally, values that can be encoded are
limited by way of their encoding as four octets as required by
&the_rfc; with the required extension from RFC 2030.
In particular, only values between <c>{{1968,1,20},{3,14,8}}</c>
and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p>

<marker id="UTF8String"/>
<pre>
UTF8String() = [integer()] | binary()
</pre>

<p>
List elements are the UTF-8 encodings of the individual characters
in the string.
Invalid codepoints will result in encode/decode failure.
On encode, a UTF8String() can be specified as a binary, or as a nested
list of binaries and codepoints.</p>

<marker id="DiameterIdentity"/>
<pre>
DiameterIdentity() = OctetString()
</pre>

<p>
A value must have length at least 1.</p>

<marker id="DiameterURI"/>
<pre>
DiameterURI() = OctetString()
              | #diameter_URI{type = Type,
                              fqdn = FQDN,
                              port = Port,
                              transport = Transport,
                              protocol  = Protocol}

where

  Type = aaa | aaas
  FQDN = OctetString()
  Port = integer()
  Transport = sctp | tcp
  Protocol  = diameter | radius | 'tacacs+'
</pre>

<p>
On encode, fields port, transport and protocol default to 3868, sctp
and diameter respectively.
The grammar of an OctetString-valued DiameterURI() is as specified in
section 4.3 of &the_rfc;.
The record representation is used on decode.</p>

<marker id="Enumerated"/>
<pre>
Enumerated() = Integer32()
</pre>

<p>
On encode, values can be specified using the macros defined in a
dictionary's hrl file.</p>

<marker id="IPFilterRule"/>
<marker id="QoSFilterRule"/>
<pre>
IPFilterRule()  = OctetString()
QoSFilterRule() = OctetString()
</pre>

<p>
Values of these types are not currently parsed by diameter.</p>

</section>

<!-- ===================================================================== -->
<!-- ===================================================================== -->

<section>
<title>SEE ALSO</title>

<p>
&man_compile;, &man_main;, &man_app;, &man_codec;, &man_make;</p>

</section>

</fileref>