Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Thursday, June 13, 2019
 
 

diameter_dict (5erl)

Name

diameter_dict - Dictionary interface of the diameter application.

Synopsis

Please see following description for synopsis

Description

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
       decode its messages and AVPs. The dictionary module is in  turn  gener-
       ated  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  specific  applications  by  creating dictionary files, compiling
       them to Erlang modules using either  diameterc(1)  or  diameter_make(3)
       and configuring 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(3).  These  records and the underlying Erlang data types corre-
       sponding to Diameter data formats are discussed in MESSAGE RECORDS  and
       DATA  TYPES respectively. The generated hrl also contains macro defini-
       tions 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
       insignificant.

       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
           required 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(encode|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
       request 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
       tuple()  has  length  8 and contains values of type 0..65535. The tuple
       representation 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
       extension  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(3),  diameter_app(3), diameter_codec(3), diame-
       ter_make(3)



Ericsson AB                     diameter 2.1.5                diameter_dict(5)