diameter_dict(5) Files diameter_dict(5)
NAME
diameter_dict - Dictionary interface of the diameter application.
DESCRIPTION
A diameter service, as configured with diameter:start_service/2, speci-
fies one or more supported Diameter applications. Each Diameter appli-
cation specifies a dictionary module that knows how to encode and de-
code 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 FILE FORMAT below. Users add support for their spe-
cific applications by creating dictionary files, compiling them to Er-
lang modules using either diameterc(1) or diameter_make(3erl) and con-
figuring the resulting dictionaries modules on a service.
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 diame-
ter_app(3erl). These records and the underlying Erlang data types cor-
responding to Diameter data formats are discussed in MESSAGE RECORDS
and DATA TYPES respectively. The generated hrl also contains macro def-
initions for the possible values of AVPs of type Enumerated.
The diameter application includes five dictionary modules corresponding
to applications defined in section 2.4 of RFC 6733: diame-
ter_gen_base_rfc3588 and diameter_gen_base_rfc6733 for the Diameter
Common Messages application with application identifier 0, diame-
ter_gen_accounting (for RFC 3588) and diameter_gen_acct_rfc6733 for the
Diameter Base Accounting application with application identifier 3 and
diameter_gen_relay the Relay application with application identifier
0xFFFFFFFF.
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.
FILE FORMAT
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 char-
acter followed by a keyword and are separated from their arguments by
whitespace. Whitespace separates individual tokens but is otherwise in-
significant.
The tags, their arguments and the contents of each corresponding sec-
tion are as follows. Each section can occur multiple times unless oth-
erwise specified. The order in which sections are specified is unimpor-
tant.
@id Number:
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 @messages. The section has empty content.
The Application Id is set in the Diameter Header of outgoing mes-
sages of the application, and the value in the header of an incom-
ing message is used to identify the relevant dictionary module.
Example:
@id 16777231
@name Mod:
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.
Note that a dictionary module should have a unique name so as not
collide with existing modules in the system.
Example:
@name etsi_e2
@prefix Name:
Defines Name as the prefix to be added to record and constant names
(followed by a '_' character) in the generated dictionary module
and hrl. Can occur at most once. The section has empty content.
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.
Example:
@prefix etsi_e2
@vendor Number Name:
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 applica-
tion but is otherwise unused. Can occur at most once and is re-
quired if an AVP sets the V flag and is not otherwise assigned a
Vendor-Id. The section has empty content.
Example:
@vendor 13019 ETSI
@avp_vendor_id Number:
Defines the integer Number as the Vendor-Id of the AVPs listed in
the section content, overriding the @vendor default. The section
content consists of AVP names.
Example:
@avp_vendor_id 2937
WWW-Auth
Domain-Index
Region-Set
@inherits Mod:
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.
Note that an inherited AVP that sets the V flag takes its Vendor-Id
from either @avp_vendor_id in the inheriting dictionary or @vendor
in the inherited dictionary. In particular, @avp_vendor_id in the
inherited dictionary is ignored. Inheriting from a dictionary that
specifies the required @vendor is equivalent to using @avp_ven-
dor_id with a copy of the dictionary's definitions but the former
makes for easier reuse.
All dictionaries should typically inherit RFC 6733 AVPs from diame-
ter_gen_base_rfc6733.
Example:
@inherits diameter_gen_base_rfc6733
@avp_types:
Defines the name, code, type and flags of individual AVPs. The sec-
tion consists of definitions of the form
Name Code Type Flags
where Code is the integer AVP code, Type identifies an AVP Data
Format as defined in section DATA 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 '-' (minus) character if none are to be
set.
Example:
@avp_types
Location-Information 350 Grouped MV
Requested-Information 353 Enumerated V
Warning:
The P flag has been deprecated by RFC 6733.
@custom_types Mod:
Specifies AVPs for which module Mod provides encode/decode func-
tions. The section contents consists of AVP names. For each such
name, Mod:Name(encode|decode, Type, Data, Opts) is expected to pro-
vide encode/decode for values of the AVP, where Name is the name of
the AVP, Type is it's type as declared in the @avp_types section of
the dictionary, Data is the value to encode/decode, and Opts is a
term that is passed through encode/decode.
Example:
@custom_types rfc4005_avps
Framed-IP-Address
@codecs Mod:
Like @custom_types but requires the specified module to export
Mod:Type(encode|decode, Name, Data, Opts) rather than Mod:Name(en-
code|decode, Type, Data, Opts).
Example:
@codecs rfc4005_avps
Framed-IP-Address
@messages:
Defines the messages of the application. The section content con-
sists of definitions of the form specified in section 3.2 of RFC
6733, "Command Code Format Specification".
@messages
RTR ::= < Diameter Header: 287, REQ, PXY >
< 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 ::= < Diameter Header: 287, PXY >
< 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 ]
@grouped:
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 RFC 6733, "Grouped AVP Values".
Example:
@grouped
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
Specifying a Vendor-Id in the definition of a grouped AVP is equiv-
alent to specifying it with @avp_vendor_id.
@enum Name:
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.
Note that the AVP in question can be defined in an inherited dic-
tionary in order to introduce additional values to an enumeration
otherwise defined in another dictionary.
Example:
@enum SIP-Reason-Code
PERMANENT_TERMINATION 0
NEW_SIP_SERVER_ASSIGNED 1
SIP_SERVER_CHANGE 2
REMOVE_SIP_SERVER 3
@end:
Causes parsing of the dictionary to terminate: any remaining con-
tent is ignored.
Comments can be included in a dictionary file using semicolon: charac-
ters from a semicolon to end of line are ignored.
MESSAGE RECORDS
The hrl generated from a dictionary specification defines records for
the messages and grouped AVPs defined in @messages and @grouped sec-
tions. 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 @prefix, 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
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
will result in the following record definition given an empty prefix.
-record('SIP-Deregistration-Reason', {'SIP-Reason-Code',
'SIP-Reason-Info',
'AVP'}).
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 RFC 6733 types being described below.
DATA TYPES
The data formats defined in sections 4.2 ("Basic AVP Data Formats") and
4.3 ("Derived AVP Data Formats") of RFC 6733 are encoded as values of
the types defined here. Values are passed to diameter:call/4 in a re-
quest record when sending a request, returned in a resulting answer
record and passed to a handle_request/3 callback upon reception of an
incoming request.
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 diameter:service_opt() string_decode.
Basic AVP Data Formats
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()
On encode, an OctetString() can be specified as an iolist(), exces-
sively large floats (in absolute value) are equivalent to infinity or
'-infinity' and excessively large integers result in encode failure.
The records for grouped AVPs are as discussed in the previous section.
Derived AVP Data Formats
Address() = OctetString()
| tuple()
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 tu-
ple() has length 8 and contains values of type 0..65535. The tuple rep-
resentation is used on decode.
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
Additionally, values that can be encoded are limited by way of their
encoding as four octets as required by RFC 6733 with the required ex-
tension from RFC 2030. In particular, only values between
{{1968,1,20},{3,14,8}} and {{2104,2,26},{9,42,23}} (both inclusive) can
be encoded.
UTF8String() = [integer()] | binary()
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.
DiameterIdentity() = OctetString()
A value must have length at least 1.
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+'
On encode, fields port, transport and protocol default to 3868, sctp
and diameter respectively. The grammar of an OctetString-valued Diame-
terURI() is as specified in section 4.3 of RFC 6733. The record repre-
sentation is used on decode.
Enumerated() = Integer32()
On encode, values can be specified using the macros defined in a dic-
tionary's hrl file.
IPFilterRule() = OctetString()
QoSFilterRule() = OctetString()
Values of these types are not currently parsed by diameter.
SEE ALSO
diameterc(1), diameter(3erl), diameter_app(3erl), diameter_codec(3erl),
diameter_make(3erl)
Ericsson AB diameter 2.2.3 diameter_dict(5)