Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, February 10, 2021
 
 

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) 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 @avp_types section of the
           dictionary and Data is the value to 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)      rather      than
           Mod:Name(encode|decode, Type, Data).

           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 1.12.2               diameter_dict(5)