diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_dict.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 601 |
1 files changed, 601 insertions, 0 deletions
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml new file mode 100644 index 0000000000..5bc3cab9e4 --- /dev/null +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -0,0 +1,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 ::= < 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 ] +</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 ::= < 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 ::= < 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> |