1diameter_dict(5)                     Files                    diameter_dict(5)
2
3
4

NAME

6       diameter_dict - Dictionary interface of the diameter application.
7

DESCRIPTION

9       A diameter service, as configured with diameter:start_service/2, speci‐
10       fies one or more supported Diameter applications. Each Diameter  appli‐
11       cation  specifies  a dictionary module that knows how to encode and de‐
12       code its messages and AVPs. The dictionary module is in turn  generated
13       from  a file that defines these messages and AVPs. The format of such a
14       file is defined in FILE FORMAT below. Users add support for their  spe‐
15       cific  applications by creating dictionary files, compiling them to Er‐
16       lang modules using either diameterc(1) or diameter_make(3) and  config‐
17       uring the resulting dictionaries modules on a service.
18
19       Dictionary  module  generation  also results in a hrl file that defines
20       records for the messages and Grouped AVPs defined  by  the  dictionary,
21       these  records  being what a user of the diameter application sends and
22       receives,  modulo  other  possible  formats  as  discussed  in   diame‐
23       ter_app(3).  These  records and the underlying Erlang data types corre‐
24       sponding to Diameter data formats are discussed in MESSAGE RECORDS  and
25       DATA  TYPES respectively. The generated hrl also contains macro defini‐
26       tions for the possible values of AVPs of type Enumerated.
27
28       The diameter application includes five dictionary modules corresponding
29       to   applications   defined   in   section  2.4  of  RFC  6733:  diame‐
30       ter_gen_base_rfc3588 and  diameter_gen_base_rfc6733  for  the  Diameter
31       Common  Messages  application  with  application  identifier  0, diame‐
32       ter_gen_accounting (for RFC 3588) and diameter_gen_acct_rfc6733 for the
33       Diameter  Base Accounting application with application identifier 3 and
34       diameter_gen_relay the Relay application  with  application  identifier
35       0xFFFFFFFF.
36
37       The  Common  Message  and  Relay applications are the only applications
38       that diameter itself has any specific knowledge of. The Common  Message
39       application is used for messages that diameter itself handles: CER/CEA,
40       DWR/DWA and DPR/DPA. The Relay application is given  special  treatment
41       with regard to encode/decode since the messages and AVPs it handles are
42       not specifically defined.
43

FILE FORMAT

