1diameter_dict(5) Files diameter_dict(5)
2
6 diameter_dict - Dictionary interface of the diameter application.
7
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 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 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 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
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 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 @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 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 Example:
67 @id 16777231
69 @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 Note that a dictionary module should have a unique name so as not
77 collide with existing modules in the system.
78 Example:
80 @name etsi_e2
82 @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 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 Example:
94 @prefix etsi_e2
96 @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 Example:
106 @vendor 13019 ETSI
108 @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 Example:
116 @avp_vendor_id 2937
118 WWW-Auth
120 Domain-Index
121 Region-Set
122 @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 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 All dictionaries should typically inherit RFC 6733 AVPs from diame‐
142 ter_gen_base_rfc6733.
143 Example:
145 @inherits diameter_gen_base_rfc6733
147 @avp_types:
150 Defines the name, code, type and flags of individual AVPs. The sec‐
151 tion consists of definitions of the form
152 Name Code Type Flags
154 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 Example:
162 @avp_types
164 Location-Information 350 Grouped MV
166 Requested-Information 353 Enumerated V
167 Warning:
170 The P flag has been deprecated by RFC 6733.
171 @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 Example:
183 @custom_types rfc4005_avps
185 Framed-IP-Address
187 @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 Example:
195 @codecs rfc4005_avps
197 Framed-IP-Address
199 @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 @messages
207 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 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 @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 Example:
246 @grouped
248 SIP-Deregistration-Reason ::= < AVP Header: 383 >
250 { SIP-Reason-Code }
251 [ SIP-Reason-Info ]
252 * [ AVP ]
253 Specifying a Vendor-Id in the definition of a grouped AVP is equiv‐
256 alent to specifying it with @avp_vendor_id.
257 @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 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 Example:
268 @enum SIP-Reason-Code
270 PERMANENT_TERMINATION 0
272 NEW_SIP_SERVER_ASSIGNED 1
273 SIP_SERVER_CHANGE 2
274 REMOVE_SIP_SERVER 3
275 @end:
278 Causes parsing of the dictionary to terminate: any remaining con‐
279 tent is ignored.
280 Comments can be included in a dictionary file using semicolon: charac‐
282 ters from a semicolon to end of line are ignored.
283
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 SIP-Deregistration-Reason ::= < AVP Header: 383 >
294 { SIP-Reason-Code }
295 [ SIP-Reason-Info ]
296 * [ AVP ]
297 will result in the following record definition given an empty prefix.
300 -record('SIP-Deregistration-Reason', {'SIP-Reason-Code',
302 'SIP-Reason-Info',
303 'AVP'}).
304 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
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 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 Basic AVP Data Formats
326 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 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 Derived AVP Data Formats
343 Address() = OctetString()
345 | tuple()
346 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 Time() = {date(), time()}
356 where
358 date() = {Year, Month, Day}
360 time() = {Hour, Minute, Second}
361 Year = integer()
363 Month = 1..12
364 Day = 1..31
365 Hour = 0..23
366 Minute = 0..59
367 Second = 0..59
368 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 UTF8String() = [integer()] | binary()
377 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 DiameterIdentity() = OctetString()
385 A value must have length at least 1.
388 DiameterURI() = OctetString()
390 | #diameter_URI{type = Type,
391 fqdn = FQDN,
392 port = Port,
393 transport = Transport,
394 protocol = Protocol}
395 where
397 Type = aaa | aaas
399 FQDN = OctetString()
400 Port = integer()
401 Transport = sctp | tcp
402 Protocol = diameter | radius | 'tacacs+'
403 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 Enumerated() = Integer32()
411 On encode, values can be specified using the macros defined in a dic‐
414 tionary's hrl file.
415 IPFilterRule() = OctetString()
417 QoSFilterRule() = OctetString()
418 Values of these types are not currently parsed by diameter.
421
423 diameterc(1), diameter(3), diameter_app(3), diameter_codec(3), diame‐
424 ter_make(3)
425Ericsson AB diameter 2.2.4 diameter_dict(5)