aboutsummaryrefslogblamecommitdiffstats
path: root/lib/diameter/doc/src/diameter_dict.xml
blob: 5bc3cab9e46b1065510f2c327b1b2b0402c3ab18 (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
























































































































































































































































































































































































































































































































































































































                                                                              
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "fileref.dtd">

<fileref>
<header>

<copyright>
<year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
    
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
    
</legalnotice>

<title>diameter_dict(4)</title>
<prepared>Anders Svensson</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>%VSN%</rev>
<file>diameter_dict.xml</file>
</header>

<!-- ===================================================================== -->

<file>diameter_dict</file>
<filesummary>Dictionary inteface of the diameter application.</filesummary>

<description>
<p>
A diameter service as configured with <seealso
marker="diameter#start_service">diameter:start_service/2</seealso>
specifies one or more supported Diameter applications.
Each Diameter application specifies a dictionary module that knows how
to encode and decode its messages and AVP's.
The dictionary module is in turn generated from a file that defines
these messages and AVP's.
The format of such a file is defined in
<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below.</p>

<p>
The codec generation also results in an hrl that defines records
for the messages and grouped AVP's defined for the application, these
records being what a user of the diameter application sends and
receives.
These records and the underlying Erlang data types corresponding to
Diameter data formats are discussed in <seealso
marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso
marker="#DATA_TYPES">DATA TYPES</seealso> respectively.</p>

<!-- TODO: Need some reserved dictionary for agents that shouldn't -->
<!--       know about specific applications. -->

<p>
The diameter application defines the base application of RFC 3588 in
the file diameter_gen_base_rfc3588.dia, and
this is the only application that diameter itself has any specific
knowledge of.
Other applications are callback modules configured for an application
as far as diameter is concerned.</p>

<p>
A generated hrl also contains defines for the values of defined for
AVPs of type Enumerated.</p>

<p>
See <seealso marker="diameter_compile">diameterc</seealso> for a
utility that transforms dictionary files into codec modules needed
at runtime.</p>

<marker id="FILE_FORMAT"/>
</description>

<!-- ===================================================================== -->

<section>
<title>FILE FORMAT</title>

<p>
A specification file consists of distinct sections.
Each section starts with a line consisting of a tag
followed by zero or more arguments.
Each section ends at the the start of the next section or end of file.
Tags consist of an ampersand character followed by a keyword and are
separated from their arguments by whitespace.
Whitespace within a section separates individual tokens but its
quantity is insignificant.</p>

<p>
The tags, their arguments and the contents of each corresponding
section are as follows.
Each section can occur only once unless otherwise specified.
The order in which sections are specified is unimportant.</p>

<taglist>

<tag><c>@id Number</c></tag>
<item>
<p>
Defines the integer Number as the Diameter Application Id of the
application in question.
The section has empty content.</p>

<p>
The Application Id is set in the Diameter Header of outgoing messages
of the application, and the value in the header of an incoming message
is used to identify the relevant dictionary module.</p>

<p>
Example:</p>

<code>
@id 16777231
</code>

</item>

<tag><c>@name Mod</c></tag>
<item>
<p>
Defines the name of the generated dictionary module.
The section has empty content.
Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$';
that is, contains only alphanumerics, hyphens and underscores begin with an
alphanumeric.</p>

<p>
A name is optional and defaults to the name of the dictionary file
minus any extension.
Note that a generated module must have a unique name an not colide
with another module in the system.</p>

<p>
Example:</p>

<code>
@name etsi_e2
</code>

</item>

<tag><c>@prefix Name</c></tag>
<item>
<p>
Defines Name as the prefix to be added to record and constant names in
the generated dictionary module and hrl.
The section has empty content.
Name must be of the same form as a @name.</p>

<p>
A prefix is optional but can
be used to disambiguate record and constant names
resulting from similarly named messages and AVP's in different
Diameter applications.</p>

<p>
Example:</p>

<code>
@prefix etsi_e2_
</code>

</item>

<tag><c>@vendor Number Name</c></tag>
<item>
<p>
Defines the integer Number as the the default Vendor-ID of AVP's for
which the V flag is set.
Name documents the owner of the application
but is otherwise unused.
The section has empty content.</p>

<p>
Example:</p>

<code>
@vendor 13019 ETSI
</code>

</item>

<tag><c>@avp_vendor_id Number</c></tag>
<item>
<p>
Defines the integer Number as the Vendor-ID of the AVP's listed in the
section content, overriding the <c>@vendor</c> default.
The section content consists of AVP names.
Can occur zero or more times (with different values of Number).</p>

<p>
Example:</p>

<code>
@avp_vendor_id 2937

WWW-Auth
Domain-Index
Region-Set
</code>

</item>

<tag><c>@inherits Mod</c></tag>
<item>
<p>
Defines the name of a generated dictionary module containing AVP
definitions referenced by the dictionary but not defined by it.
The section content is empty.</p>

<p>
Can occur 0 or more times (with different values of Mod) but all
dictionaries should typically inherit RFC3588 AVPs from
diameter_gen_base_rfc3588.</p>

<p>
Example:</p>

<code>
@inherits diameter_gen_base_rfc3588
</code>

</item>

<tag><c>@avp_types</c></tag>
<item>
<p>
Defines the name, code, type and flags of individual AVPs.
The section consists of definitions of the form</p>

<p><c>Name Code Type Flags</c></p>

<p>
where Code is the integer AVP code, 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.
Type identifies either an AVP Data Format as defined in <seealso
marker="DATA_TYPES">DATA TYPES</seealso> below or a
type as defined by a <c>@custom_types</c> tag.</p>

<p>
Example:</p>

<code>
@avp_types

Location-Information   350  Grouped     VM
Requested-Information  353  Enumerated  V
</code>

<p>
Note that the P flag has been deprecated by the Diameter Maintenance
and Extensions Working Group of the IETF.</p>

</item>

<tag><c>@custom_types Mod</c></tag>
<item>
<p>
Defines AVPs for which module Mod provides encode/decode.
The section contents consists of type names.
For each AVP Name defined with custom type Type, Mod should export the
function Name/3 with arguments encode|decode, Type and Data,
the latter being the term to be encoded/decoded.
The function returns the encoded/decoded value.</p>

<p>
Can occur 0 or more times (with different values of Mod).</p>

<p>
Example:</p>

<code>
@custom_types rfc4005_types

Framed-IP-Address
</code>
</item>

<tag><c>@messages</c></tag>
<item>
<p>
Defines the messages of the application.
The section content consists of definitions of the form specified in
section 3.2 of RFC 3588, "Command Code ABNF specification".</p>

<!-- RFC 4740 RTR/RTA -->
<code>
@messages

RTR ::= &lt; Diameter Header: 287, REQ, PXY >
        &lt; 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 ::= &lt; Diameter Header: 287, PXY >
        &lt; 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 ]