45       A dictionary file consists of distinct sections.  Each  section  starts
46       with a tag followed by zero or more arguments and ends at the the start
47       of the next section or end of file. Tags consist of an ampersand  char‐
48       acter  followed  by a keyword and are separated from their arguments by
49       whitespace. Whitespace separates individual tokens but is otherwise in‐
50       significant.
51
52       The  tags,  their arguments and the contents of each corresponding sec‐
53       tion are as follows. Each section can occur multiple times unless  oth‐
54       erwise specified. The order in which sections are specified is unimpor‐
55       tant.
56
57         @id Number:
58           Defines the integer Number as the Diameter Application  Id  of  the
59           application  in question. Can occur at most once and is required if
60           the dictionary defines @messages. The section has empty content.
61
62           The Application Id is set in the Diameter Header of  outgoing  mes‐
63           sages  of the application, and the value in the header of an incom‐
64           ing message is used to identify the relevant dictionary module.
65
66           Example:
67
68         @id 16777231
69
70
71         @name Mod:
72           Defines the name of the generated dictionary module. Can  occur  at
73           most once and defaults to the name of the dictionary file minus any
74           extension. The section has empty content.
75
76           Note that a dictionary module should have a unique name so  as  not
77           collide with existing modules in the system.
78
79           Example:
80
81         @name etsi_e2
82
83
84         @prefix Name:
85           Defines Name as the prefix to be added to record and constant names
86           (followed by a '_' character) in the  generated  dictionary  module
87           and hrl. Can occur at most once. The section has empty content.
88
89           A  prefix  is  optional  but can be be used to disambiguate between
90           record and constant names resulting from similarly  named  messages
91           and AVPs in different Diameter applications.
92
93           Example:
94
95         @prefix etsi_e2
96
97
98         @vendor Number Name:
99           Defines the integer Number as the the default Vendor-Id of AVPs for
100           which the V flag is set. Name documents the owner of  the  applica‐
101           tion  but  is  otherwise  unused. Can occur at most once and is re‐
102           quired if an AVP sets the V flag and is not  otherwise  assigned  a
103           Vendor-Id. The section has empty content.
104
105           Example:
106
107         @vendor 13019 ETSI
108
109
110         @avp_vendor_id Number:
111           Defines  the  integer Number as the Vendor-Id of the AVPs listed in
112           the section content, overriding the @vendor  default.  The  section
113           content consists of AVP names.
114
115           Example:
116
117         @avp_vendor_id 2937
118
119         WWW-Auth
120         Domain-Index
121         Region-Set
122
123
124         @inherits Mod:
125           Defines  the name of a dictionary module containing AVP definitions
126           that should be imported into the current  dictionary.  The  section
127           content  consists  of  the  names  of  those AVPs whose definitions
128           should be imported from the dictionary, an empty list  causing  all
129           to  be imported. Any listed AVPs must not be defined in the current
130           dictionary and it is an error to inherit the  same  AVP  from  more
131           than one dictionary.
132
133           Note that an inherited AVP that sets the V flag takes its Vendor-Id
134           from either @avp_vendor_id in the inheriting dictionary or  @vendor
135           in  the  inherited dictionary. In particular, @avp_vendor_id in the
136           inherited dictionary is ignored. Inheriting from a dictionary  that
137           specifies  the  required  @vendor  is equivalent to using @avp_ven‐
138           dor_id with a copy of the dictionary's definitions but  the  former
139           makes for easier reuse.
140
141           All dictionaries should typically inherit RFC 6733 AVPs from diame‐
142           ter_gen_base_rfc6733.
143
144           Example:
145
146         @inherits diameter_gen_base_rfc6733
147
148
149         @avp_types:
150           Defines the name, code, type and flags of individual AVPs. The sec‐
151           tion consists of definitions of the form
152
153           Name Code Type Flags
154
155           where  Code  is  the  integer AVP code, Type identifies an AVP Data
156           Format as defined in section DATA  TYPES  below,  and  Flags  is  a
157           string  of  V, M and P characters indicating the flags to be set on
158           an outgoing AVP or a single '-' (minus) character if none are to be
159           set.
160
161           Example:
162
163         @avp_types
164
165         Location-Information   350  Grouped     MV
166         Requested-Information  353  Enumerated   V
167
168
169     Warning:
170         The P flag has been deprecated by RFC 6733.
171
172
173         @custom_types Mod:
174           Specifies  AVPs  for  which module Mod provides encode/decode func‐
175           tions. The section contents consists of AVP names.  For  each  such
176           name, Mod:Name(encode|decode, Type, Data, Opts) is expected to pro‐
177           vide encode/decode for values of the AVP, where Name is the name of
178           the AVP, Type is it's type as declared in the @avp_types section of
179           the dictionary, Data is the value to encode/decode, and Opts  is  a
180           term that is passed through encode/decode.
181
182           Example:
183
184         @custom_types rfc4005_avps
185
186         Framed-IP-Address
187
188
189         @codecs Mod:
190           Like  @custom_types  but  requires  the  specified module to export
191           Mod:Type(encode|decode, Name, Data, Opts) rather than  Mod:Name(en‐
192           code|decode, Type, Data, Opts).
193
194           Example:
195
196         @codecs rfc4005_avps
197
198         Framed-IP-Address
199
200
201         @messages:
202           Defines  the  messages of the application. The section content con‐
203           sists of definitions of the form specified in section  3.2  of  RFC
204           6733, "Command Code Format Specification".
205
206         @messages
207
208         RTR ::= < Diameter Header: 287, REQ, PXY >
209                 < Session-Id >
210                 { Auth-Application-Id }
211                 { Auth-Session-State }
212                 { Origin-Host }
213                 { Origin-Realm }
214                 { Destination-Host }
215                 { SIP-Deregistration-Reason }
216                 [ Destination-Realm ]
217                 [ User-Name ]
218               * [ SIP-AOR ]
219               * [ Proxy-Info ]
220               * [ Route-Record ]
221               * [ AVP ]
222
223         RTA ::= < Diameter Header: 287, PXY >
224                 < Session-Id >
225                 { Auth-Application-Id }
226                 { Result-Code }
227                 { Auth-Session-State }
228                 { Origin-Host }
229                 { Origin-Realm }
230                 [ Authorization-Lifetime ]
231                 [ Auth-Grace-Period ]
232                 [ Redirect-Host ]
233                 [ Redirect-Host-Usage ]
234                 [ Redirect-Max-Cache-Time ]
235               * [ Proxy-Info ]
236               * [ Route-Record ]
237               * [ AVP ]
238
239
240         @grouped:
241           Defines  the  contents  of  the AVPs of the application having type
242           Grouped. The section content consists of definitions  of  the  form
243           specified in section 4.4 of RFC 6733, "Grouped AVP Values".
244
245           Example:
246
247         @grouped
248
249         SIP-Deregistration-Reason ::= < AVP Header: 383 >
250                                       { SIP-Reason-Code }
251                                       [ SIP-Reason-Info ]
252                                     * [ AVP ]
253
254
255           Specifying a Vendor-Id in the definition of a grouped AVP is equiv‐
256           alent to specifying it with @avp_vendor_id.
257
258         @enum Name:
259           Defines values of AVP Name having type Enumerated. Section  content
260           consists  of names and corresponding integer values. Integer values
261           can be prefixed with 0x to be interpreted as hexadecimal.
262
263           Note that the AVP in question can be defined in an  inherited  dic‐
264           tionary  in  order to introduce additional values to an enumeration
265           otherwise defined in another dictionary.
266
267           Example:
268
269         @enum SIP-Reason-Code
270
271         PERMANENT_TERMINATION    0
272         NEW_SIP_SERVER_ASSIGNED  1
273         SIP_SERVER_CHANGE        2
274         REMOVE_SIP_SERVER        3
275
276
277         @end:
278           Causes parsing of the dictionary to terminate: any  remaining  con‐
279           tent is ignored.
280
281       Comments  can be included in a dictionary file using semicolon: charac‐
282       ters from a semicolon to end of line are ignored.
283

MESSAGE RECORDS

285       The hrl generated from a dictionary specification defines  records  for
286       the  messages  and  grouped AVPs defined in @messages and @grouped sec‐
287       tions. For each message or grouped AVP definition, a record is  defined
288       whose  name  is  the  message or AVP name, prefixed with any dictionary
289       prefix defined with @prefix, and whose fields are the names of the AVPs
290       contained  in  the message or grouped AVP in the order specified in the
291       definition in question. For example, the grouped AVP
292
293       SIP-Deregistration-Reason ::= < AVP Header: 383 >
294                                     { SIP-Reason-Code }
295                                     [ SIP-Reason-Info ]
296                                   * [ AVP ]
297
298
299       will result in the following record definition given an empty prefix.
300
301       -record('SIP-Deregistration-Reason', {'SIP-Reason-Code',
302                                             'SIP-Reason-Info',
303                                             'AVP'}).
304
305
306       The values encoded in the fields of generated records  depends  on  the
307       type and number of times the AVP can occur. In particular, an AVP which
308       is specified as occurring exactly once is encoded as  a  value  of  the
309       AVP's  type  while  an AVP with any other specification is encoded as a
310       list of values of the AVP's type. The AVP's type is as specified in the
311       AVP definition, the RFC 6733 types being described below.
312

DATA TYPES