</code>

</item>

<tag><c>@grouped</c></tag>
<item>
<p>
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 3588, "Grouped AVP Values".</p>

<p>
Example:</p>

<code>
@grouped

SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
                              { SIP-Reason-Code }
                              [ SIP-Reason-Info ]
                            * [ AVP ]
</code>
</item>

<tag><c>@enum Name</c></tag>
<item>
<p>
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
hexidecimal.</p>

<p>
Can occur 0 or more times (with different values of Name).</p>

<p>
Example:</p>

<code>
@enum SIP-Reason-Code

PERMANENT_TERMINATION    0
NEW_SIP_SERVER_ASSIGNED  1
SIP_SERVER_CHANGE        2
REMOVE_SIP_SERVER        3
</code>
</item>

</taglist>

<p>
Comments can be included in a dictionary file using semicolon:
text from a semicolon to end of line is ignored.</p>

<marker id="MESSAGE_RECORDS"/>
</section>

<!-- ===================================================================== -->

<section>
<title>MESSAGE RECORDS</title>

<p>
The hrl generated from a dictionary specification defines records for the
messages and grouped AVPs defined in <c>@messages</c> and
<c>@grouped</c> sections.
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 <c>@prefix</c> 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</p>

<code>
SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
                              { SIP-Reason-Code }
                              [ SIP-Reason-Info ]
                            * [ AVP ]
</code>

<p>
will result in the following record definition given an empty
prefix.</p>

<code>
-record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
                                     'SIP-Reason-Info',
                                     'AVP'}).
</code>

<p>
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 3588
types being described below.</p>

<marker id="DATA_TYPES"/>
</section>

<!-- ===================================================================== -->

<section>
<title>DATA TYPES</title>

<p>
The data formats defined in sections 4.2 ("Basic AVP Data
Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded
as values of the types defined here.
Values are passed to <seealso
marker="diameter#call">diameter:call/4</seealso>
in a request record when sending a request, returned in a resulting
answer record and passed to a diameter_app(3) <seealso
marker="diameter_app#handle_request">handle_request</seealso>
callback upon reception of an incoming request.</p>

<p>
<em>Basic AVP Data Formats</em></p>

<marker id="OctetString"/>
<marker id="Integer32"/>
<marker id="Integer64"/>
<marker id="Unsigned32"/>
<marker id="Unsigned64"/>
<marker id="Float32"/>
<marker id="Float64"/>
<marker id="Grouped"/>

<code>
OctetString() = [0..255]
Integer32()   = -2147483647..2147483647
Integer64()   = -9223372036854775807..9223372036854775807
Unsigned32()  = 0..4294967295
Unsigned64()  = 0..18446744073709551615
Float32()     = '-infinity' | float() | infinity
Float64()     = '-infinity' | float() | infinity
Grouped()     = record()
</code>

<p>
On encode, an OctetString() can be specified as an iolist(),
excessively 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.</p>

<p>
<em>Derived AVP Data Formats</em></p>

<marker id="Address"/>
<code>
Address() = OctetString()
          | tuple()
</code>

<p>
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.</p>

<marker id="Time"/>
<code>
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
</code>

<p>
Additionally, values that can be encoded are
limited by way of their encoding as four octets as required by RFC
3588 with the required extension from RFC 2030.
In particular, only values between <c>{{1968,1,20},{3,14,8}}</c>
and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p>

<marker id="UTF8String"/>
<code>
UTF8String() = [integer()]
</code>

<p>
List elements are the UTF-8 encodings of the individual characters
in the string.
Invalid codepoints will result in encode/decode failure.</p>

<marker id="DiameterIdentity"/>
<code>
DiameterIdentity() = OctetString()
</code>

<p>
A value must have length at least 1.</p>

<marker id="DiameterURI"/>
<code>
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+'
</code>

<p>
On encode, fields port, transport and protocol default to 3868, sctp
and diameter respectively.
The grammar of an OctetString-valued DiameterURI() is as specified in
section 4.3 of RFC 3588.
The record representation is used on decode.</p>

<marker id="Enumerated"/>
<code>
Enumerated() = Integer32()
</code>

<p>
On encode, values can be specified using the macros defined in a
dictionary's hrl file.</p>

<marker id="IPFilterRule"/>
<marker id="QoSFilterRule"/>
<code>
IPFilterRule()  = OctetString()
QoSFilterRule() = OctetString()
</code>

<p>
Values of these types are not parsed by diameter.</p>

</section>

<!-- ===================================================================== -->
<!-- ===================================================================== -->

<section>
<title>SEE ALSO</title>

<p>
<seealso marker="diameter_util">diameterc(1)</seealso></p>

</section>

</fileref>