314       The data formats defined in sections 4.2 ("Basic AVP Data Formats") and
315       4.3 ("Derived AVP Data Formats") of RFC 6733 are encoded as  values  of
316       the  types  defined here. Values are passed to diameter:call/4 in a re‐
317       quest record when sending a request, returned  in  a  resulting  answer
318       record  and  passed to a handle_request/3 callback upon reception of an
319       incoming request.
320
321       In cases in which there is a choice between string() and binary() types
322       for  OctetString()  and derived types, the representation is determined
323       by the value of diameter:service_opt() string_decode.
324
325       Basic AVP Data Formats
326
327       OctetString() = string() | binary()
328       Integer32()   = -2147483647..2147483647
329       Integer64()   = -9223372036854775807..9223372036854775807
330       Unsigned32()  = 0..4294967295
331       Unsigned64()  = 0..18446744073709551615
332       Float32()     = '-infinity' | float() | infinity
333       Float64()     = '-infinity' | float() | infinity
334       Grouped()     = record()
335
336
337       On encode, an OctetString() can be specified  as  an  iolist(),  exces‐
338       sively  large  floats (in absolute value) are equivalent to infinity or
339       '-infinity' and excessively large integers result  in  encode  failure.
340       The records for grouped AVPs are as discussed in the previous section.
341
342       Derived AVP Data Formats
343
344       Address() = OctetString()
345                 | tuple()
346
347
348       On encode, an OctetString() IPv4 address is parsed in the usual x.x.x.x
349       format while an IPv6 address is parsed in any of the formats  specified
350       by section 2.2 of RFC 2373, "Text Representation of Addresses". An IPv4
351       tuple() has length 4 and contains values of type 0..255.  An  IPv6  tu‐
352       ple() has length 8 and contains values of type 0..65535. The tuple rep‐
353       resentation is used on decode.
354
355       Time() = {date(), time()}
356
357       where
358
359         date() = {Year, Month, Day}
360         time() = {Hour, Minute, Second}
361
362         Year   = integer()
363         Month  = 1..12
364         Day    = 1..31
365         Hour   = 0..23
366         Minute = 0..59
367         Second = 0..59
368
369
370       Additionally, values that can be encoded are limited by  way  of  their
371       encoding  as  four octets as required by RFC 6733 with the required ex‐
372       tension  from  RFC   2030.   In   particular,   only   values   between
373       {{1968,1,20},{3,14,8}} and {{2104,2,26},{9,42,23}} (both inclusive) can
374       be encoded.
375
376       UTF8String() = [integer()] | binary()
377
378
379       List elements are the UTF-8 encodings of the individual  characters  in
380       the string. Invalid codepoints will result in encode/decode failure. On
381       encode, a UTF8String() can be specified as a binary,  or  as  a  nested
382       list of binaries and codepoints.
383
384       DiameterIdentity() = OctetString()
385
386
387       A value must have length at least 1.
388
389       DiameterURI() = OctetString()
390                     | #diameter_URI{type = Type,
391                                     fqdn = FQDN,
392                                     port = Port,
393                                     transport = Transport,
394                                     protocol  = Protocol}
395
396       where
397
398         Type = aaa | aaas
399         FQDN = OctetString()
400         Port = integer()
401         Transport = sctp | tcp
402         Protocol  = diameter | radius | 'tacacs+'
403
404
405       On  encode,  fields  port, transport and protocol default to 3868, sctp
406       and diameter respectively. The grammar of an OctetString-valued  Diame‐
407       terURI()  is as specified in section 4.3 of RFC 6733. The record repre‐
408       sentation is used on decode.
409
410       Enumerated() = Integer32()
411
412
413       On encode, values can be specified using the macros defined in  a  dic‐
414       tionary's hrl file.
415
416       IPFilterRule()  = OctetString()
417       QoSFilterRule() = OctetString()
418
419
420       Values of these types are not currently parsed by diameter.
421

SEE ALSO

423       diameterc(1),  diameter(3),  diameter_app(3), diameter_codec(3), diame‐
424       ter_make(3)
425
426
427
428Ericsson AB                     diameter 2.2.7                diameter_dict(5)
Impressum