aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r--lib/diameter/doc/src/diameter.xml282
-rw-r--r--lib/diameter/doc/src/diameter_app.xml9
-rw-r--r--lib/diameter/doc/src/diameter_codec.xml42
-rw-r--r--lib/diameter/doc/src/diameter_dict.xml13
-rw-r--r--lib/diameter/doc/src/diameter_sctp.xml63
-rw-r--r--lib/diameter/doc/src/diameter_soc.xml1327
-rw-r--r--lib/diameter/doc/src/diameter_soc_rfc6733.xml8693
-rw-r--r--lib/diameter/doc/src/diameter_tcp.xml58
-rw-r--r--lib/diameter/doc/src/files.mk5
-rw-r--r--lib/diameter/doc/src/notes.xml350
-rw-r--r--lib/diameter/doc/src/seealso.ent7
-rw-r--r--lib/diameter/doc/standard/rfc7683.txt2355
12 files changed, 4327 insertions, 8877 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 72181a42b0..6bc7d147c0 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -21,7 +21,7 @@
<copyright>
<year>2011</year>
-<year>2016</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -300,6 +300,17 @@ corresponding list of filters.
Defaults to <c>none</c>.</p>
</item>
+<tag><c>{peer, &app_peer_ref;}</c></tag>
+<item>
+<p>
+Peer to which the request in question can be sent, preempting the
+selection of peers having advertised support for the Diameter
+application in question.
+Multiple options can be specified, and their order is
+respected in the candidate lists passed to a subsequent
+&app_pick_peer; callback.</p>
+</item>
+
<tag><c>{timeout, &dict_Unsigned32;}</c></tag>
<item>
<p>
@@ -386,10 +397,10 @@ from the peer offers it.</p>
Note that each tuple communicates one or more AVP values.
It is an error to specify duplicate tuples.</p>
-<marker id="evaluable"/>
+<marker id="eval"/>
</item>
-<tag><c>evaluable() = {M,F,A} | fun() | [evaluable() | A]</c></tag>
+<tag><c>eval() = {M,F,A} | fun() | [eval() | A]</c></tag>
<item>
<p>
An expression that can be evaluated as a function in the following
@@ -407,7 +418,7 @@ eval(F) ->
</pre>
<p>
-Applying an <c>&evaluable;</c>
+Applying an <c>&eval;</c>
<c>E</c> to an argument list <c>A</c>
is meant in the sense of <c>eval([E|A])</c>.</p>
@@ -473,11 +484,11 @@ Matches only those peers whose Origin-Realm has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
-<tag><c>{eval, &evaluable;}</c></tag>
+<tag><c>{eval, &eval;}</c></tag>
<item>
<p>
Matches only those peers for which the specified
-<c>&evaluable;</c> returns
+<c>&eval;</c> returns
<c>true</c> when applied to the connection's <c>diameter_caps</c>
record.
Any other return value or exception is equivalent to <c>false</c>.</p>
@@ -639,7 +650,7 @@ Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
Caps = #diameter_caps{}
Pkt = #diameter_packet{}
ResultCode = integer()
-CB = &evaluable;
+CB = &eval;
</pre>
<p>
@@ -787,15 +798,31 @@ be matched by corresponding &capability; configuration, of
</item>
<tag>
-<marker id="incoming_maxlen"/><c>{incoming_maxlen, 0..16777215}</c></tag>
+<marker id="decode_format"/>
+<c>{decode_format, record | list | map | none}</c></tag>
<item>
<p>
-Bound on the expected size of incoming Diameter messages.
-Messages larger than the specified number of bytes are discarded.</p>
+The format of decoded messages and grouped AVPs in the <c>msg</c> field
+of diameter_packet records and <c>value</c> field of diameter_avp
+records respectively.
+If <c>record</c> then a record whose definition is generated from the
+dictionary file in question.
+If <c>list</c> or <c>map</c> then a <c>[Name | Avps]</c> pair where
+<c>Avps</c> is a list of AVP name/values pairs or a map keyed on
+AVP names respectively.
+If <c>none</c> then the atom-value message name, or <c>undefined</c>
+for a Grouped AVP.
+See also &codec_message;.</p>
<p>
-Defaults to <c>16777215</c>, the maximum value of the 24-bit Message
-Length field in a Diameter Header.</p>
+Defaults to <c>record</c>.</p>
+
+<note>
+<p>
+AVPs are decoded into a list of diameter_avp records in <c>avps</c>
+field of diameter_packet records independently of
+<c>decode_format</c>.</p>
+</note>
</item>
@@ -803,7 +830,7 @@ Length field in a Diameter Header.</p>
| node
| nodes
| [node()]
- | evaluable()}</c></tag>
+ | eval()}</c></tag>
<item>
<p>
The degree to which the service allows multiple transport
@@ -814,7 +841,7 @@ at capabilities exchange.</p>
If <c>[node()]</c> then a connection is rejected if another already
exists on any of the specified nodes.
Types <c>false</c>, <c>node</c>, <c>nodes</c> and
-&evaluable; are equivalent to
+&eval; are equivalent to
<c>[]</c>, <c>[node()]</c>, <c>[node()|nodes()]</c> and the
evaluated value respectively, evaluation of each expression taking
place whenever a new connection is to be established.
@@ -829,7 +856,7 @@ by their own peer and watchdog state machines.</p>
Defaults to <c>nodes</c>.</p>
</item>
-<tag><c>{sequence, {H,N} | &evaluable;}</c></tag>
+<tag><c>{sequence, {H,N} | &eval;}</c></tag>
<item>
<p>
A constant value <c>H</c> for the topmost <c>32-N</c> bits of
@@ -864,7 +891,7 @@ outgoing requests.</p>
</warning>
</item>
-<tag><c>{share_peers, boolean() | [node()] | evaluable()}</c></tag>
+<tag><c>{share_peers, boolean() | [node()] | eval()}</c></tag>
<item>
<p>
Nodes to which peer connections established on the local
@@ -877,7 +904,7 @@ configured to use them: see <c>use_shared_peers</c> below.</p>
If <c>false</c> then peers are not shared.
If <c>[node()]</c> then peers are shared with the specified list of
nodes.
-If <c>evaluable()</c> then peers are shared with the nodes returned
+If <c>eval()</c> then peers are shared with the nodes returned
by the specified function, evaluated whenever a peer connection
becomes available or a remote service requests information about local
connections.
@@ -903,59 +930,36 @@ of a single Diameter node across multiple Erlang nodes.</p>
</note>
</item>
-<tag><c>{spawn_opt, [term()]}</c></tag>
-<item>
-<p>
-Options list passed to &spawn_opt; when spawning a process for an
-incoming Diameter request, unless the transport in question
-specifies another value.
-Options <c>monitor</c> and <c>link</c> are ignored.</p>
-
-<p>
-Defaults to the empty list.</p>
-</item>
-
<tag>
-<marker id="strict_mbit"/><c>{strict_mbit, boolean()}</c></tag>
+<marker id="strict_arities"/><c>{strict_arities, boolean()
+ | encode
+ | decode}</c></tag>
<item>
<p>
-Whether or not to regard an AVP setting the M-bit as erroneous when
-the command grammar in question does not explicitly allow the AVP.
-If <c>true</c> then such AVPs are regarded as 5001 errors,
-DIAMETER_AVP_UNSUPPORTED.
-If <c>false</c> then the M-bit is ignored and policing
-it becomes the receiver's responsibility.</p>
+Whether or not to require that the number of AVPs in a message or
+grouped AVP agree with those specified in the dictionary in question
+when passing messages to &man_app; callbacks.
+If <c>true</c> then mismatches in an outgoing messages cause message
+encoding to fail, while mismatches in an incoming message are reported
+as 5005/5009 errors in the errors field of the diameter_packet record
+passed to &app_handle_request; or &app_handle_answer; callbacks.
+If <c>false</c> then neither error is enforced/detected.
+If <c>encode</c> or <c>decode</c> then errors are only
+enforced/detected on outgoing or incoming messages respectively.</p>
<p>
Defaults to <c>true</c>.</p>
-<warning>
-<p>
-RFC 6733 is unclear about the semantics of the M-bit.
-One the one hand, the CCF specification in section 3.2 documents AVP
-in a command grammar as meaning <em>any</em> arbitrary AVP; on the
-other hand, 1.3.4 states that AVPs setting the M-bit cannot be added
-to an existing command: the modified command must instead be
-placed in a new Diameter application.</p>
-<p>
-The reason for the latter is presumably interoperability:
-allowing arbitrary AVPs setting the M-bit in a command makes its
-interpretation implementation-dependent, since there's no
-guarantee that all implementations will understand the same set of
-arbitrary AVPs in the context of a given command.
-However, interpreting <c>AVP</c> in a command grammar as any
-AVP, regardless of M-bit, renders 1.3.4 meaningless, since the receiver
-can simply ignore any AVP it thinks isn't relevant, regardless of the
-sender's intent.</p>
+<note>
<p>
-Beware of confusing mandatory in the sense of the M-bit with mandatory
-in the sense of the command grammar.
-The former is a semantic requirement: that the receiver understand the
-semantics of the AVP in the context in question.
-The latter is a syntactic requirement: whether or not the AVP must
-occur in the message in question.</p>
-</warning>
-
+Disabling arity checks affects the form of messages at encode/decode.
+In particular, decoded AVPs are represented as lists of values,
+regardless of the AVP's arity (ie. expected number in the message/AVP
+grammar in question), and values are expected to be supplied as lists
+at encode.
+This differs from the historic decode behaviour of representing AVPs
+of arity 1 as bare values, not wrapped in a list.</p>
+</note>
</item>
<tag>
@@ -982,7 +986,27 @@ The default value is for backwards compatibility.</p>
</item>
-<tag><c>{use_shared_peers, boolean() | [node()] | evaluable()}</c></tag>
+<tag>
+<marker id="traffic_counters"/><c>{traffic_counters, boolean()}</c></tag>
+<item>
+<p>
+Whether or not to count application-specific messages; those for which
+&man_app; callbacks take place.
+If false then only messages handled by diameter itself are counted:
+CER/CEA, DWR/DWA, DPR/DPA.</p>
+
+<p>
+Defaults to <c>true</c>.</p>
+
+<note>
+<p>
+Disabling counters is a performance improvement, but means that the
+omitted counters are not returned by &service_info;.</p>
+</note>
+
+</item>
+
+<tag><c>{use_shared_peers, boolean() | [node()] | eval()}</c></tag>
<item>
<p>
Nodes from which communicated peers are made available in
@@ -992,7 +1016,7 @@ the remote candidates list of &app_pick_peer; callbacks.</p>
If <c>false</c> then remote peers are not used.
If <c>[node()]</c> then only peers from the specified list of nodes
are used.
-If <c>evaluable()</c> then only peers returned by the specified
+If <c>eval()</c> then only peers returned by the specified
function are used, evaluated whenever a remote service communicates
information about an available peer connection.
The value <c>true</c> is equivalent to <c>fun &nodes;</c>.
@@ -1017,6 +1041,15 @@ each node from which requests are sent.</p>
</warning>
</item>
+<tag><c>&transport_opt;</c></tag>
+<item>
+<p>
+Any transport option except <c>applications</c> or
+<c>capabilities</c>.
+Used as defaults for transport configuration, values passed to
+&add_transport; overriding values configured on the service.</p>
+</item>
+
</taglist>
<marker id="transport_opt"/>
@@ -1050,6 +1083,37 @@ implies having to set matching *-Application-Id AVPs in a
</item>
<tag>
+<marker id="avp_dictionaries"/><c>{avp_dictionaries, [module()]}</c></tag>
+<item>
+<p>
+A list of alternate dictionary modules with which to encode/decode
+AVPs that are not defined by the dictionary of the application in
+question.
+At decode, such AVPs are represented as diameter_avp records in the
+<c>'AVP'</c> field of a decoded message or Grouped AVP, the first
+alternate that succeeds in decoding the AVP setting the record's value
+field.
+At encode, values in an <c>'AVP'</c> list can be passed as AVP
+name/value 2-tuples, and it is an encode error for no alternate to
+define the AVP of such a tuple.</p>
+
+<p>
+Defaults to the empty list.</p>
+
+<note>
+<p>
+The motivation for alternate dictionaries is RFC 7683, Diameter
+Overload Indication Conveyance (DOIC), which defines AVPs to
+be piggybacked onto existing application messages rather than defining
+an application of its own.
+The DOIC dictionary is provided by the diameter application, as module
+<c>diameter_gen_doic_rfc7683</c>, but alternate dictionaries can be
+used to encode/decode any set of AVPs not known to an application
+dictionary.</p>
+</note>
+</item>
+
+<tag>
<marker id="capabilities"/><c>{capabilities, [&capability;]}</c></tag>
<item>
<p>
@@ -1064,7 +1128,7 @@ TLS is desired over TCP as implemented by &man_tcp;.</p>
</item>
<tag>
-<marker id="capabilities_cb"/><c>{capabilities_cb, &evaluable;}</c></tag>
+<marker id="capabilities_cb"/><c>{capabilities_cb, &eval;}</c></tag>
<item>
<p>
Callback invoked upon reception of CER/CEA during capabilities
@@ -1158,7 +1222,7 @@ transport.</p>
</item>
<tag>
-<marker id="disconnect_cb"/><c>{disconnect_cb, &evaluable;}</c></tag>
+<marker id="disconnect_cb"/><c>{disconnect_cb, &eval;}</c></tag>
<item>
<p>
Callback invoked prior to terminating the transport process of a
@@ -1258,6 +1322,19 @@ Defaults to 5000.</p>
</item>
<tag>
+<marker id="incoming_maxlen"/><c>{incoming_maxlen, 0..16777215}</c></tag>
+<item>
+<p>
+Bound on the expected size of incoming Diameter messages.
+Messages larger than the specified number of bytes are discarded.</p>
+
+<p>
+Defaults to <c>16777215</c>, the maximum value of the 24-bit Message
+Length field in a Diameter Header.</p>
+
+</item>
+
+<tag>
<marker id="length_errors"/><c>{length_errors, exit|handle|discard}</c></tag>
<item>
<p>
@@ -1315,7 +1392,64 @@ incoming Diameter request.
Options <c>monitor</c> and <c>link</c> are ignored.</p>
<p>
-Defaults to the list configured on the service if not specified.</p>
+Defaults to the empty list.</p>
+</item>
+
+<tag>
+<marker id="strict_capx"/><c>{strict_capx, boolean()]}</c></tag>
+<item>
+<p>
+Whether or not to enforce the RFC 6733 requirement that any message
+before capabilities exchange should close the peer connection.
+If false then unexpected messages are discarded.</p>
+
+<p>
+Defaults to true.
+Changing this results in non-standard behaviour, but can be useful in
+case peers are known to be behave badly.</p>
+</item>
+
+<tag>
+<marker id="strict_mbit"/><c>{strict_mbit, boolean()}</c></tag>
+<item>
+<p>
+Whether or not to regard an AVP setting the M-bit as erroneous when
+the command grammar in question does not explicitly allow the AVP.
+If <c>true</c> then such AVPs are regarded as 5001 errors,
+DIAMETER_AVP_UNSUPPORTED.
+If <c>false</c> then the M-bit is ignored and policing
+it becomes the receiver's responsibility.</p>
+
+<p>
+Defaults to <c>true</c>.</p>
+
+<warning>
+<p>
+RFC 6733 is unclear about the semantics of the M-bit.
+One the one hand, the CCF specification in section 3.2 documents AVP
+in a command grammar as meaning <em>any</em> arbitrary AVP; on the
+other hand, 1.3.4 states that AVPs setting the M-bit cannot be added
+to an existing command: the modified command must instead be
+placed in a new Diameter application.</p>
+<p>
+The reason for the latter is presumably interoperability:
+allowing arbitrary AVPs setting the M-bit in a command makes its
+interpretation implementation-dependent, since there's no
+guarantee that all implementations will understand the same set of
+arbitrary AVPs in the context of a given command.
+However, interpreting <c>AVP</c> in a command grammar as any
+AVP, regardless of M-bit, renders 1.3.4 meaningless, since the receiver
+can simply ignore any AVP it thinks isn't relevant, regardless of the
+sender's intent.</p>
+<p>
+Beware of confusing mandatory in the sense of the M-bit with mandatory
+in the sense of the command grammar.
+The former is a semantic requirement: that the receiver understand the
+semantics of the AVP in the context in question.
+The latter is a syntactic requirement: whether or not the AVP must
+occur in the message in question.</p>
+</warning>
+
</item>
<tag>
@@ -1731,8 +1865,8 @@ An example return value with for a client service with Origin-Host
{raddr,{127,0,0,1}},
{rport,3868},
{reuseaddr,true}]}]},
- {watchdog,{&lt;0.66.0>,{1346,171491,996448},okay}},
- {peer,{&lt;0.67.0>,{1346,171491,999906}}},
+ {watchdog,{&lt;0.66.0>,-576460736368485571,okay}},
+ {peer,{&lt;0.67.0>,-576460736357885808}},
{apps,[{0,common}]},
{caps,[{origin_host,{"client.example.com","server.example.com"}},
{origin_realm,{"example.com","example.com"}},
@@ -1812,8 +1946,8 @@ connection might look as follows.</p>
{transport_config,[{reuseaddr,true},
{ip,{127,0,0,1}},
{port,3868}]}]},
- {accept,[[{watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
- {peer,{&lt;0.58.0>,{1346,171491,999511}}},
+ {accept,[[{watchdog,{&lt;0.56.0>,-576460739249514012,okay}},
+ {peer,{&lt;0.58.0>,-576460638229179167}},
{apps,[{0,common}]},
{caps,[{origin_host,{"server.example.com","client.example.com"}},
{origin_realm,{"example.com","example.com"}},
@@ -1842,7 +1976,7 @@ connection might look as follows.</p>
{send_max,148},
{send_avg,87},
{send_pend,0}]}]}],
- [{watchdog,{&lt;0.72.0>,{1346,171491,998404},initial}}]]},
+ [{watchdog,{&lt;0.72.0>,-576460638229717546,initial}}]]},
{statistics,[{{{0,280,0},recv},7},
{{{0,280,1},send},7},
{{{0,280,0},recv,{'Result-Code',2001}},7},
@@ -1890,8 +2024,8 @@ A return value for the server above might look as follows.</p>
{transport_config,[{reuseaddr,true},
{ip,{127,0,0,1}},
{port,3868}]}]},
- {watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
- {peer,{&lt;0.58.0>,{1346,171491,999511}}},
+ {watchdog,{&lt;0.56.0>,-576460739249514012,okay}},
+ {peer,{&lt;0.58.0>,-576460638229179167}},
{apps,[{0,common}]},
{caps,[{origin_host,{"server.example.com","client.example.com"}},
{origin_realm,{"example.com","example.com"}},
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index dfcd00975b..aa334beb21 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -13,7 +13,8 @@
<header>
<copyright>
-<year>2011</year><year>2016</year>
+<year>2011</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -319,7 +320,7 @@ or &peer_down; callback.</p>
<v>Action = Send | Discard | {eval_packet, Action, PostF}</v>
<v>Send = {send, &packet; | &message;}</v>
<v>Discard = {discard, Reason} | discard</v>
-<v>PostF = &mod_evaluable;}</v>
+<v>PostF = &mod_eval;}</v>
</type>
<desc>
<p>
@@ -371,7 +372,7 @@ discarded}</c>.</p>
<v>Action = Send | Discard | {eval_packet, Action, PostF}</v>
<v>Send = {send, &packet; | &message;}</v>
<v>Discard = {discard, Reason} | discard</v>
-<v>PostF = &mod_evaluable;}</v>
+<v>PostF = &mod_eval;}</v>
</type>
<desc>
<p>
@@ -478,7 +479,7 @@ not selected.</p>
| {answer_message, 3000..3999|5000..5999}
| {protocol_error, 3000..3999}</v>
<v>Opt = &mod_call_opt;</v>
-<v>PostF = &mod_evaluable;</v>
+<v>PostF = &mod_eval;</v>
</type>
<desc>
<p>
diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml
index 91e96058dd..5124b49484 100644
--- a/lib/diameter/doc/src/diameter_codec.xml
+++ b/lib/diameter/doc/src/diameter_codec.xml
@@ -4,7 +4,10 @@
'<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'>
<!ENTITY types
'<seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>'>
- <!ENTITY % also SYSTEM "seealso.ent" >
+ <!ENTITY decode_format
+ '<seealso marker="diameter#decode_format">decode format</seealso>'>
+
+<!ENTITY % also SYSTEM "seealso.ent" >
<!ENTITY % here SYSTEM "seehere.ent" >
%also;
%here;
@@ -13,7 +16,8 @@
<erlref>
<header>
<copyright>
-<year>2012</year><year>2016</year>
+<year>2012</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -53,17 +57,17 @@ communicated to &man_app; callbacks.
Similarly, outgoing Diameter messages are encoded into binary() before
being passed to the appropriate &man_transport; module for
transmission.
-The functions in this module implement this encode/decode.</p>
+The functions documented here implement the default encode/decode.</p>
-<note>
+<warning>
<p>
-Calls to this module are made by diameter itself as a consequence of
-configuration passed to &mod_start_service;.
-The encode/decode functions may also be useful for other purposes (eg.
-test) but the diameter user does not need to call them explicitly when
+The diameter user does not need to call functions here explicitly when
sending and receiving messages using &mod_call; and the callback
-interface documented in &man_app;.</p>
-</note>
+interface documented in &man_app;: diameter itself provides encode/decode
+as a consequence of configuration passed to &mod_start_service;, and
+the results may differ from those returned by the functions documented
+here, depending on configuration.</p>
+</warning>
<p>
The &header; and &packet; records below
@@ -144,7 +148,8 @@ question.</p>
<p>
The decoded value of an AVP.
Will be <c>undefined</c> on decode if the data bytes could
-not be decoded or the AVP is unknown.
+not be decoded, the AVP is unknown, or if the &decode_format; is
+<c>none</c>.
The type of a decoded value is as document in &types;.</p>
</item>
@@ -229,7 +234,8 @@ header.</p>
</item>
<tag>
-<marker id="message"/><c>message() = record() | list()</c></tag>
+<marker id="message"/><c>message() = record()
+ | maybe_improper_list()</c></tag>
<item>
<p>
The representation of a Diameter message as passed to
@@ -239,7 +245,10 @@ a message as defined in a dictionary file is encoded as a record with
one field for each component AVP.
Equivalently, a message can also be encoded as a list whose head is
the atom-valued message name (as specified in the relevant dictionary
-file) and whose tail is a list of <c>{AvpName, AvpValue}</c> pairs.</p>
+file) and whose tail is either a list of AVP name/values
+pairs or a map with values keyed on AVP names.
+The format at decode is determined by &mod_decode_format;.
+Any of the formats is accepted at encode.</p>
<p>
Another list-valued representation allows a message to be specified
@@ -282,15 +291,16 @@ value other than <c>undefined</c>.</p>
<item>
<p>
The incoming/outgoing message.
-For an incoming message, a record if the message can be
-decoded in a non-relay application, <c>undefined</c> otherwise.
+For an incoming message, a term corresponding to the configured
+&decode_format; if the message can be decoded in a non-relay
+application, <c>undefined</c> otherwise.
For an outgoing message, setting a <c>[&header; | &avp;]</c> list is
equivalent to setting the <c>header</c> and <c>avps</c> fields to the
corresponding values.</p>
<warning>
<p>
-A record-valued <c>msg</c> field does <em>not</em> imply an absence of
+A value in the <c>msg</c> field does <em>not</em> imply an absence of
decode errors.
The <c>errors</c> field should also be examined.</p>
</warning>
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index 9584d682c2..94016d9466 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -16,7 +16,8 @@
<header>
<copyright>
-<year>2011</year><year>2016</year>
+<year>2011</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -307,11 +308,11 @@ The P flag has been deprecated by &the_rfc;.</p>
<p>
Specifies AVPs for which module Mod provides encode/decode functions.
The section contents consists of AVP names.
-For each such name, <c>Mod:Name(encode|decode, Type, Data)</c> is
+For each such name, <c>Mod:Name(encode|decode, Type, Data, Opts)</c> 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
-<c>@avp_types</c> section of the dictionary and Data is the value to
-encode/decode.</p>
+<c>@avp_types</c> section of the dictionary, Data is the value to
+encode/decode, and Opts is a term that is passed through encode/decode.</p>
<p>
Example:</p>
@@ -328,8 +329,8 @@ Framed-IP-Address
<item>
<p>
Like <c>@custom_types</c> but requires the specified module to export
-<c>Mod:Type(encode|decode, Name, Data)</c> rather than
-<c>Mod:Name(encode|decode, Type, Data)</c>.</p>
+<c>Mod:Type(encode|decode, Name, Data, Opts)</c> rather than
+<c>Mod:Name(encode|decode, Type, Data, Opts)</c>.</p>
<p>
Example:</p>
diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index 9b6d629f79..62e958870e 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+ <!ENTITY man_tcp_sender
+ '<seealso marker="diameter_tcp#sender">diameter_tcp(3)</seealso>'>
<!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'>
<!ENTITY gen_sctp_open1
'<seealso marker="kernel:gen_sctp#open-1">gen_sctp:open/1</seealso>'>
@@ -16,7 +18,7 @@
<header>
<copyright>
<year>2011</year>
-<year>2016</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -78,7 +80,11 @@ and implements the behaviour documented in
<v>Reason = term()</v>
<v>OwnOpt = {raddr, &ip_address;}
| {rport, integer()}
- | {accept, Match}</v>
+ | {accept, Match}
+ | {unordered, boolean() | pos_integer()}
+ | {packet, boolean() | raw}
+ | {message_cb, &mod_eval;}
+ | {sender, boolean()}</v>
<v>SctpOpt = term()</v>
<v>Match = &ip_address; | string() | [Match]</v>
</type>
@@ -106,6 +112,41 @@ A string-valued <c>Match</c> that does not parse as an address is
interpreted as a regular expression.</p>
<p>
+Option <c>unordered</c> specifies whether or not to use unordered
+delivery, integer <c>N</c> being equivalent to <c>N =&lt; OS</c>,
+where <c>OS</c> is the number of outbound streams negotiated on the
+association in question.
+Regardless of configuration, sending is ordered on stream 0
+until reception of a second incoming message, to ensure that a peer
+receives capabilities exchange messages before any other.
+Defaults to <c>false</c>.</p>
+
+<p>
+Option <c>packet</c> determines how/if an incoming message is
+packaged into a diameter_packet record.
+If <c>false</c> then messages are received as binary().
+If <c>true</c> then as a record with the binary() message in the
+<c>bin</c> field and a <c>{stream, Id}</c> tuple in the
+<c>transport_data</c> field, where <c>Id</c> is the identifier of the
+inbound stream the message was received on.
+If <c>raw</c> then as a record with the received ancillary
+sctp_sndrcvinfo record in the <c>transport_data</c> field.
+Defaults to <c>true</c>.</p>
+
+<p>
+Options <c>message_cb</c> and <c>sender</c> have semantics identical
+to those documented in &man_tcp_sender;, but with the message argument
+to a <c>recv</c> callback being as directed by the <c>packet</c>
+option.</p>
+
+<p>
+An <c>{outstream, Id}</c> tuple in the <c>transport_data</c> field of
+a outgoing diameter_packet record sets the outbound stream on which
+the message is sent, modulo the negotiated number of outbound streams.
+Any other value causes successive such sends to cycle though all
+outbound streams.</p>
+
+<p>
Remaining options are any accepted by &gen_sctp_open1;, with the exception
of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
and <c>sctp_events</c>.
@@ -116,35 +157,21 @@ and port respectively.</p>
Multiple <c>ip</c> options can be specified for a multihomed peer.
If none are specified then the values of <c>Host-IP-Address</c>
in the <c>diameter_service</c> record are used.
-(In particular, one of these must be specified.)
Option <c>port</c> defaults to 3868 for a listening transport and 0 for a
connecting transport.</p>
<warning>
<p>
-An insufficiently large receive buffer may result in a peer having to
+An small receive buffer may result in a peer having to
resend incoming messages: set the &inet; option <c>recbuf</c> to increase
the buffer size.</p>
<p>
-An insufficiently large send buffer may result in outgoing messages
+An small send buffer may result in outgoing messages
being discarded: set the &inet; option <c>sndbuf</c> to increase
the buffer size.</p>
</warning>
-<p>
-The <c>transport_data</c> field of record <c>diameter_packet</c>
-is used to communicate the stream on which an inbound message
-has been received, or on which an outbound message should be sent.
-The value will be of the form <c>{stream, Id}</c> for an inbound
-message passed to a &app_handle_request; or &app_handle_answer;
-callback.
-For an outbound message, <c>{outstream, Id}</c> in the return value of
-&app_handle_request; or &app_prepare_retransmit; sets the outbound
-stream, the stream id being interpreted modulo the number of outbound
-streams.
-Any other value, or not setting a value, causes successive such sends
-to cycle though all outbound streams.</p>
</desc>
</func>
diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml
index ae404fcda4..28e01ff1be 100644
--- a/lib/diameter/doc/src/diameter_soc.xml
+++ b/lib/diameter/doc/src/diameter_soc.xml
@@ -1,15 +1,22 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd" [
+ <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'>
+ <!ENTITY gen_tcp '<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>'>
+ <!ENTITY service '<seealso marker="diameter#start_service-2">service</seealso>'>
+ <!ENTITY capabilities '<seealso marker="diameter#capability">capabilities</seealso>'>
+ <!ENTITY events '<seealso marker="diameter#service_event">events</seealso>'>
+ <!ENTITY NA '&#8212;'>
+ <!ENTITY BR '<br/>&nbsp;<br/>'>
<!ENTITY % also SYSTEM "seealso.ent" >
%also;
]>
-<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
+<chapter>
<header>
<copyright>
<year>2011</year>
-<year>2016</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
@@ -41,63 +48,1285 @@ limitations under the License.
</header>
<p>
-Known points of questionable or non-compliance.</p>
+The table below summarizes the diameter application's compliance with
+&the_rfc;.
+Since the diameter application isn't a Diameter node on its own,
+compliance is strictly the responsibility of the user in many cases,
+diameter providing the means for the user to be compliant
+rather than being compliant on its own.</p>
-<!-- ===================================================================== -->
-
-<section>
-<title>&the_rfc;</title>
-
-<list>
-
-<item>
-<p>
-There is no support for DTLS over SCTP.</p>
-</item>
-
-<item>
<p>
-There is no explicit support for peer discovery (section 5.2).
-It can possibly be implemented on top of diameter as is but this is
-probably something that diameter should do.</p>
-</item>
+The Compliance column notes <em>C</em> (Compliant) if the required
+functionality is implemented, <em>PC</em> (Partially Compliant) if
+there are limitations, <em>NC</em> (Not Compliant) if functionality is
+not implemented, or a dash if text is informational or only places
+requirements that must be met by the user's implementation.</p>
-<item>
<p>
-The peer state machine's election process (section 5.6.4) isn't
-implemented as specified since it assumes knowledge of a
-peer's Origin-Host before sending it a CER. (The identity becoming known
-upon reception of CEA.)
-The possibility of configuring
-the peer's Origin-Host could be added, along with handling of the case
-that it sends something else, but for many applications this will
-just be unnecessary configuration of a value that it has no control over.</p>
-</item>
-<!-- Transport protocol plus address/port, which we do know when
- sending and receiving CER, is enough to definitely identify
- the peer. However, there's nothing stopping a peer from using
- different identities on different transport protocols, even
- if it's maybe a bit far-fetched. -->
-
-</list>
-
-<xi:include href="diameter_soc_rfc6733.xml"/>
-
-</section>
+Capitalized <em>Diameter</em> refers to the protocol, lowercase
+<em>diameter</em> to the Erlang application.</p>
<!-- ===================================================================== -->
<section>
-<title>RFC 3539</title>
+<title>&the_rfc; - Diameter Base Protocol</title>
-<p>
-RFC 3539 is more difficult to comply to since it discusses
-problems as much as it requires functionality but all the MUST's are
-covered, the watchdog state machine being the primary one.
-Of the optional functionality, load balancing is left to the
-diameter user (since it's the one deciding who to send to) and
-there is no Congestion Manager.</p>
+<table>
+<row>
+ <cell><em>Section</em></cell>
+ <cell><em>Title</em></cell>
+ <cell><em>Compliance</em></cell>
+ <cell><em>Notes</em></cell>
+</row>
+<row>
+ <cell>1</cell>
+ <cell>Introduction</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.1</cell>
+ <cell>Diameter Protocol</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.1.1</cell>
+ <cell>Description of the Document Set</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.1.2</cell>
+ <cell>Conventions Used in This Document</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.1.3</cell>
+ <cell>Changes from RFC 3588</cell>
+ <cell>&NA;</cell>
+ <cell>It is possible to configure a 3588 dictionary in
+ order to get 3588 semantics, where the differ from 6733.</cell>
+</row>
+<row>
+ <cell>1.2</cell>
+ <cell>Terminology</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.3</cell>
+ <cell>Approach to Extensibility</cell>
+ <cell>&NA;</cell>
+ <cell>The dictionary interface documented in &man_dict; provides
+ extensibility, allowing the user to defined new AVPs, commands, and
+ applications.
+ Ready dictionaries are provided for the &the_rfc; common message, base
+ accounting, and relay applications, as well as for RFC 7683,
+ Diameter Overload Indicator Conveyance.</cell>
+</row>
+<row>
+ <cell>1.3.1</cell>
+ <cell>Defining New AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>1.3.2</cell>
+ <cell>Creating New AVPs</cell>
+ <cell>&NA;</cell>
+ <cell>New AVPs can be defined using the dictionary interface.
+ Both both RFC data formats and extensions are supported.</cell>
+</row>
+<row>
+ <cell>1.3.3</cell>
+ <cell>Creating New Commands</cell>
+ <cell>&NA;</cell>
+ <cell>New commands can be defined using the dictionary interface.</cell>
+</row>
+<row>
+ <cell>1.3.4</cell>
+ <cell>Creating New Diameter Applications</cell>
+ <cell>&NA;</cell>
+ <cell>New applications can be defined using the dictionary interface.</cell>
+</row>
+<row>
+ <cell>2</cell>
+ <cell>Protocol Overview</cell>
+ <cell>&NA;</cell>
+ <cell>Session state is the responsibility of the user.&BR;
+ The role of a Diameter node is determined by the user's
+ implementation.</cell>
+</row>
+<row>
+ <cell>2.1</cell>
+ <cell>Transport</cell>
+ <cell>PC</cell>
+ <cell>Ports are configured by the user: diameter places no
+ restrictions.&BR;
+ The transport interface documented in &man_transport;
+ allows the user to implement their own methods.
+ Ready support is provided for TCP, TCP/TLS, and SCTP, but not
+ DTLS/SCTP.&BR;
+ Multiple connections to the same peer is possible.
+ ICMP messages are not interpreted.</cell>
+</row>
+<row>
+ <cell>2.1.1</cell>
+ <cell>SCTP Guidelines</cell>
+ <cell>C</cell>
+ <cell>Unordered sending is configurable in &man_sctp;.
+ There is no special handling of DPR/DPA: since a user that cares
+ about pending answers should wait for them before initiating
+ DPR.&BR;
+ A PPID can be configured with a a gen_sctp sctp_default_send_param
+ option.</cell>
+</row>
+<row>
+ <cell>2.2</cell>
+ <cell>Securing Diameter Messages</cell>
+ <cell>PC</cell>
+ <cell>DTLS is not supported by &man_sctp;. See also
+ 2.1.</cell>
+</row>
+<row>
+ <cell>2.3</cell>
+ <cell>Diameter Application Compliance</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>2.4</cell>
+ <cell>Application Identifiers</cell>
+ <cell>C</cell>
+ <cell>The user configures diameter with the identifiers to send at
+ capabilities exchange, along with corresponding dictionaries
+ defining the messages of the applications.</cell>
+</row>
+<row>
+ <cell>2.5</cell>
+ <cell>Connections vs. Sessions</cell>
+ <cell>C</cell>
+ <cell>Connections are realized by configuring transport. Sessions
+ are the responsibility of the user.</cell>
+</row>
+<row>
+ <cell>2.6</cell>
+ <cell>Peer Table</cell>
+ <cell>PC</cell>
+ <cell>Routing is implemented by the user in callbacks documented in
+ &man_app;.
+ A peer table of the documented form is not exposed to the user.</cell>
+</row>
+<row>
+ <cell>2.7</cell>
+ <cell>Routing Table</cell>
+ <cell>PC</cell>
+ <cell>See 2.6.
+ A routing table of the documented form is not exposed to
+ the user.</cell>
+</row>
+<row>
+ <cell>2.8</cell>
+ <cell>Role of Diameter Agents</cell>
+ <cell>C</cell>
+ <cell>Most role-specific behaviour is implemented by the user.
+ How a node advertises itself at capabilities exchange is determined
+ by user configuration.</cell>
+</row>
+<row>
+ <cell>2.8.1</cell>
+ <cell>Relay Agents</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>2.8.2</cell>
+ <cell>Proxy Agents</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>2.8.3</cell>
+ <cell>Redirect Agents</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>2.8.4</cell>
+ <cell>Translation Agents</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>2.9</cell>
+ <cell>Diameter Path Authorization</cell>
+ <cell>&NA;</cell>
+ <cell>Authorization is the responsibility of the user.</cell>
+</row>
+<row>
+ <cell>3</cell>
+ <cell>Diameter Header</cell>
+ <cell>C</cell>
+ <cell>Hop-by-Hop and End-to-End Identifiers are set by diameter when
+ sending outgoing requests.</cell>
+</row>
+<row>
+ <cell>3.1</cell>
+ <cell>Command Codes</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>3.2</cell>
+ <cell>Command Code Format Specification</cell>
+ <cell>C</cell>
+ <cell>Commands are defined as CCF specifications in dictionary
+ files.</cell>
+</row>
+<row>
+ <cell>3.3</cell>
+ <cell>Diameter Command Naming Conventions</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>4</cell>
+ <cell>Diameter AVPs</cell>
+ <cell>C</cell>
+ <cell>Any required padding is added by diameter when encoding
+ outgoing messages.</cell>
+</row>
+<row>
+ <cell>4.1</cell>
+ <cell>AVP Header</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>4.1.1</cell>
+ <cell>Optional Header Elements</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>4.2</cell>
+ <cell>Basic AVP Data Formats</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>4.3</cell>
+ <cell>Derived AVP Data Formats</cell>
+ <cell>C</cell>
+ <cell>Arbitrary derived data formats are supported by the dictionary
+ interface.</cell>
+</row>
+<row>
+ <cell>4.3.1</cell>
+ <cell>Common Derived AVP Data Formats</cell>
+ <cell>C</cell>
+ <cell>Beware that RFC 6733 changed the DiameterURI transport/port
+ defaults specified in RFC3588.
+ Relying on the defaults can result in interoperability
+ problems.</cell>
+</row>
+<row>
+ <cell>4.4</cell>
+ <cell>Grouped AVP Values</cell>
+ <cell>C</cell>
+ <cell>The M-bit on a component AVP of a Grouped AVP that does not
+ set M is ignored: such AVPs are not regarded as erroneous at
+ decode.&BR;
+ Grouped AVPs are defined as CCF specifications in dictionary
+ files.</cell>
+</row>
+<row>
+ <cell>4.4.1</cell>
+ <cell>Example AVP with a Grouped Data Type</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>4.5</cell>
+ <cell>Diameter Base Protocol AVPs</cell>
+ <cell>C</cell>
+ <cell>The base AVPs are defined in the common dictionary provided by
+ diameter.
+ There are common dictionaries for both RFC 3588 and RFC 6733 since
+ the latter made changes to both syntax and semantics.</cell>
+</row>
+<row>
+ <cell>5</cell>
+ <cell>Diameter Peers</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.1</cell>
+ <cell>Peer Connections</cell>
+ <cell>PC</cell>
+ <cell>A peer's DiameterIdentity is not required when initiating a
+ connection: the identify is received at capabilities exchange, at
+ which time the connection can be rejected if the identity is
+ objectionable.&BR;
+ The number of connections established depends on the user's
+ configuration. Multiple connections per peer is possible.</cell>
+</row>
+<row>
+ <cell>5.2</cell>
+ <cell>Diameter Peer Discovery</cell>
+ <cell>NC</cell>
+ <cell>No form of peer discovery is implemented.
+ The user can implement this independently of diameter if
+ required.</cell>
+</row>
+<row>
+ <cell>5.3</cell>
+ <cell>Capabilities Exchange</cell>
+ <cell>C</cell>
+ <cell>All supported applications are sent in CEA.
+ The user can reject an incoming CER or CEA in a configured
+ callback.&BR;
+ Both transport security at connection establishment and
+ negotiated via an Inband-Security AVP are supported.</cell>
+</row>
+<row>
+ <cell>5.3.1</cell>
+ <cell>Capabilities-Exchange-Request</cell>
+ <cell>C</cell>
+ <cell>CER is sent and received by diameter.</cell>
+</row>
+<row>
+ <cell>5.3.2</cell>
+ <cell>Capabilities-Exchange-Answer</cell>
+ <cell>C</cell>
+ <cell>CEA is sent and received by diameter.</cell>
+</row>
+<row>
+ <cell>5.3.3</cell>
+ <cell>Vendor-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.3.4</cell>
+ <cell>Firmware-Revision AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.3.5</cell>
+ <cell>Host-IP-Address AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.3.6</cell>
+ <cell>Supported-Vendor-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.3.7</cell>
+ <cell>Product-Name AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.4</cell>
+ <cell>Disconnecting Peer Connections</cell>
+ <cell>C</cell>
+ <cell>DPA will not be answered with error: a peer that wants to a
+ avoid a race can wait for pending answers before sending
+ DPR.</cell>
+</row>
+<row>
+ <cell>5.4.1</cell>
+ <cell>Disconnect-Peer-Request</cell>
+ <cell>C</cell>
+ <cell>DPR is sent by diameter in response to configuration
+ changes requiring a connection to be broken.
+ The user can also send DPR.</cell>
+</row>
+<row>
+ <cell>5.4.2</cell>
+ <cell>Disconnect-Peer-Answer</cell>
+ <cell>C</cell>
+ <cell>DPR is answered by diameter.</cell>
+</row>
+<row>
+ <cell>5.4.3</cell>
+ <cell>Disconnect-Cause AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.5</cell>
+ <cell>Transport Failure Detection</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.5.1</cell>
+ <cell>Device-Watchdog-Request</cell>
+ <cell>C</cell>
+ <cell>DWR is sent and received by diameter.
+ Callbacks notify the user of transitions into and out of the OKAY
+ state.</cell>
+</row>
+<row>
+ <cell>5.5.2</cell>
+ <cell>Device-Watchdog-Answer</cell>
+ <cell>C</cell>
+ <cell>DWA is sent and received by diameter.</cell>
+</row>
+<row>
+ <cell>5.5.3</cell>
+ <cell>Transport Failure Algorithm</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.5.4</cell>
+ <cell>Failover and Failback Procedures</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.6</cell>
+ <cell>Peer State Machine</cell>
+ <cell>PC</cell>
+ <cell>The election process is modified as described in 5.6.4.</cell>
+</row>
+<row>
+ <cell>5.6.1</cell>
+ <cell>Incoming Connections</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.6.2</cell>
+ <cell>Events</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.6.3</cell>
+ <cell>Actions</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>5.6.4</cell>
+ <cell>The Election Process</cell>
+ <cell>PC</cell>
+ <cell>As documented, the election assumes knowledge of a peer's
+ DiameterIdentity when initiating a connection, which diameter
+ doesn't require. Connections will be accepted if configuration
+ allows multiple connections per peer to be established or there is
+ no existing connection. Note that the election process is only
+ applicable when multiple connections per peer is
+ disallowed.</cell>
+</row>
+<row>
+ <cell>6</cell>
+ <cell>Diameter Message Processing</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.1</cell>
+ <cell>Diameter Request Routing Overview</cell>
+ <cell>&NA;</cell>
+ <cell>Routing is performed by the user.
+ A callback from diameter provides a list of available suitable peer
+ connections.</cell>
+</row>
+<row>
+ <cell>6.1.1</cell>
+ <cell>Originating a Request</cell>
+ <cell>C</cell>
+ <cell>Requests are constructed by the user; diameter sets header
+ fields as defined in the relevant dictionary.</cell>
+</row>
+<row>
+ <cell>6.1.2</cell>
+ <cell>Sending a Request</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.1.3</cell>
+ <cell>Receiving Requests</cell>
+ <cell>C</cell>
+ <cell>Loops are detected by diameter when the return value of a
+ request callback asks that a request be forwarded.
+ Loop detection in other cases is the responsibility of the
+ user.</cell>
+</row>
+<row>
+ <cell>6.1.4</cell>
+ <cell>Processing Local Requests</cell>
+ <cell>C</cell>
+ <cell>The user decides whether or not to process a request locally
+ in the request callback from diameter.</cell>
+</row>
+<row>
+ <cell>6.1.5</cell>
+ <cell>Request Forwarding</cell>
+ <cell>PC</cell>
+ <cell>See 2.6.</cell>
+</row>
+<row>
+ <cell>6.1.6</cell>
+ <cell>Request Routing</cell>
+ <cell>PC</cell>
+ <cell>See 2.7.</cell>
+</row>
+<row>
+ <cell>6.1.7</cell>
+ <cell>Predictive Loop Avoidance</cell>
+ <cell>C</cell>
+ <cell>See 6.1.3.</cell>
+</row>
+<row>
+ <cell>6.1.8</cell>
+ <cell>Redirecting Requests</cell>
+ <cell>PC</cell>
+ <cell>See 2.6.</cell>
+</row>
+<row>
+ <cell>6.1.9</cell>
+ <cell>Relaying and Proxying Requests</cell>
+ <cell>C</cell>
+ <cell>A Route-Record AVP is appended by diameter when the return
+ value of a request callback asks that a request be forwarded.
+ Appending the AVP in other cases is the responsibility of the
+ user.</cell>
+</row>
+<row>
+ <cell>6.2</cell>
+ <cell>Diameter Answer Processing</cell>
+ <cell>C</cell>
+ <cell>Answer message are constructed by the user, except in the case
+ of some protocol errors, in which case the procedures are
+ followed.</cell>
+</row>
+<row>
+ <cell>6.2.1</cell>
+ <cell>Processing Received Answers</cell>
+ <cell>C</cell>
+ <cell>Answers with an unknown Hop-by-Hop Identifier are
+ discarded.</cell>
+</row>
+<row>
+ <cell>6.2.2</cell>
+ <cell>Relaying and Proxying Answers</cell>
+ <cell>&NA;</cell>
+ <cell>Modifying answers is the responsibility of the user in
+ callbacks from diameter.</cell>
+</row>
+<row>
+ <cell>6.3</cell>
+ <cell>Origin-Host AVP</cell>
+ <cell>C</cell>
+ <cell>The order of AVPs in an encoded message is determined by
+ the CCF of the message in question.&BR;
+ AVPs defined in the RFC are defined in dictionaries provided by
+ diameter.
+ Their proper use in application messages is the responsibility of
+ the user.</cell>
+</row>
+<row>
+ <cell>6.4</cell>
+ <cell>Origin-Realm AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.5</cell>
+ <cell>Destination-Host AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.6</cell>
+ <cell>Destination-Realm AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.7</cell>
+ <cell>Routing AVPs</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.7.1</cell>
+ <cell>Route-Record AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.7.2</cell>
+ <cell>Proxy-Info AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.7.3</cell>
+ <cell>Proxy-Host AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.7.4</cell>
+ <cell>Proxy-State AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.8</cell>
+ <cell>Auth-Application-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.9</cell>
+ <cell>Acct-Application-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.10</cell>
+ <cell>Inband-Security-Id AVP</cell>
+ <cell>C</cell>
+ <cell>See 2.1.</cell>
+</row>
+<row>
+ <cell>6.11</cell>
+ <cell>Vendor-Specific-Application-Id AVP</cell>
+ <cell>C</cell>
+ <cell>Note that the CCF of this AVP is not the same as in RFC
+ 3588.</cell>
+</row>
+<row>
+ <cell>6.12</cell>
+ <cell>Redirect-Host AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.13</cell>
+ <cell>Redirect-Host-Usage AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>6.14</cell>
+ <cell>Redirect-Max-Cache-Time AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7</cell>
+ <cell>Error Handling</cell>
+ <cell>C</cell>
+ <cell>Answers are formulated by the user in most cases.
+ Answers setting the E-bit can be sent by diameter itself in response
+ to a request that cannot be handled by the user.</cell>
+</row>
+<row>
+ <cell>7.1</cell>
+ <cell>Result-Code AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7.1.1</cell>
+ <cell>Informational</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7.1.2</cell>
+ <cell>Success</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7.1.3</cell>
+ <cell>Protocol Errors</cell>
+ <cell>C</cell>
+ <cell>Result codes 3001, 3002, 3005, and 3007 can be sent in answers
+ formulated by diameter, if configured to do so.</cell>
+</row>
+<row>
+ <cell>7.1.4</cell>
+ <cell>Transient Failures</cell>
+ <cell>C</cell>
+ <cell>Result code 4003 is sent in CEA if there is an existing
+ connection to the peer in question and configuration does not allow
+ more than one.</cell>
+</row>
+<row>
+ <cell>7.1.5</cell>
+ <cell>Permanent Failures</cell>
+ <cell>C</cell>
+ <cell>Message reception detects 5001, 5004,
+ 5005, 5008, 5009, 5010, 5011, 5014, 5015, and 5017 errors.
+ It ignores 5013 errors at the admonition of sections 3 and 4.1.&BR;
+ Note that RFC 3588 did not allow 5xxx result codes in
+ answers setting the E-bit, while RFC 6733 does.
+ This is a potential interoperability problem since the Diameter
+ protocol version has not changed.</cell>
+</row>
+<row>
+ <cell>7.2</cell>
+ <cell>Error Bit</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7.3</cell>
+ <cell>Error-Message AVP</cell>
+ <cell>C</cell>
+ <cell>The user can include this AVP as required.</cell>
+</row>
+<row>
+ <cell>7.4</cell>
+ <cell>Error-Reporting-Host AVP</cell>
+ <cell>C</cell>
+ <cell>The user can include this AVP as required.</cell>
+</row>
+<row>
+ <cell>7.5</cell>
+ <cell>Failed-AVP AVP</cell>
+ <cell>C</cell>
+ <cell>The user constructs application-specific messages, but
+ diameter provides failed AVPs in message callbacks. Failed component AVPs
+ are grouped within the relevant Grouped AVPs.</cell>
+</row>
+<row>
+ <cell>7.6</cell>
+ <cell>Experimental-Result AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>7.7</cell>
+ <cell>Experimental-Result-Code AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8</cell>
+ <cell>Diameter User Sessions</cell>
+ <cell>&NA;</cell>
+ <cell>Authorization and accounting AVPs are defined in provided
+ dictionaries. Their proper use is the responsibility of the
+ user.</cell>
+</row>
+<row>
+ <cell>8.1</cell>
+ <cell>Authorization Session State Machine</cell>
+ <cell>&NA;</cell>
+ <cell>Authorization is the responsibility of the user: diameter does
+ not implement this state machine.</cell>
+</row>
+<row>
+ <cell>8.2</cell>
+ <cell>Accounting Session State Machine</cell>
+ <cell>&NA;</cell>
+ <cell>Accounting is the responsibility of the user: diameter does
+ not implement this state machine.</cell>
+</row>
+<row>
+ <cell>8.3</cell>
+ <cell>Server-Initiated Re-Auth</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.3.1</cell>
+ <cell>Re-Auth-Request</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.3.2</cell>
+ <cell>Re-Auth-Answer</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.4</cell>
+ <cell>Session Termination</cell>
+ <cell>&NA;</cell>
+ <cell>Session-related messages and AVPs are defined in provided
+ dictionaries. Their proper use is the user's responsibility.</cell>
+</row>
+<row>
+ <cell>8.4.1</cell>
+ <cell>Session-Termination-Request</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.4.2</cell>
+ <cell>Session-Termination-Answer</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.5</cell>
+ <cell>Aborting a Session</cell>
+ <cell>&NA;</cell>
+ <cell>Session-related messages and AVPs are defined in provided
+ dictionaries. Their proper use is the user's responsibility.</cell>
+</row>
+<row>
+ <cell>8.5.1</cell>
+ <cell>Abort-Session-Request</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.5.2</cell>
+ <cell>Abort-Session-Answer</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.6</cell>
+ <cell>Inferring Session Termination from Origin-State-Id</cell>
+ <cell>&NA;</cell>
+ <cell>Session-related messages and AVPs are defined in provided
+ dictionaries. Their proper use is the user's responsibility.</cell>
+</row>
+<row>
+ <cell>8.7</cell>
+ <cell>Auth-Request-Type AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.8</cell>
+ <cell>Session-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.9</cell>
+ <cell>Authorization-Lifetime AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.10</cell>
+ <cell>Auth-Grace-Period AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.11</cell>
+ <cell>Auth-Session-State AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.12</cell>
+ <cell>Re-Auth-Request-Type AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.13</cell>
+ <cell>Session-Timeout AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.14</cell>
+ <cell>User-Name AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.15</cell>
+ <cell>Termination-Cause AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.16</cell>
+ <cell>Origin-State-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.17</cell>
+ <cell>Session-Binding AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.18</cell>
+ <cell>Session-Server-Failover AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.19</cell>
+ <cell>Multi-Round-Time-Out AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.20</cell>
+ <cell>Class AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>8.21</cell>
+ <cell>Event-Timestamp AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9</cell>
+ <cell>Accounting</cell>
+ <cell>&NA;</cell>
+ <cell>Accounting-related messages and AVPs are defined in provided
+ dictionaries. Their proper use is the user's responsibility.</cell>
+</row>
+<row>
+ <cell>9.1</cell>
+ <cell>Server Directed Model</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.2</cell>
+ <cell>Protocol Messages</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.3</cell>
+ <cell>Accounting Application Extension and Requirements</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.4</cell>
+ <cell>Fault Resilience</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.5</cell>
+ <cell>Accounting Records</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.6</cell>
+ <cell>Correlation of Accounting Records</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.7</cell>
+ <cell>Accounting Command Codes</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.7.1</cell>
+ <cell>Accounting-Request</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.7.2</cell>
+ <cell>Accounting-Answer</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8</cell>
+ <cell>Accounting AVPs</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.1</cell>
+ <cell>Accounting-Record-Type AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.2</cell>
+ <cell>Acct-Interim-Interval AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.3</cell>
+ <cell>Accounting-Record-Number AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.4</cell>
+ <cell>Acct-Session-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.5</cell>
+ <cell>Acct-Multi-Session-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.6</cell>
+ <cell>Accounting-Sub-Session-Id AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>9.8.7</cell>
+ <cell>Accounting-Realtime-Required AVP</cell>
+ <cell>C</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>10</cell>
+ <cell>AVP Occurrence Tables</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>10.1</cell>
+ <cell>Base Protocol Command AVP Table</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>10.2</cell>
+ <cell>Accounting AVP Table</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11</cell>
+ <cell>IANA Considerations</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.1</cell>
+ <cell>AVP Header</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.1.1</cell>
+ <cell>AVP Codes</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.1.2</cell>
+ <cell>AVP Flags</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.2</cell>
+ <cell>Diameter Header</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.2.1</cell>
+ <cell>Command Codes</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.2.2</cell>
+ <cell>Command Flags</cell>
+ <cell></cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3</cell>
+ <cell>AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.1</cell>
+ <cell>Experimental-Result-Code AVP</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.2</cell>
+ <cell>Result-Code AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.3</cell>
+ <cell>Accounting-Record-Type AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.4</cell>
+ <cell>Termination-Cause AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.5</cell>
+ <cell>Redirect-Host-Usage AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.6</cell>
+ <cell>Session-Server-Failover AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.7</cell>
+ <cell>Session-Binding AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.8</cell>
+ <cell>Disconnect-Cause AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.9</cell>
+ <cell>Auth-Request-Type AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.10</cell>
+ <cell>Auth-Session-State AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.11</cell>
+ <cell>Re-Auth-Request-Type AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.12</cell>
+ <cell>Accounting-Realtime-Required AVP Values</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.3.13</cell>
+ <cell>Inband-Security-Id AVP (code 299)</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.4</cell>
+ <cell>_diameters Service Name and Port Number Registration</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.5</cell>
+ <cell>SCTP Payload Protocol Identifiers</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>11.6</cell>
+ <cell>S-NAPTR Parameters</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>12</cell>
+ <cell>Diameter Protocol-Related Configurable Parameters</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>13</cell>
+ <cell>Security Considerations</cell>
+ <cell>PC</cell>
+ <cell>See 2.1.&BR;
+ IPsec is transparent to diameter.</cell>
+</row>
+<row>
+ <cell>13.1</cell>
+ <cell>TLS/TCP and DTLS/SCTP Usage</cell>
+ <cell>PC</cell>
+ <cell>See 2.1.</cell>
+</row>
+<row>
+ <cell>13.2</cell>
+ <cell>Peer-to-Peer Considerations</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>13.3</cell>
+ <cell>AVP Considerations</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>14</cell>
+ <cell>References</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>14.1</cell>
+ <cell>Normative References</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+<row>
+ <cell>14.2</cell>
+ <cell>Informative References</cell>
+ <cell>&NA;</cell>
+ <cell></cell>
+</row>
+
+<tcaption>RFC 6733 Compliance</tcaption>
+</table>
</section>
</chapter>
+
+<!-- LocalWords: AVP AVPs CCF DiameterIdentity CEA CER Inband IP
+-->
+<!-- LocalWords: DPA DPR DWR DWA Failover Failback Proxying Auth
+-->
+<!-- LocalWords: interoperability Multi Timestamp Realtime
+-->
diff --git a/lib/diameter/doc/src/diameter_soc_rfc6733.xml b/lib/diameter/doc/src/diameter_soc_rfc6733.xml
deleted file mode 100644
index 2098965706..0000000000
--- a/lib/diameter/doc/src/diameter_soc_rfc6733.xml
+++ /dev/null
@@ -1,8693 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-
-<!--
-
-<copyright>
-<year>2013</year><year>2016</year>
-<holder>Ericsson AB. All Rights Reserved.</holder>
-</copyright>
-
-<legalnotice>
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-</legalnotice>
-
--->
-
-<!DOCTYPE section SYSTEM "chapter.dtd" [
- <!ENTITY gen_sctp '<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>'>
- <!ENTITY gen_tcp '<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>'>
- <!ENTITY service '<seealso marker="diameter#start_service-2">service</seealso>'>
- <!ENTITY capabilities '<seealso marker="diameter#capability">capabilities</seealso>'>
- <!ENTITY events '<seealso marker="diameter#service_event">events</seealso>'>
- <!ENTITY nada '<p>No comment.</p>'>
- <!ENTITY % also SYSTEM "seealso.ent" >
- %also;
-]>
-
-<section>
-<title>Commentary</title>
-
-<p>
-A more detailed commentary on &the_rfc; follows.
-Its purpose is to (hopefully) clarify not only what is supported but
-how, given that semantics and features discussed in the RFC are not
-solely the responsibility of the diameter application:
-in many cases much depends on the configuration a user passes to
-diameter, the implementation of &man_app; callback modules in
-particular.</p>
-
-<p>
-Comments apply to all text following the preceding comment.
-Be sure to distinguish between capitalized <em>Diameter</em>, the
-protocol defined by the RFC, and lowercase <em>diameter</em>, the
-Erlang application to which the commentary applies.</p>
-
-<warning>
-<p>
-The commentary is not yet complete.
-Comments currently stop at chapter 4.</p>
-</warning>
-
-<pre>
-Fajardo, et al. Standards Track [Page 6]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-1. Introduction
-
- Authentication, Authorization, and Accounting (AAA) protocols such as
- TACACS [RFC1492] and RADIUS [RFC2865] were initially deployed to
- provide dial-up PPP [RFC1661] and terminal server access. Over time,
- AAA support was needed on many new access technologies, the scale and
- complexity of AAA networks grew, and AAA was also used on new
- applications (such as voice over IP). This led to new demands on AAA
- protocols.
-</pre>
-
-<p>
-Note that diameter implements the Diameter protocol as defined in
-&the_rfc;.
-It also supported the previous version of the protocol, as defined in
-RFC 3588, when there are differences.
-(Which will be noted below.)
-It does not support RADIUS.</p>
-
-<pre>
-
- Network access requirements for AAA protocols are summarized in
- Aboba, et al. [RFC2989]. These include:
-
- Failover
-
- [RFC2865] does not define failover mechanisms and, as a result,
- failover behavior differs between implementations. In order to
- provide well-defined failover behavior, Diameter supports
- application-layer acknowledgements and defines failover algorithms
- and the associated state machine.
-</pre>
-
-&nada;
-
-<pre>
-
- Transmission-level security
-
- RADIUS [RFC2865] defines an application-layer authentication and
- integrity scheme that is required only for use with response
- packets. While [RFC2869] defines an additional authentication and
- integrity mechanism, use is only required during Extensible
- Authentication Protocol (EAP) [RFC3748] sessions. While attribute
- hiding is supported, [RFC2865] does not provide support for per-
- packet confidentiality. In accounting, [RFC2866] assumes that
- replay protection is provided by the backend billing server rather
- than within the protocol itself.
-
- While [RFC3162] defines the use of IPsec with RADIUS, support for
- IPsec is not required. In order to provide universal support for
- transmission-level security, and enable both intra- and inter-
- domain AAA deployments, Diameter provides support for TLS/TCP and
- DTLS/SCTP. Security is discussed in Section 13.
-</pre>
-
-<p>
-Whether or not IPsec is used is transparent to diameter.</p>
-
-<p>
-The transport protocol used on a given peer connection is also
-transparent to diameter in that transport to diameter is simply a
-module that implements the transport protocol documented in
-&man_transport;.
-A diameter user configures this module as the &mod_transport_opt;
-<c>transport_module</c>.</p>
-
-<p>
-While a user can implement their own transport modules, diameter
-includes implementations for TCP and SCTP:
-&man_tcp; based on &gen_tcp; and &man_sctp; based on &gen_sctp;.
-The former supports TLS but the latter does not currently support
-DTLS.</p>
-
-<pre>
-
- Reliable transport
-
- RADIUS runs over UDP, and does not define retransmission behavior;
- as a result, reliability varies between implementations. As
- described in [RFC2975], this is a major issue in accounting, where
- packet loss may translate directly into revenue loss. In order to
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 7]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- provide well-defined transport behavior, Diameter runs over
- reliable transport mechanisms (TCP, Stream Control Transmission
- Protocol (SCTP)) as defined in [RFC3539].
-
- Agent support
-
- RADIUS does not provide for explicit support for agents, including
- proxies, redirects, and relays. Since the expected behavior is
- not defined, it varies between implementations. Diameter defines
- agent behavior explicitly; this is described in Section 2.8.
-</pre>
-
-&nada;
-
-<pre>
-
- Server-initiated messages
-
- While server-initiated messages are defined in RADIUS [RFC5176],
- support is optional. This makes it difficult to implement
- features such as unsolicited disconnect or re-authentication/
- re-authorization on demand across a heterogeneous deployment. To
- address this issue, support for server-initiated messages is
- mandatory in Diameter.
-</pre>
-
-<p>
-A diameter user can both send and receive messages.</p>
-
-<pre>
-
- Transition support
-
- While Diameter does not share a common protocol data unit (PDU)
- with RADIUS, considerable effort has been expended in enabling
- backward compatibility with RADIUS so that the two protocols may
- be deployed in the same network. Initially, it is expected that
- Diameter will be deployed within new network devices, as well as
- within gateways enabling communication between legacy RADIUS
- devices and Diameter agents. This capability enables Diameter
- support to be added to legacy networks, by addition of a gateway
- or server speaking both RADIUS and Diameter.
-</pre>
-
-<p>
-RADIUS Attributes can be redefined as Diameter AVP's using diameter's
-&man_dict; interface but diameter provides no such definitions.</p>
-
-<pre>
-
- In addition to addressing the above requirements, Diameter also
- provides support for the following:
-
- Capability negotiation
-
- RADIUS does not support error messages, capability negotiation, or
- a mandatory/non-mandatory flag for attributes. Since RADIUS
- clients and servers are not aware of each other's capabilities,
- they may not be able to successfully negotiate a mutually
- acceptable service or, in some cases, even be aware of what
- service has been implemented. Diameter includes support for error
- handling (Section 7), capability negotiation (Section 5.3), and
- mandatory/non-mandatory Attribute-Value Pairs (AVPs)
- (Section 4.1).
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 8]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Peer discovery and configuration
-
- RADIUS implementations typically require that the name or address
- of servers or clients be manually configured, along with the
- corresponding shared secrets. This results in a large
- administrative burden and creates the temptation to reuse the
- RADIUS shared secret, which can result in major security
- vulnerabilities if the Request Authenticator is not globally and
- temporally unique as required in [RFC2865]. Through DNS, Diameter
- enables dynamic discovery of peers (see Section 5.2). Derivation
- of dynamic session keys is enabled via transmission-level
- security.
-
- Over time, the capabilities of Network Access Server (NAS) devices
- have increased substantially. As a result, while Diameter is a
- considerably more sophisticated protocol than RADIUS, it remains
- feasible to implement it within embedded devices.
-</pre>
-
-&nada;
-
-<pre>
-
-1.1. Diameter Protocol
-
- The Diameter base protocol provides the following facilities:
-
- o Ability to exchange messages and deliver AVPs
-</pre>
-
-<p>
-There are two interfaces directly involved in message exchange when
-using diameter: the function &mod_call; for sending outgoing requests,
-and the application callback interface, documented in &man_app; for
-receiving incoming request and answers.</p>
-
-<pre>
-
- o Capabilities negotiation
-</pre>
-
-<p>
-Capabilities negotiation is the responsibility of diameter:
-a user configures a diameter service and/or transport with
-&capabilities; to provide AVP values for CER and CEA messages but it
-is diameter itself that sends these messages.
-A user receives notification of a successful capabilities exchange by
-way of &app_peer_up; callbacks.</p>
-
-<pre>
-
- o Error notification
-</pre>
-
-<p>
-A user can subscribe to &events;, using &mod_subscribe;, in order to
-receive notification of various failures.
-Errors in Diameter messaging are communicated via the application
-callbacks &app_handle_request;, &app_handle_answer; and
-&app_handle_error;.</p>
-
-
-<pre>
-
- o Extensibility, required in [RFC2989], through addition of new
- applications, commands, and AVPs
-</pre>
-
-<p>
-Support for applications, commands and AVP's is extensible using
-diameter's dictionary interface, as documented in &man_dict;.
-Dictionaries are compiled to Erlang encode/decode modules using
-&man_compile; or &man_make;.</p>
-
-<pre>
-
- o Basic services necessary for applications, such as the handling of
- user sessions or accounting
-</pre>
-
-<p>
-Compiled dictionaries are provided for the RFC 3588 and RFC 6733
-Diameter applications: common, base accounting and relay.
-Dictionaries for a number of standardized
-applications are provided in uncompiled form below the <c>examples</c>
-subdirectory of the diameter application directory.</p>
-
-<pre>
-
- All data delivered by the protocol is in the form of AVPs. Some of
- these AVP values are used by the Diameter protocol itself, while
- others deliver data associated with particular applications that
- employ Diameter. AVPs may be arbitrarily added to Diameter messages,
- the only restriction being that the Command Code Format (CCF)
- specification (Section 3.2) be satisfied. AVPs are used by the base
- Diameter protocol to support the following required features:
-
- o Transporting of user authentication information, for the purposes
- of enabling the Diameter server to authenticate the user
-
- o Transporting of service-specific authorization information,
- between client and servers, allowing the peers to decide whether a
- user's access request should be granted
-
-
-
-Fajardo, et al. Standards Track [Page 9]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o Exchanging resource usage information, which may be used for
- accounting purposes, capacity planning, etc.
-
- o Routing, relaying, proxying, and redirecting of Diameter messages
- through a server hierarchy
-
- The Diameter base protocol satisfies the minimum requirements for a
- AAA protocol, as specified by [RFC2989]. The base protocol may be
- used by itself for accounting purposes only, or it may be used with a
- Diameter application, such as Mobile IPv4 [RFC4004], or network
- access [RFC4005]. It is also possible for the base protocol to be
- extended for use in new applications, via the addition of new
- commands or AVPs. The initial focus of Diameter was network access
- and accounting applications. A truly generic AAA protocol used by
- many applications might provide functionality not provided by
- Diameter. Therefore, it is imperative that the designers of new
- applications understand their requirements before using Diameter.
- See Section 1.3.4 for more information on Diameter applications.
-
- Any node can initiate a request. In that sense, Diameter is a peer-
- to-peer protocol. In this document, a Diameter client is a device at
- the edge of the network that performs access control, such as a
- Network Access Server (NAS) or a Foreign Agent (FA). A Diameter
- client generates Diameter messages to request authentication,
- authorization, and accounting services for the user. A Diameter
- agent is a node that does not provide local user authentication or
- authorization services; agents include proxies, redirects, and relay
- agents. A Diameter server performs authentication and/or
- authorization of the user. A Diameter node may act as an agent for
- certain requests while acting as a server for others.
-
- The Diameter protocol also supports server-initiated messages, such
- as a request to abort service to a particular user.
-</pre>
-
-&nada;
-
-<pre>
-
-1.1.1. Description of the Document Set
-
- The Diameter specification consists of an updated version of the base
- protocol specification (this document) and the Transport Profile
- [RFC3539]. This document obsoletes both RFC 3588 and RFC 5719. A
- summary of the base protocol updates included in this document can be
- found in Section 1.1.3.
-
- This document defines the base protocol specification for AAA, which
- includes support for accounting. There are also a myriad of
- applications documents describing applications that use this base
- specification for Authentication, Authorization, and Accounting.
- These application documents specify how to use the Diameter protocol
- within the context of their application.
-
-
-
-Fajardo, et al. Standards Track [Page 10]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The Transport Profile document [RFC3539] discusses transport layer
- issues that arise with AAA protocols and recommendations on how to
- overcome these issues. This document also defines the Diameter
- failover algorithm and state machine.
-
- "Clarifications on the Routing of Diameter Request Based on the
- Username and the Realm" [RFC5729] defines specific behavior on how to
- route requests based on the content of the User-Name AVP (Attribute
- Value Pair).
-
-1.1.2. Conventions Used in This Document
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-</pre>
-
-&nada;
-
-<pre>
-
-1.1.3. Changes from RFC 3588
-
- This document obsoletes RFC 3588 but is fully backward compatible
- with that document. The changes introduced in this document focus on
- fixing issues that have surfaced during the implementation of
- Diameter (RFC 3588). An overview of some the major changes are given
- below.
-</pre>
-
-<p>
-RFC 6733 is not fully backwards compatible with RFC 3588.
-(For example, in what values of Result-Code values are permissible with
-the E-bit.)
-The implications of incompatibilities for diameter are noted where
-appropriate.</p>
-
-<pre>
-
- o Deprecated the use of the Inband-Security AVP for negotiating
- Transport Layer Security (TLS) [RFC5246]. It has been generally
- considered that bootstrapping of TLS via Inband-Security AVP
- creates certain security risks because it does not completely
- protect the information carried in the CER/CEA (Capabilities-
- Exchange-Request/Capabilities-Exchange-Answer). This version of
- Diameter adopts the common approach of defining a well-known
- secured port that peers should use when communicating via TLS/TCP
- and DTLS/SCTP. This new approach augments the existing in-band
- security negotiation, but it does not completely replace it. The
- old method is kept for backward compatibility reasons.
-</pre>
-
-<p>
-&man_tcp; supports both methods of negotiating TLS:
-bootstrapping via Inband-Security and directly following connection
-establishment.</p>
-
-<pre>
-
- o Deprecated the exchange of CER/CEA messages in the open state.
- This feature was implied in the peer state machine table of RFC
- 3588, but it was not clearly defined anywhere else in that
- document. As work on this document progressed, it became clear
- that the multiplicity of meaning and use of Application-Id AVPs in
- the CER/CEA messages (and the messages themselves) is seen as an
- abuse of the Diameter extensibility rules and thus required
- simplification. Capabilities exchange in the open state has been
- re-introduced in a separate specification [RFC6737], which clearly
- defines new commands for this feature.
-</pre>
-
-<p>
-Capabilities exchange in the open state is not supported: an incoming
-CER in the open state will cause diameter to ask the relevant
-transport process to terminate, which implies the loss of the peer
-connection in the case of &man_tcp; and &man_sctp;.</p>
-
-<p>
-Capabilities update, as defined by RFC 6737, is not yet supported.
-Support will require diameter to handle CUR/CUA in the same way that
-it handles CER/CEA.</p>
-
-<pre>
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 11]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o Simplified security requirements. The use of a secured transport
- for exchanging Diameter messages remains mandatory. However, TLS/
- TCP and DTLS/SCTP have become the primary methods of securing
- Diameter with IPsec as a secondary alternative. See Section 13
- for details. The support for the End-to-End security framework
- (E2E-Sequence AVP and 'P'-bit in the AVP header) has also been
- deprecated.
-</pre>
-
-<p>
-The End-to-End security framework is not supported since it's use is
-largely unspecified: diameter will set the P-bit in outgoing AVP's as
-directed by the relevant dictionary and/or &app_prepare_request; or
-&app_handle_request; callbacks, but whether or not the P-bit is set on
-incoming AVP's has no consequence.</p>
-
-<p>
-As noted above, DTLS is not currently supported and whether or not
-IPsec is used is transparent to diameter.</p>
-
-<pre>
-
- o Changed Diameter extensibility. This includes fixes to the
- Diameter extensibility description (Section 1.3 and others) to
- better aid Diameter application designers; in addition, the new
- specification relaxes the policy with respect to the allocation of
- Command Codes for vendor-specific uses.
-
- o Clarified Application Id usage. Clarify the proper use of
- Application Id information, which can be found in multiple places
- within a Diameter message. This includes correlating Application
- Ids found in the message headers and AVPs. These changes also
- clearly specify the proper Application Id value to use for
- specific base protocol messages (ASR/ASA, STR/STA) as well as
- clarify the content and use of Vendor-Specific-Application-Id.
-
- o Clarified routing fixes. This document more clearly specifies
- what information (AVPs and Application Ids) can be used for making
- general routing decisions. A rule for the prioritization of
- redirect routing criteria when multiple route entries are found
- via redirects has also been added (see Section 6.13).
-
- o Simplified Diameter peer discovery. The Diameter discovery
- process now supports only widely used discovery schemes; the rest
- have been deprecated (see Section 5.2 for details).
-</pre>
-
-<p>
-Peer discover is not currently supported: peers to which a node should
-connect must be configured.
-Connection requests are accepted from arbitrary peers but a
-&mod_transport_opt; <c>capabilities_cb</c> can be used to reject a
-peer based on an incoming CER or CEA.</p>
-
-<pre>
-
- There are many other miscellaneous fixes that have been introduced in
- this document that may not be considered significant, but they have
- value nonetheless. Examples are removal of obsolete types, fixes to
- the state machine, clarification of the election process, message
- validation, fixes to Failed-AVP and Result-Code AVP values, etc. All
- of the errata filed against RFC 3588 prior to the publication of this
- document have been addressed. A comprehensive list of changes is not
- shown here for practical reasons.
-
-1.2. Terminology
-
- AAA
-
- Authentication, Authorization, and Accounting.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 12]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- ABNF
-
- Augmented Backus-Naur Form [RFC5234]. A metalanguage with its own
- formal syntax and rules. It is based on the Backus-Naur Form and
- is used to define message exchanges in a bi-directional
- communications protocol.
-
- Accounting
-
- The act of collecting information on resource usage for the
- purpose of capacity planning, auditing, billing, or cost
- allocation.
-
- Accounting Record
-
- An accounting record represents a summary of the resource
- consumption of a user over the entire session. Accounting servers
- creating the accounting record may do so by processing interim
- accounting events or accounting events from several devices
- serving the same user.
-
- Authentication
-
- The act of verifying the identity of an entity (subject).
-
- Authorization
-
- The act of determining whether a requesting entity (subject) will
- be allowed access to a resource (object).
-
- Attribute-Value Pair (AVP)
-
- The Diameter protocol consists of a header followed by one or more
- Attribute-Value-Pairs (AVPs). An AVP includes a header and is
- used to encapsulate protocol-specific data (e.g., routing
- information) as well as authentication, authorization, or
- accounting information.
-</pre>
-
-&nada;
-
-<pre>
-
- Command Code Format (CCF)
-
- A modified form of ABNF used to define Diameter commands (see
- Section 3.2).
-</pre>
-
-<p>
-The <c>@messages</c> section of the &man_dict; format has the CCF as
-content.</p>
-
-<pre>
-
- Diameter Agent
-
- A Diameter Agent is a Diameter node that provides relay, proxy,
- redirect, or translation services.
-
-
-
-
-Fajardo, et al. Standards Track [Page 13]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Diameter Client
-
- A Diameter client is a Diameter node that supports Diameter client
- applications as well as the base protocol. Diameter clients are
- often implemented in devices situated at the edge of a network and
- provide access control services for that network. Typical
- examples of Diameter clients include the Network Access Server
- (NAS) and the Mobile IP Foreign Agent (FA).
-
- Diameter Node
-
- A Diameter node is a host process that implements the Diameter
- protocol and acts as either a client, an agent, or a server.
-
- Diameter Peer
-
- Two Diameter nodes sharing a direct TCP or SCTP transport
- connection are called Diameter peers.
-
- Diameter Server
-
- A Diameter server is a Diameter node that handles authentication,
- authorization, and accounting requests for a particular realm. By
- its very nature, a Diameter server must support Diameter server
- applications in addition to the base protocol.
-</pre>
-
-<p>
-A Diameter Node is implemented by configuring a service
-using &mod_start_service; and one or more transports using
-&mod_add_transport;.
-The service typically represents a Diameter Node but since
-capabilities can be configured on individual transports it's more
-accurate to say that the node is a collection of transports
-advertising the same Origin-Host.</p>
-
-<p>
-The role of a node (agent, client or server) is not something that's
-configured explicitly.
-Transports are either connecting or listening, depending on whether
-diameter should establish a peer connection and send CER or accept
-connections and receive CER, but the role a node implements depends
-largely on dictionary configuration and &man_app; callback
-implementation.</p>
-
-<pre>
-
- Downstream
-
- Downstream is used to identify the direction of a particular
- Diameter message from the home server towards the Diameter client.
-
- Home Realm
-
- A Home Realm is the administrative domain with which the user
- maintains an account relationship.
-
- Home Server
-
- A Diameter server that serves the Home Realm.
-
- Interim Accounting
-
- An interim accounting message provides a snapshot of usage during
- a user's session. Typically, it is implemented in order to
- provide for partial accounting of a user's session in case a
- device reboot or other network problem prevents the delivery of a
- session summary message or session record.
-
-
-
-
-Fajardo, et al. Standards Track [Page 14]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Local Realm
-
- A local realm is the administrative domain providing services to a
- user. An administrative domain may act as a local realm for
- certain users while being a home realm for others.
-
- Multi-session
-
- A multi-session represents a logical linking of several sessions.
- Multi-sessions are tracked by using the Acct-Multi-Session-Id. An
- example of a multi-session would be a Multi-link PPP bundle. Each
- leg of the bundle would be a session while the entire bundle would
- be a multi-session.
-
- Network Access Identifier
-
- The Network Access Identifier, or NAI [RFC4282], is used in the
- Diameter protocol to extract a user's identity and realm. The
- identity is used to identify the user during authentication and/or
- authorization while the realm is used for message routing
- purposes.
-
- Proxy Agent or Proxy
-
- In addition to forwarding requests and responses, proxies make
- policy decisions relating to resource usage and provisioning.
- Typically, this is accomplished by tracking the state of NAS
- devices. While proxies usually do not respond to client requests
- prior to receiving a response from the server, they may originate
- Reject messages in cases where policies are violated. As a
- result, proxies need to understand the semantics of the messages
- passing through them, and they may not support all Diameter
- applications.
-
- Realm
-
- The string in the NAI that immediately follows the '@' character.
- NAI realm names are required to be unique and are piggybacked on
- the administration of the DNS namespace. Diameter makes use of
- the realm, also loosely referred to as domain, to determine
- whether messages can be satisfied locally or whether they must be
- routed or redirected. In RADIUS, realm names are not necessarily
- piggybacked on the DNS namespace but may be independent of it.
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 15]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Real-Time Accounting
-
- Real-time accounting involves the processing of information on
- resource usage within a defined time window. Typically, time
- constraints are imposed in order to limit financial risk. The
- Diameter Credit-Control Application [RFC4006] is an example of an
- application that defines real-time accounting functionality.
-
- Relay Agent or Relay
-
- Relays forward requests and responses based on routing-related
- AVPs and routing table entries. Since relays do not make policy
- decisions, they do not examine or alter non-routing AVPs. As a
- result, relays never originate messages, do not need to understand
- the semantics of messages or non-routing AVPs, and are capable of
- handling any Diameter application or message type. Since relays
- make decisions based on information in routing AVPs and realm
- forwarding tables, they do not keep state on NAS resource usage or
- sessions in progress.
-
- Redirect Agent
-
- Rather than forwarding requests and responses between clients and
- servers, redirect agents refer clients to servers and allow them
- to communicate directly. Since redirect agents do not sit in the
- forwarding path, they do not alter any AVPs transiting between
- client and server. Redirect agents do not originate messages and
- are capable of handling any message type, although they may be
- configured only to redirect messages of certain types, while
- acting as relay or proxy agents for other types. As with relay
- agents, redirect agents do not keep state with respect to sessions
- or NAS resources.
-</pre>
-
-&nada;
-
-<pre>
-
- Session
-
- A session is a related progression of events devoted to a
- particular activity. Diameter application documents provide
- guidelines as to when a session begins and ends. All Diameter
- packets with the same Session-Id are considered to be part of the
- same session.
-</pre>
-
-<p>
-Sessions are not something that diameter is aware of.
-The function &mod_session_id; can be used to construct appropriate
-values for Session-Id AVP's but logic connecting events in the same
-session is the responsibility of the diameter user.</p>
-
-<pre>
-
- Stateful Agent
-
- A stateful agent is one that maintains session state information,
- by keeping track of all authorized active sessions. Each
- authorized session is bound to a particular service, and its state
- is considered active either until it is notified otherwise or
- until expiration.
-
-
-
-Fajardo, et al. Standards Track [Page 16]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Sub-session
-
- A sub-session represents a distinct service (e.g., QoS or data
- characteristics) provided to a given session. These services may
- happen concurrently (e.g., simultaneous voice and data transfer
- during the same session) or serially. These changes in sessions
- are tracked with the Accounting-Sub-Session-Id.
-
- Transaction State
-
- The Diameter protocol requires that agents maintain transaction
- state, which is used for failover purposes. Transaction state
- implies that upon forwarding a request, the Hop-by-Hop Identifier
- is saved; the field is replaced with a locally unique identifier,
- which is restored to its original value when the corresponding
- answer is received. The request's state is released upon receipt
- of the answer. A stateless agent is one that only maintains
- transaction state.
-
- Translation Agent
-
- A translation agent (TLA in Figure 4) is a stateful Diameter node
- that performs protocol translation between Diameter and another
- AAA protocol, such as RADIUS.
-
- Upstream
-
- Upstream is used to identify the direction of a particular
- Diameter message from the Diameter client towards the home server.
-
- User
-
- The entity or device requesting or using some resource, in support
- of which a Diameter client has generated a request.
-</pre>
-
-&nada;
-
-<pre>
-
-1.3. Approach to Extensibility
-
- The Diameter protocol is designed to be extensible, using several
- mechanisms, including:
-
- o Defining new AVP values
-
- o Creating new AVPs
-
- o Creating new commands
-
- o Creating new applications
-
-
-
-
-Fajardo, et al. Standards Track [Page 17]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- From the point of view of extensibility, Diameter authentication,
- authorization, and accounting applications are treated in the same
- way.
-</pre>
-
-<p>
-Extensibility in diameter is by way of the dictionary interface
-documented in &man_dict;: a diameter user creates applications,
-commands and AVP's by implementing a new dictionary,
-compiling the dictionary to a codec module using &man_compile; or
-&man_make;, and configuring the resulting dictionary module on a
-service.
-The dictionary modules provided with diameter are all implemented in
-this manner.</p>
-
-<pre>
- Note: Protocol designers should try to reuse existing functionality,
- namely AVP values, AVPs, commands, and Diameter applications. Reuse
- simplifies standardization and implementation. To avoid potential
- interoperability issues, it is important to ensure that the semantics
- of the reused features are well understood. Given that Diameter can
- also carry RADIUS attributes as Diameter AVPs, such reuse
- considerations also apply to existing RADIUS attributes that may be
- useful in a Diameter application.
-</pre>
-
-<p>
-Reuse in dictionary files is achieved by way of the <c>@inherits</c>
-section.
-AVP's are inherited, commands are not.</p>
-
-<pre>
-
-1.3.1. Defining New AVP Values
-
- In order to allocate a new AVP value for AVPs defined in the Diameter
- base protocol, the IETF needs to approve a new RFC that describes the
- AVP value. IANA considerations for these AVP values are discussed in
- Section 11.3.
-
- The allocation of AVP values for other AVPs is guided by the IANA
- considerations of the document that defines those AVPs. Typically,
- allocation of new values for an AVP defined in an RFC would require
- IETF Review [RFC5226], whereas values for vendor-specific AVPs can be
- allocated by the vendor.
-
-1.3.2. Creating New AVPs
-
- A new AVP being defined MUST use one of the data types listed in
- Sections 4.2 or 4.3. If an appropriate derived data type is already
- defined, it SHOULD be used instead of a base data type to encourage
- reusability and good design practice.
-
- In the event that a logical grouping of AVPs is necessary, and
- multiple "groups" are possible in a given command, it is recommended
- that a Grouped AVP be used (see Section 4.4).
-
- The creation of new AVPs can happen in various ways. The recommended
- approach is to define a new general-purpose AVP in a Standards Track
- RFC approved by the IETF. However, as described in Section 11.1.1,
- there are other mechanisms.
-</pre>
-
-<p>
-Creating new AVP's is an issue for the dictionary designer, not
-diameter.</p>
-
-<pre>
-
-1.3.3. Creating New Commands
-
- A new Command Code MUST be allocated when required AVPs (those
- indicated as {AVP} in the CCF definition) are added to, deleted from,
- or redefined in (for example, by changing a required AVP into an
- optional one) an existing command.
-
-
-
-Fajardo, et al. Standards Track [Page 18]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Furthermore, if the transport characteristics of a command are
- changed (for example, with respect to the number of round trips
- required), a new Command Code MUST be registered.
-
- A change to the CCF of a command, such as described above, MUST
- result in the definition of a new Command Code. This subsequently
- leads to the need to define a new Diameter application for any
- application that will use that new command.
-
- The IANA considerations for Command Codes are discussed in
- Section 3.1.
-</pre>
-
-<p>
-Creating new commands is an issue for the dictionary designer, not
-diameter.</p>
-
-<pre>
-
-1.3.4. Creating New Diameter Applications
-
- Every Diameter application specification MUST have an IANA-assigned
- Application Id (see Section 2.4). The managed Application ID space
- is flat, and there is no relationship between different Diameter
- applications with respect to their Application Ids. As such, there
- is no versioning support provided by these Application Ids
- themselves; every Diameter application is a standalone application.
- If the application has a relationship with other Diameter
- applications, such a relationship is not known to Diameter.
-</pre>
-
-<p>
-Creating new applications is an issue for the dictionary designer,
-not diameter.</p>
-
-<p>
-An application's Application Id is specified in the <c>@id</c> section
-of a dictionary file.</p>
-
-<pre>
-
- Before describing the rules for creating new Diameter applications,
- it is important to discuss the semantics of the AVP occurrences as
- stated in the CCF and the M-bit flag (Section 4.1) for an AVP. There
- is no relationship imposed between the two; they are set
- independently.
-
- o The CCF indicates what AVPs are placed into a Diameter command by
- the sender of that command. Often, since there are multiple modes
- of protocol interactions, many of the AVPs are indicated as
- optional.
-
- o The M-bit allows the sender to indicate to the receiver whether or
- not understanding the semantics of an AVP and its content is
- mandatory. If the M-bit is set by the sender and the receiver
- does not understand the AVP or the values carried within that AVP,
- then a failure is generated (see Section 7).
-</pre>
-
-<p>
-The M-bit is set on outgoing AVP's as directed by the relevant
-dictionary.
-For incoming AVP's, an M-bit set on an AVP that isn't
-explicitly included in the definition of the command in question is
-interpreted as a 5001 error, DIAMETER_AVP_UNSUPPORTED, the
-consequences of which depend on the value of the &mod_application_opt;
-<c>answer_errors</c> or <c>request_errors</c>.</p>
-
-<pre>
-
- It is the decision of the protocol designer when to develop a new
- Diameter application rather than extending Diameter in other ways.
- However, a new Diameter application MUST be created when one or more
- of the following criteria are met:
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 19]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- M-bit Setting
-
- An AVP with the M-bit in the MUST column of the AVP flag table is
- added to an existing Command/Application. An AVP with the M-bit
- in the MAY column of the AVP flag table is added to an existing
- Command/Application.
-
- Note: The M-bit setting for a given AVP is relevant to an
- Application and each command within that application that includes
- the AVP. That is, if an AVP appears in two commands for
- application Foo and the M-bit settings are different in each
- command, then there should be two AVP flag tables describing when
- to set the M-bit.
-
- Commands
-
- A new command is used within the existing application because
- either an additional command is added, an existing command has
- been modified so that a new Command Code had to be registered, or
- a command has been deleted.
-
- AVP Flag bits
-
- If an existing application changes the meaning/semantics of its
- AVP Flags or adds new flag bits, then a new Diameter application
- MUST be created.
-
- If the CCF definition of a command allows it, an implementation may
- add arbitrary optional AVPs with the M-bit cleared (including vendor-
- specific AVPs) to that command without needing to define a new
- application. Please refer to Section 11.1.1 for details.
-</pre>
-
-&nada;
-
-<pre>
-
-2. Protocol Overview
-
- The base Diameter protocol concerns itself with establishing
- connections to peers, capabilities negotiation, how messages are sent
- and routed through peers, and how the connections are eventually torn
- down. The base protocol also defines certain rules that apply to all
- message exchanges between Diameter nodes.
-
- Communication between Diameter peers begins with one peer sending a
- message to another Diameter peer. The set of AVPs included in the
- message is determined by a particular Diameter application. One AVP
- that is included to reference a user's session is the Session-Id.
-
- The initial request for authentication and/or authorization of a user
- would include the Session-Id AVP. The Session-Id is then used in all
- subsequent messages to identify the user's session (see Section 8 for
-
-
-
-Fajardo, et al. Standards Track [Page 20]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- more information). The communicating party may accept the request or
- reject it by returning an answer message with the Result-Code AVP set
- to indicate that an error occurred. The specific behavior of the
- Diameter server or client receiving a request depends on the Diameter
- application employed.
-
- Session state (associated with a Session-Id) MUST be freed upon
- receipt of the Session-Termination-Request, Session-Termination-
- Answer, expiration of authorized service time in the Session-Timeout
- AVP, and according to rules established in a particular Diameter
- application.
-</pre>
-
-<p>
-Like Session-Id, session state is maintained by the diameter user:
-diameter has no session state of its own and does not interpret
-STR/STA in any way.</p>
-
-<pre>
-
- The base Diameter protocol may be used by itself for accounting
- applications. For authentication and authorization, it is always
- extended for a particular application.
-
- Diameter clients MUST support the base protocol, which includes
- accounting. In addition, they MUST fully support each Diameter
- application that is needed to implement the client's service, e.g.,
- Network Access Server Requirements (NASREQ) [RFC2881] and/or Mobile
- IPv4. A Diameter client MUST be referred to as "Diameter X Client"
- where X is the application that it supports and not a "Diameter
- Client".
-
- Diameter servers MUST support the base protocol, which includes
- accounting. In addition, they MUST fully support each Diameter
- application that is needed to implement the intended service, e.g.,
- NASREQ and/or Mobile IPv4. A Diameter server MUST be referred to as
- "Diameter X Server" where X is the application that it supports, and
- not a "Diameter Server".
-
- Diameter relays and redirect agents are transparent to the Diameter
- applications, but they MUST support the Diameter base protocol, which
- includes accounting, and all Diameter applications.
-
- Diameter proxies MUST support the base protocol, which includes
- accounting. In addition, they MUST fully support each Diameter
- application that is needed to implement proxied services, e.g.,
- NASREQ and/or Mobile IPv4. A Diameter proxy MUST be referred to as
- "Diameter X Proxy" where X is the application which it supports, and
- not a "Diameter Proxy".
-
-</pre>
-
-&nada;
-
-<pre>
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 21]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-2.1. Transport
-
- The Diameter Transport profile is defined in [RFC3539].
-
- The base Diameter protocol is run on port 3868 for both TCP [RFC0793]
- and SCTP [RFC4960]. For TLS [RFC5246] and Datagram Transport Layer
- Security (DTLS) [RFC6347], a Diameter node that initiates a
- connection prior to any message exchanges MUST run on port 5658. It
- is assumed that TLS is run on top of TCP when it is used, and DTLS is
- run on top of SCTP when it is used.
-</pre>
-
-<p>
-Which port a transport connects to or listens on is a matter of
-configuration.
-Both &man_tcp; and &man_sctp; will default to 3868 if no other value
-is specified.</p>
-
-<pre>
-
- If the Diameter peer does not support receiving TLS/TCP and DTLS/SCTP
- connections on port 5658 (i.e., the peer complies only with RFC
- 3588), then the initiator MAY revert to using TCP or SCTP on port
- 3868. Note that this scheme is kept only for the purpose of backward
- compatibility and that there are inherent security vulnerabilities
- when the initial CER/CEA messages are sent unprotected (see
- Section 5.6).
-
- Diameter clients MUST support either TCP or SCTP; agents and servers
- SHOULD support both.
-
- A Diameter node MAY initiate connections from a source port other
- than the one that it declares it accepts incoming connections on, and
- it MUST always be prepared to receive connections on port 3868 for
- TCP or SCTP and port 5658 for TLS/TCP and DTLS/SCTP connections.
- When DNS-based peer discovery (Section 5.2) is used, the port numbers
- received from SRV records take precedence over the default ports
- (3868 and 5658).
-
- A given Diameter instance of the peer state machine MUST NOT use more
- than one transport connection to communicate with a given peer,
- unless multiple instances exist on the peer, in which, case a
- separate connection per process is allowed.
-</pre>
-
-<p>
-The &mod_service_opt; <c>restrict_connection</c> controls to what
-extent a diameter service allows multiple connections to the same
-peer.
-(As identified by the value of Origin-Host received from it
-during capabilities exchange.)</p>
-
-<pre>
-
- When no transport connection exists with a peer, an attempt to
- connect SHOULD be made periodically. This behavior is handled via
- the Tc timer (see Section 12 for details), whose recommended value is
- 30 seconds. There are certain exceptions to this rule, such as when
- a peer has terminated the transport connection stating that it does
- not wish to communicate.
-
-</pre>
-
-<p>
-The frequency of reconnection attempts is configured with the
-&mod_transport_opt; <c>connect_timer</c> and
-<c>watchdog_timer</c>.</p>
-
-<pre>
-
- When connecting to a peer and either zero or more transports are
- specified, TLS SHOULD be tried first, followed by DTLS, then by TCP,
- and finally by SCTP. See Section 5.2 for more information on peer
- discovery.
-</pre>
-
-<p>
-The order in which different transports are attempted depends on the
-order of &mod_transport_opt; <c>transport_module</c> and
-<c>transport_config</c> tuples in transport configuration.</p>
-
-<pre>
-
-
-
-Fajardo, et al. Standards Track [Page 22]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Diameter implementations SHOULD be able to interpret ICMP protocol
- port unreachable messages as explicit indications that the server is
- not reachable, subject to security policy on trusting such messages.
- Further guidance regarding the treatment of ICMP errors can be found
- in [RFC5927] and [RFC5461]. Diameter implementations SHOULD also be
- able to interpret a reset from the transport and timed-out connection
- attempts. If Diameter receives data from the lower layer that cannot
- be parsed or identified as a Diameter error made by the peer, the
- stream is compromised and cannot be recovered. The transport
- connection MUST be closed using a RESET call (send a TCP RST bit) or
- an SCTP ABORT message (graceful closure is compromised).
-</pre>
-
-<p>
-ICMP messages and other transport-level errors aren't directly
-visible to diameter but transport implementations like &man_tcp; and
-&man_sctp; propagate these as terminating transport processes.</p>
-
-<pre>
-
-2.1.1. SCTP Guidelines
-
- Diameter messages SHOULD be mapped into SCTP streams in a way that
- avoids head-of-the-line (HOL) blocking. Among different ways of
- performing the mapping that fulfill this requirement it is
- RECOMMENDED that a Diameter node send every Diameter message (request
- or response) over stream zero with the unordered flag set. However,
- Diameter nodes MAY select and implement other design alternatives for
- avoiding HOL blocking such as using multiple streams with the
- unordered flag cleared (as originally instructed in RFC 3588). On
- the receiving side, a Diameter entity MUST be ready to receive
- Diameter messages over any stream, and it is free to return responses
- over a different stream. This way, both sides manage the available
- streams in the sending direction, independently of the streams chosen
- by the other side to send a particular Diameter message. These
- messages can be out-of-order and belong to different Diameter
- sessions.
-</pre>
-
-<p>
-&man_sctp; allows the sender to specify a stream number explicitly.
-The stream on which an incoming message is received it passed to
-&app_handle_request; and &app_handle_answer; callbacks as
-<c>transport_data</c> in a <c>#diameter_packet{}</c>.</p>
-
-<p>
-Ordered or unordered delivery can be configured per transport.</p>
-
-<pre>
-
- Out-of-order delivery has special concerns during a connection
- establishment and termination. When a connection is established, the
- responder side sends a CEA message and moves to R-Open state as
- specified in Section 5.6. If an application message is sent shortly
- after the CEA and delivered out-of-order, the initiator side, still
- in Wait-I-CEA state, will discard the application message and close
- the connection. In order to avoid this race condition, the receiver
- side SHOULD NOT use out-of-order delivery methods until the first
- message has been received from the initiator, proving that it has
- moved to I-Open state. To trigger such a message, the receiver side
- could send a DWR immediately after sending a CEA. Upon reception of
- the corresponding DWA, the receiver side should start using out-of-
- order delivery methods to counter the HOL blocking.
-</pre>
-
-<p>
-&man_sctp; does not currently allow the user to switch between ordered
-and unordered delivery, or to specify the manner of sending per
-message: one or the other must be configured, the defaults being
-ordered.</p>
-
-<pre>
-
- Another race condition may occur when DPR and DPA messages are used.
- Both DPR and DPA are small in size; thus, they may be delivered to
- the peer faster than application messages when an out-of-order
- delivery mechanism is used. Therefore, it is possible that a DPR/DPA
-
-
-
-Fajardo, et al. Standards Track [Page 23]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- exchange completes while application messages are still in transit,
- resulting in a loss of these messages. An implementation could
- mitigate this race condition, for example, using timers, and wait for
- a short period of time for pending application level messages to
- arrive before proceeding to disconnect the transport connection.
- Eventually, lost messages are handled by the retransmission mechanism
- described in Section 5.5.4.
-
- A Diameter agent SHOULD use dedicated payload protocol identifiers
- (PPIDs) for clear text and encrypted SCTP DATA chunks instead of only
- using the unspecified payload protocol identifier (value 0). For
- this purpose, two PPID values are allocated: the PPID value 46 is for
- Diameter messages in clear text SCTP DATA chunks, and the PPID value
- 47 is for Diameter messages in protected DTLS/SCTP DATA chunks.
-</pre>
-
-&nada;
-
-<pre>
-
-2.2. Securing Diameter Messages
-
- Connections between Diameter peers SHOULD be protected by TLS/TCP and
- DTLS/SCTP. All Diameter base protocol implementations MUST support
- the use of TLS/TCP and DTLS/SCTP. If desired, alternative security
- mechanisms that are independent of Diameter, such as IPsec [RFC4301],
- can be deployed to secure connections between peers. The Diameter
- protocol MUST NOT be used without one of TLS, DTLS, or IPsec.
-</pre>
-
-<p>
-As noted above, DTLS is not currently supported and IPsec usage is
-transparent to diameter.
-Security is not enforced by diameter.</p>
-
-<pre>
-
-2.3. Diameter Application Compliance
-
- Application Ids are advertised during the capabilities exchange phase
- (see Section 5.3). Advertising support of an application implies
- that the sender supports the functionality specified in the
- respective Diameter application specification.
-
- Implementations MAY add arbitrary optional AVPs with the M-bit
- cleared (including vendor-specific AVPs) to a command defined in an
- application, but only if the command's CCF syntax specification
- allows for it. Please refer to Section 11.1.1 for details.
-</pre>
-
-&nada;
-
-<pre>
-
-2.4. Application Identifiers
-
- Each Diameter application MUST have an IANA-assigned Application ID.
- The base protocol does not require an Application Id since its
- support is mandatory. During the capabilities exchange, Diameter
- nodes inform their peers of locally supported applications.
- Furthermore, all Diameter messages contain an Application Id, which
- is used in the message forwarding process.
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 24]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The following Application Id values are defined:
-
- Diameter common message 0
- Diameter base accounting 3
- Relay 0xffffffff
-</pre>
-
-<p>
-These applications are implemented in the dictionary modules
-<c>diameter_gen_base_rfc6733</c>, <c>diameter_gen_acct_rfc6733</c> and
-<c>diameter_relay</c> respectively.
-There are also RFC 3588 versions or the common and accounting
-dictionaries: <c>diameter_gen_base_rfc3588</c> and
-<c>diameter_base_accounting</c>.
-(The inconsistent naming is historical.)
-Dictionary modules are configured using the &mod_application_opt;
-<c>dictionary</c>.</p>
-
-<pre>
- Relay and redirect agents MUST advertise the Relay Application ID,
- while all other Diameter nodes MUST advertise locally supported
- applications. The receiver of a Capabilities Exchange message
- advertising relay service MUST assume that the sender supports all
- current and future applications.
-
- Diameter relay and proxy agents are responsible for finding an
- upstream server that supports the application of a particular
- message. If none can be found, an error message is returned with the
- Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER.
-</pre>
-
-&nada;
-
-<pre>
-
-2.5. Connections vs. Sessions
-
- This section attempts to provide the reader with an understanding of
- the difference between "connection" and "session", which are terms
- used extensively throughout this document.
-
- A connection refers to a transport-level connection between two peers
- that is used to send and receive Diameter messages. A session is a
- logical concept at the application layer that exists between the
- Diameter client and the Diameter server; it is identified via the
- Session-Id AVP.
-
- +--------+ +-------+ +--------+
- | Client | | Relay | | Server |
- +--------+ +-------+ +--------+
- &lt;----------> &lt;---------->
- peer connection A peer connection B
-
- &lt;----------------------------->
- User session x
-
- Figure 1: Diameter Connections and Sessions
-
- In the example provided in Figure 1, peer connection A is established
- between the client and the relay. Peer connection B is established
- between the relay and the server. User session X spans from the
- client via the relay to the server. Each "user" of a service causes
- an auth request to be sent, with a unique session identifier. Once
- accepted by the server, both the client and the server are aware of
- the session.
-
-
-
-
-Fajardo, et al. Standards Track [Page 25]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- It is important to note that there is no relationship between a
- connection and a session, and that Diameter messages for multiple
- sessions are all multiplexed through a single connection. Also, note
- that Diameter messages pertaining to the session, both application-
- specific and those that are defined in this document such as ASR/ASA,
- RAR/RAA, and STR/STA, MUST carry the Application Id of the
- application. Diameter messages pertaining to peer connection
- establishment and maintenance such as CER/CEA, DWR/DWA, and DPR/DPA
- MUST carry an Application Id of zero (0).
-</pre>
-
-<p>
-As noted above, diameter is not involved in session management.
-This is the responsibility of the diameter user.</p>
-
-<pre>
-
-2.6. Peer Table
-
- The Diameter peer table is used in message forwarding and is
- referenced by the routing table. A peer table entry contains the
- following fields:
-
- Host Identity
-
- Following the conventions described for the DiameterIdentity-
- derived AVP data format in Section 4.3.1, this field contains the
- contents of the Origin-Host (Section 6.3) AVP found in the CER or
- CEA message.
-
- StatusT
-
- This is the state of the peer entry, and it MUST match one of the
- values listed in Section 5.6.
-
- Static or Dynamic
-
- Specifies whether a peer entry was statically configured or
- dynamically discovered.
-
- Expiration Time
-
- Specifies the time at which dynamically discovered peer table
- entries are to be either refreshed or expired. If public key
- certificates are used for Diameter security (e.g., with TLS), this
- value MUST NOT be greater than the expiry times in the relevant
- certificates.
-
- TLS/TCP and DTLS/SCTP Enabled
-
- Specifies whether TLS/TCP and DTLS/SCTP is to be used when
- communicating with the peer.
-
- Additional security information, when needed (e.g., keys,
- certificates).
-</pre>
-
-<p>
-The Peer Table is not directly accessible to the diameter user.
-Information about connected peers can be retrieved using
-&mod_service_info;.</p>
-
-<pre>
-
-
-
-Fajardo, et al. Standards Track [Page 26]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-2.7. Routing Table
-
- All Realm-Based routing lookups are performed against what is
- commonly known as the routing table (see Section 12). Each routing
- table entry contains the following fields:
-
- Realm Name
-
- This is the field that MUST be used as a primary key in the
- routing table lookups. Note that some implementations perform
- their lookups based on longest-match-from-the-right on the realm
- rather than requiring an exact match.
-
- Application Identifier
-
- An application is identified by an Application Id. A route entry
- can have a different destination based on the Application Id in
- the message header. This field MUST be used as a secondary key
- field in routing table lookups.
-
- Local Action
-
- The Local Action field is used to identify how a message should be
- treated. The following actions are supported:
-
- 1. LOCAL - Diameter messages that can be satisfied locally and do
- not need to be routed to another Diameter entity.
-
- 2. RELAY - All Diameter messages that fall within this category
- MUST be routed to a next-hop Diameter entity that is indicated
- by the identifier described below. Routing is done without
- modifying any non-routing AVPs. See Section 6.1.9 for
- relaying guidelines.
-
- 3. PROXY - All Diameter messages that fall within this category
- MUST be routed to a next Diameter entity that is indicated by
- the identifier described below. The local server MAY apply
- its local policies to the message by including new AVPs to the
- message prior to routing. See Section 6.1.9 for proxying
- guidelines.
-
- 4. REDIRECT - Diameter messages that fall within this category
- MUST have the identity of the home Diameter server(s)
- appended, and returned to the sender of the message. See
- Section 6.1.8 for redirection guidelines.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 27]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Server Identifier
-
- The identity of one or more servers to which the message is to be
- routed. This identity MUST also be present in the Host Identity
- field of the peer table (Section 2.6). When the Local Action is
- set to RELAY or PROXY, this field contains the identity of the
- server(s) to which the message MUST be routed. When the Local
- Action field is set to REDIRECT, this field contains the identity
- of one or more servers to which the message MUST be redirected.
-
- Static or Dynamic
-
- Specifies whether a route entry was statically configured or
- dynamically discovered.
-
- Expiration Time
-
- Specifies the time at which a dynamically discovered route table
- entry expires. If public key certificates are used for Diameter
- security (e.g., with TLS), this value MUST NOT be greater than the
- expiry time in the relevant certificates.
-
- It is important to note that Diameter agents MUST support at least
- one of the LOCAL, RELAY, PROXY, or REDIRECT modes of operation.
- Agents do not need to support all modes of operation in order to
- conform with the protocol specification, but they MUST follow the
- protocol compliance guidelines in Section 2. Relay agents and
- proxies MUST NOT reorder AVPs.
-
- The routing table MAY include a default entry that MUST be used for
- any requests not matching any of the other entries. The routing
- table MAY consist of only such an entry.
-
- When a request is routed, the target server MUST have advertised the
- Application Id (see Section 2.4) for the given message or have
- advertised itself as a relay or proxy agent. Otherwise, an error is
- returned with the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER.
-</pre>
-
-<p>
-Routing does not need specific support in diameter: a user can
-maintain their own routing table if desired and implement any desired
-routing in &man_app; callbacks.
-However, it may be convenient to add more specific routing support to
-diameter in the future.</p>
-
-<pre>
-
-2.8. Role of Diameter Agents
-
- In addition to clients and servers, the Diameter protocol introduces
- relay, proxy, redirect, and translation agents, each of which is
- defined in Section 1.2. Diameter agents are useful for several
- reasons:
-</pre>
-
-<p>
-An noted above, the role a node plays is largely a question of
-configuration and &man_app; callback implementation.</p>
-
-<pre>
-
- o They can distribute administration of systems to a configurable
- grouping, including the maintenance of security associations.
-
-
-
-
-Fajardo, et al. Standards Track [Page 28]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o They can be used for concentration of requests from a number of
- co-located or distributed NAS equipment sets to a set of like user
- groups.
-
- o They can do value-added processing to the requests or responses.
-
- o They can be used for load balancing.
-
- o A complex network will have multiple authentication sources, they
- can sort requests and forward towards the correct target.
-
- The Diameter protocol requires that agents maintain transaction
- state, which is used for failover purposes. Transaction state
- implies that upon forwarding a request, its Hop-by-Hop Identifier is
- saved; the field is replaced with a locally unique identifier, which
- is restored to its original value when the corresponding answer is
- received. The request's state is released upon receipt of the
- answer. A stateless agent is one that only maintains transaction
- state.
-
- The Proxy-Info AVP allows stateless agents to add local state to a
- Diameter request, with the guarantee that the same state will be
- present in the answer. However, the protocol's failover procedures
- require that agents maintain a copy of pending requests.
-
- A stateful agent is one that maintains session state information by
- keeping track of all authorized active sessions. Each authorized
- session is bound to a particular service, and its state is considered
- active until either the agent is notified otherwise or the session
- expires. Each authorized session has an expiration, which is
- communicated by Diameter servers via the Session-Timeout AVP.
-
- Maintaining session state may be useful in certain applications, such
- as:
-
- o Protocol translation (e.g., RADIUS &lt;-> Diameter)
-
- o Limiting resources authorized to a particular user
-
- o Per-user or per-transaction auditing
-
- A Diameter agent MAY act in a stateful manner for some requests and
- be stateless for others. A Diameter implementation MAY act as one
- type of agent for some requests and as another type of agent for
- others.
-</pre>
-
-&nada;
-
-<pre>
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 29]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-2.8.1. Relay Agents
-
- Relay agents are Diameter agents that accept requests and route
- messages to other Diameter nodes based on information found in the
- messages (e.g., the value of the Destination-Realm AVP Section 6.6).
- This routing decision is performed using a list of supported realms
- and known peers. This is known as the routing table, as is defined
- further in Section 2.7.
-
- Relays may, for example, be used to aggregate requests from multiple
- Network Access Servers (NASes) within a common geographical area
- (Point of Presence, POP). The use of relays is advantageous since it
- eliminates the need for NASes to be configured with the necessary
- security information they would otherwise require to communicate with
- Diameter servers in other realms. Likewise, this reduces the
- configuration load on Diameter servers that would otherwise be
- necessary when NASes are added, changed, or deleted.
-
- Relays modify Diameter messages by inserting and removing routing
- information, but they do not modify any other portion of a message.
- Relays SHOULD NOT maintain session state but MUST maintain
- transaction state.
-
- +------+ ---------> +------+ ---------> +------+
- | | 1. Request | | 2. Request | |
- | NAS | | DRL | | HMS |
- | | 4. Answer | | 3. Answer | |
- +------+ &lt;--------- +------+ &lt;--------- +------+
- example.net example.net example.com
-
- Figure 2: Relaying of Diameter messages
-
- The example provided in Figure 2 depicts a request issued from a NAS,
- which is an access device, for the user [email protected]. Prior to
- issuing the request, the NAS performs a Diameter route lookup, using
- "example.com" as the key, and determines that the message is to be
- relayed to a DRL, which is a Diameter relay. The DRL performs the
- same route lookup as the NAS, and relays the message to the HMS,
- which is example.com's home server. The HMS identifies that the
- request can be locally supported (via the realm), processes the
- authentication and/or authorization request, and replies with an
- answer, which is routed back to the NAS using saved transaction
- state.
-
- Since relays do not perform any application-level processing, they
- provide relaying services for all Diameter applications; therefore,
- they MUST advertise the Relay Application Id.
-</pre>
-
-<p>
-Requests are relayed by returning a <c>relay</c> tuple from a
-&app_handle_request; callback.</p>
-
-<pre>
-
-
-
-Fajardo, et al. Standards Track [Page 30]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-2.8.2. Proxy Agents
-
- Similar to relays, proxy agents route Diameter messages using the
- Diameter routing table. However, they differ since they modify
- messages to implement policy enforcement. This requires that proxies
- maintain the state of their downstream peers (e.g., access devices)
- to enforce resource usage, provide admission control, and provide
- provisioning.
-
- Proxies may, for example, be used in call control centers or access
- ISPs that provide outsourced connections; they can monitor the number
- and type of ports in use and make allocation and admission decisions
- according to their configuration.
-
- Since enforcing policies requires an understanding of the service
- being provided, proxies MUST only advertise the Diameter applications
- they support.
-</pre>
-
-&nada;
-
-<pre>
-
-2.8.3. Redirect Agents
-
- Redirect agents are useful in scenarios where the Diameter routing
- configuration needs to be centralized. An example is a redirect
- agent that provides services to all members of a consortium, but does
- not wish to be burdened with relaying all messages between realms.
- This scenario is advantageous since it does not require that the
- consortium provide routing updates to its members when changes are
- made to a member's infrastructure.
-
- Since redirect agents do not relay messages, and only return an
- answer with the information necessary for Diameter agents to
- communicate directly, they do not modify messages. Since redirect
- agents do not receive answer messages, they cannot maintain session
- state.
-
- The example provided in Figure 3 depicts a request issued from the
- access device, NAS, for the user [email protected]. The message is
- forwarded by the NAS to its relay, DRL, which does not have a routing
- entry in its Diameter routing table for example.com. The DRL has a
- default route configured to DRD, which is a redirect agent that
- returns a redirect notification to DRL, as well as the HMS' contact
- information. Upon receipt of the redirect notification, the DRL
- establishes a transport connection with the HMS, if one doesn't
- already exist, and forwards the request to it.
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 31]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- +------+
- | |
- | DRD |
- | |
- +------+
- ^ |
- 2. Request | | 3. Redirection
- | | Notification
- | v
- +------+ ---------> +------+ ---------> +------+
- | | 1. Request | | 4. Request | |
- | NAS | | DRL | | HMS |
- | | 6. Answer | | 5. Answer | |
- +------+ &lt;--------- +------+ &lt;--------- +------+
- example.net example.net example.com
-
- Figure 3: Redirecting a Diameter Message
-
- Since redirect agents do not perform any application-level
- processing, they provide relaying services for all Diameter
- applications; therefore, they MUST advertise the Relay Application
- ID.
-</pre>
-
-&nada;
-
-<pre>
-
-2.8.4. Translation Agents
-
- A translation agent is a device that provides translation between two
- protocols (e.g., RADIUS&lt;->Diameter, TACACS+&lt;->Diameter). Translation
- agents are likely to be used as aggregation servers to communicate
- with a Diameter infrastructure, while allowing for the embedded
- systems to be migrated at a slower pace.
-
- Given that the Diameter protocol introduces the concept of long-lived
- authorized sessions, translation agents MUST be session stateful and
- MUST maintain transaction state.
-
- Translation of messages can only occur if the agent recognizes the
- application of a particular request; therefore, translation agents
- MUST only advertise their locally supported applications.
-
- +------+ ---------> +------+ ---------> +------+
- | | RADIUS Request | | Diameter Request | |
- | NAS | | TLA | | HMS |
- | | RADIUS Answer | | Diameter Answer | |
- +------+ &lt;--------- +------+ &lt;--------- +------+
- example.net example.net example.com
-
- Figure 4: Translation of RADIUS to Diameter
-</pre>
-
-&nada;
-
-<pre>
-
-
-
-
-Fajardo, et al. Standards Track [Page 32]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-2.9. Diameter Path Authorization
-
- As noted in Section 2.2, Diameter provides transmission-level
- security for each connection using TLS/TCP and DTLS/SCTP. Therefore,
- each connection can be authenticated and can be replay and integrity
- protected.
-
- In addition to authenticating each connection, the entire session
- MUST also be authorized. Before initiating a connection, a Diameter
- peer MUST check that its peers are authorized to act in their roles.
- For example, a Diameter peer may be authentic, but that does not mean
- that it is authorized to act as a Diameter server advertising a set
- of Diameter applications.
-
- Prior to bringing up a connection, authorization checks are performed
- at each connection along the path. Diameter capabilities negotiation
- (CER/CEA) also MUST be carried out, in order to determine what
- Diameter applications are supported by each peer. Diameter sessions
- MUST be routed only through authorized nodes that have advertised
- support for the Diameter application required by the session.
-
- As noted in Section 6.1.9, a relay or proxy agent MUST append a
- Route-Record AVP to all requests forwarded. The AVP contains the
- identity of the peer from which the request was received.
-
- The home Diameter server, prior to authorizing a session, MUST check
- the Route-Record AVPs to make sure that the route traversed by the
- request is acceptable. For example, administrators within the home
- realm may not wish to honor requests that have been routed through an
- untrusted realm. By authorizing a request, the home Diameter server
- is implicitly indicating its willingness to engage in the business
- transaction as specified by any contractual relationship between the
- server and the previous hop. A DIAMETER_AUTHORIZATION_REJECTED error
- message (see Section 7.1.5) is sent if the route traversed by the
- request is unacceptable.
-
- A home realm may also wish to check that each accounting request
- message corresponds to a Diameter response authorizing the session.
- Accounting requests without corresponding authorization responses
- SHOULD be subjected to further scrutiny, as should accounting
- requests indicating a difference between the requested and provided
- service.
-
- Forwarding of an authorization response is considered evidence of a
- willingness to take on financial risk relative to the session. A
- local realm may wish to limit this exposure, for example, by
- establishing credit limits for intermediate realms and refusing to
- accept responses that would violate those limits. By issuing an
-
-
-
-Fajardo, et al. Standards Track [Page 33]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- accounting request corresponding to the authorization response, the
- local realm implicitly indicates its agreement to provide the service
- indicated in the authorization response. If the service cannot be
- provided by the local realm, then a DIAMETER_UNABLE_TO_COMPLY error
- message MUST be sent within the accounting request; a Diameter client
- receiving an authorization response for a service that it cannot
- perform MUST NOT substitute an alternate service and then send
- accounting requests for the alternate service instead.
-</pre>
-
-&nada;
-
-<pre>
-
-3. Diameter Header
-
- A summary of the Diameter header format is shown below. The fields
- are transmitted in network byte order.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Version | Message Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Command Flags | Command Code |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Application-ID |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Hop-by-Hop Identifier |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | End-to-End Identifier |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | AVPs ...
- +-+-+-+-+-+-+-+-+-+-+-+-+-
-</pre>
-
-<p>
-The Diameter Header is represented by the <c>diameter_header</c>
-record defined in <c>diameter.hrl</c>.
-The <c>diameter_packet</c> record contains a <c>header</c> field whose
-value will be a decoded <c>#diameter_header{}</c> for incoming
-messages passed to &app_handle_request; and &app_handle_answer;
-callbacks.
-In the case of outgoing messages, diameter and the relevant
-dictionary populate the Diameter Header appropriately, although
-&app_prepare_request; and &app_handle_request; callbacks can modify
-header values.
-(Which can be useful in test.)</p>
-
-<pre>
-
- Version
-
- This Version field MUST be set to 1 to indicate Diameter Version
- 1.
-
- Message Length
-
- The Message Length field is three octets and indicates the length
- of the Diameter message including the header fields and the padded
- AVPs. Thus, the Message Length field is always a multiple of 4.
-
- Command Flags
-
- The Command Flags field is eight bits. The following bits are
- assigned:
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 34]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- 0 1 2 3 4 5 6 7
- +-+-+-+-+-+-+-+-+
- |R P E T r r r r|
- +-+-+-+-+-+-+-+-+
-
- R(equest)
-
- If set, the message is a request. If cleared, the message is
- an answer.
-
- P(roxiable)
-
- If set, the message MAY be proxied, relayed, or redirected. If
- cleared, the message MUST be locally processed.
-
- E(rror)
-
- If set, the message contains a protocol error, and the message
- will not conform to the CCF described for this command.
- Messages with the 'E' bit set are commonly referred to as error
- messages. This bit MUST NOT be set in request messages (see
- Section 7.2).
-
- T(Potentially retransmitted message)
-
- This flag is set after a link failover procedure, to aid the
- removal of duplicate requests. It is set when resending
- requests not yet acknowledged, as an indication of a possible
- duplicate due to a link failure. This bit MUST be cleared when
- sending a request for the first time; otherwise, the sender
- MUST set this flag. Diameter agents only need to be concerned
- about the number of requests they send based on a single
- received request; retransmissions by other entities need not be
- tracked. Diameter agents that receive a request with the T
- flag set, MUST keep the T flag set in the forwarded request.
- This flag MUST NOT be set if an error answer message (e.g., a
- protocol error) has been received for the earlier message. It
- can be set only in cases where no answer has been received from
- the server for a request, and the request has been sent again.
- This flag MUST NOT be set in answer messages.
-
- r(eserved)
-
- These flag bits are reserved for future use; they MUST be set
- to zero and ignored by the receiver.
-</pre>
-
-<p>
-Reserved bits are set to 0 in outgoing messages.</p>
-
-<pre>
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 35]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Command Code
-
- The Command Code field is three octets and is used in order to
- communicate the command associated with the message. The 24-bit
- address space is managed by IANA (see Section 3.1). Command Code
- values 16,777,214 and 16,777,215 (hexadecimal values FFFFFE-
- FFFFFF) are reserved for experimental use (see Section 11.2).
-
- Application-ID
-
- Application-ID is four octets and is used to identify for which
- application the message is applicable. The application can be an
- authentication application, an accounting application, or a
- vendor-specific application.
-
- The value of the Application-ID field in the header MUST be the
- same as any relevant Application-Id AVPs contained in the message.
-
- Hop-by-Hop Identifier
-
- The Hop-by-Hop Identifier is an unsigned 32-bit integer field (in
- network byte order) that aids in matching requests and replies.
- The sender MUST ensure that the Hop-by-Hop Identifier in a request
- is unique on a given connection at any given time, and it MAY
- attempt to ensure that the number is unique across reboots. The
- sender of an answer message MUST ensure that the Hop-by-Hop
- Identifier field contains the same value that was found in the
- corresponding request. The Hop-by-Hop Identifier is normally a
- monotonically increasing number, whose start value was randomly
- generated. An answer message that is received with an unknown
- Hop-by-Hop Identifier MUST be discarded.
-
- End-to-End Identifier
-
- The End-to-End Identifier is an unsigned 32-bit integer field (in
- network byte order) that is used to detect duplicate messages.
- Upon reboot, implementations MAY set the high order 12 bits to
- contain the low order 12 bits of current time, and the low order
- 20 bits to a random value. Senders of request messages MUST
- insert a unique identifier on each message. The identifier MUST
- remain locally unique for a period of at least 4 minutes, even
- across reboots. The originator of an answer message MUST ensure
- that the End-to-End Identifier field contains the same value that
- was found in the corresponding request. The End-to-End Identifier
- MUST NOT be modified by Diameter agents of any kind. The
- combination of the Origin-Host AVP (Section 6.3) and this field is
- used to detect duplicates. Duplicate requests SHOULD cause the
- same answer to be transmitted (modulo the Hop-by-Hop Identifier
-
-
-
-Fajardo, et al. Standards Track [Page 36]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- field and any routing AVPs that may be present), and they MUST NOT
- affect any state that was set when the original request was
- processed. Duplicate answer messages that are to be locally
- consumed (see Section 6.2) SHOULD be silently discarded.
-
- AVPs
-
- AVPs are a method of encapsulating information relevant to the
- Diameter message. See Section 4 for more information on AVPs.
-</pre>
-
-&nada;
-
-<pre>
-
-3.1. Command Codes
-
- Each command Request/Answer pair is assigned a Command Code, and the
- sub-type (i.e., request or answer) is identified via the 'R' bit in
- the Command Flags field of the Diameter header.
-
- Every Diameter message MUST contain a Command Code in its header's
- Command Code field, which is used to determine the action that is to
- be taken for a particular message. The following Command Codes are
- defined in the Diameter base protocol:
-
- Section
- Command Name Abbrev. Code Reference
- --------------------------------------------------------
- Abort-Session-Request ASR 274 8.5.1
- Abort-Session-Answer ASA 274 8.5.2
- Accounting-Request ACR 271 9.7.1
- Accounting-Answer ACA 271 9.7.2
- Capabilities-Exchange- CER 257 5.3.1
- Request
- Capabilities-Exchange- CEA 257 5.3.2
- Answer
- Device-Watchdog-Request DWR 280 5.5.1
- Device-Watchdog-Answer DWA 280 5.5.2
- Disconnect-Peer-Request DPR 282 5.4.1
- Disconnect-Peer-Answer DPA 282 5.4.2
- Re-Auth-Request RAR 258 8.3.1
- Re-Auth-Answer RAA 258 8.3.2
- Session-Termination- STR 275 8.4.1
- Request
- Session-Termination- STA 275 8.4.2
- Answer
-</pre>
-
-<p>
-These messages are all defined in diameter's implementation of the
-common dictionary in modules <c>diameter_gen_base_rfc6733</c> and
-<c>diameter_gen_base_rfc3588</c>.
-Corresponding record definitions are found in
-<c>diameter_gen_base_rfc6733.hrl</c> and
-<c>diameter_gen_base_rfc3588.hrl</c>.</p>
-
-<pre>
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 37]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-3.2. Command Code Format Specification
-
- Every Command Code defined MUST include a corresponding Command Code
- Format (CCF) specification, which is used to define the AVPs that
- MUST or MAY be present when sending the message. The following ABNF
- specifies the CCF used in the definition:
-</pre>
-
-<p>
-The CCF is what is specified in the <c>@messages</c> section of the
-&man_dict; format, except as noted below.</p>
-
-<pre>
-
- command-def = "&lt;" command-name ">" "::=" diameter-message
-</pre>
-
-<p>
-Angle brackets are currently not allowed here.
-This was a change between RFC 3588 and RFC 6733: the former disallowed
-them in the grammar but included them in its own command definitions.</p>
-
-<pre>
-
- command-name = diameter-name
-
- diameter-name = ALPHA *(ALPHA / DIGIT / "-")
-
- diameter-message = header *fixed *required *optional
-
- header = "&lt;Diameter-Header:" command-id
- [r-bit] [p-bit] [e-bit] [application-id]">"
-
- application-id = 1*DIGIT
-
- command-id = 1*DIGIT
- ; The Command Code assigned to the command.
-
- r-bit = ", REQ"
- ; If present, the 'R' bit in the Command
- ; Flags is set, indicating that the message
- ; is a request as opposed to an answer.
-
- p-bit = ", PXY"
- ; If present, the 'P' bit in the Command
- ; Flags is set, indicating that the message
- ; is proxiable.
-
- e-bit = ", ERR"
- ; If present, the 'E' bit in the Command
- ; Flags is set, indicating that the answer
- ; message contains a Result-Code AVP in
- ; the "protocol error" class.
-
- fixed = [qual] "&lt;" avp-spec ">"
- ; Defines the fixed position of an AVP.
-
- required = [qual] "{" avp-spec "}"
- ; The AVP MUST be present and can appear
- ; anywhere in the message.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 38]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- optional = [qual] "[" avp-name "]"
- ; The avp-name in the 'optional' rule cannot
- ; evaluate to any AVP Name that is included
- ; in a fixed or required rule. The AVP can
- ; appear anywhere in the message.
- ;
- ; NOTE: "[" and "]" have a slightly different
- ; meaning than in ABNF. These braces
- ; cannot be used to express optional fixed rules
- ; (such as an optional ICV at the end). To do
- ; this, the convention is '0*1fixed'.
-
- qual = [min] "*" [max]
- ; See ABNF conventions, RFC 5234, Section 4.
- ; The absence of any qualifier depends on
- ; whether it precedes a fixed, required, or
- ; optional rule. If a fixed or required rule has
- ; no qualifier, then exactly one such AVP MUST
- ; be present. If an optional rule has no
- ; qualifier, then 0 or 1 such AVP may be
- ; present. If an optional rule has a qualifier,
- ; then the value of min MUST be 0 if present.
-
- min = 1*DIGIT
- ; The minimum number of times the element may
- ; be present. If absent, the default value is 0
- ; for fixed and optional rules and 1 for
- ; required rules. The value MUST be at least 1
- ; for required rules.
-
- max = 1*DIGIT
- ; The maximum number of times the element may
- ; be present. If absent, the default value is
- ; infinity. A value of 0 implies the AVP MUST
- ; NOT be present.
-
- avp-spec = diameter-name
- ; The avp-spec has to be an AVP Name, defined
- ; in the base or extended Diameter
- ; specifications.
-
- avp-name = avp-spec / "AVP"
- ; The string "AVP" stands for *any* arbitrary AVP
- ; Name, not otherwise listed in that Command Code
- ; definition. The inclusion of this string
- ; is recommended for all CCFs to allow for
- ; extensibility.
-
-
-
-
-Fajardo, et al. Standards Track [Page 39]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The following is a definition of a fictitious Command Code:
-
- Example-Request ::= &lt; Diameter Header: 9999999, REQ, PXY >
- { User-Name }
- 1* { Origin-Host }
- * [ AVP ]
-</pre>
-
-&nada;
-
-<pre>
-
-3.3. Diameter Command Naming Conventions
-
- Diameter command names typically includes one or more English words
- followed by the verb "Request" or "Answer". Each English word is
- delimited by a hyphen. A three-letter acronym for both the request
- and answer is also normally provided.
-
- An example is a message set used to terminate a session. The command
- name is Session-Terminate-Request and Session-Terminate-Answer, while
- the acronyms are STR and STA, respectively.
-
- Both the request and the answer for a given command share the same
- Command Code. The request is identified by the R(equest) bit in the
- Diameter header set to one (1), to ask that a particular action be
- performed, such as authorizing a user or terminating a session. Once
- the receiver has completed the request, it issues the corresponding
- answer, which includes a result code that communicates one of the
- following:
-
- o The request was successful
-
- o The request failed
-
- o An additional request has to be sent to provide information the
- peer requires prior to returning a successful or failed answer.
-
- o The receiver could not process the request, but provides
- information about a Diameter peer that is able to satisfy the
- request, known as redirect.
-
- Additional information, encoded within AVPs, may also be included in
- answer messages.
-</pre>
-
-<p>
-The &man_dict; format places no requirement on the naming of commands.</p>
-
-<pre>
-
-4. Diameter AVPs
-
- Diameter AVPs carry specific authentication, accounting,
- authorization, and routing information as well as configuration
- details for the request and reply.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 40]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Each AVP of type OctetString MUST be padded to align on a 32-bit
- boundary, while other AVP types align naturally. A number of zero-
- valued bytes are added to the end of the AVP Data field until a word
- boundary is reached. The length of the padding is not reflected in
- the AVP Length field.
-
-4.1. AVP Header
-
- The fields in the AVP header MUST be sent in network byte order. The
- format of the header is:
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | AVP Code |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |V M P r r r r r| AVP Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Vendor-ID (opt) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Data ...
- +-+-+-+-+-+-+-+-+
-
- AVP Code
-
- The AVP Code, combined with the Vendor-Id field, identifies the
- attribute uniquely. AVP numbers 1 through 255 are reserved for
- reuse of RADIUS attributes, without setting the Vendor-Id field.
- AVP numbers 256 and above are used for Diameter, which are
- allocated by IANA (see Section 11.1.1).
-
- AVP Flags
-
- The AVP Flags field informs the receiver how each attribute must
- be handled. New Diameter applications SHOULD NOT define
- additional AVP Flag bits. However, note that new Diameter
- applications MAY define additional bits within the AVP header, and
- an unrecognized bit SHOULD be considered an error. The sender of
- the AVP MUST set 'R' (reserved) bits to 0 and the receiver SHOULD
- ignore all 'R' (reserved) bits. The 'P' bit has been reserved for
- future usage of end-to-end security. At the time of writing,
- there are no end-to-end security mechanisms specified; therefore,
- the 'P' bit SHOULD be set to 0.
-
- The 'M' bit, known as the Mandatory bit, indicates whether the
- receiver of the AVP MUST parse and understand the semantics of the
- AVP including its content. The receiving entity MUST return an
- appropriate error message if it receives an AVP that has the M-bit
-
-
-
-Fajardo, et al. Standards Track [Page 41]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- set but does not understand it. An exception applies when the AVP
- is embedded within a Grouped AVP. See Section 4.4 for details.
- Diameter relay and redirect agents MUST NOT reject messages with
- unrecognized AVPs.
-
- The 'M' bit MUST be set according to the rules defined in the
- application specification that introduces or reuses this AVP.
- Within a given application, the M-bit setting for an AVP is
- defined either for all command types or for each command type.
-
- AVPs with the 'M' bit cleared are informational only; a receiver
- that receives a message with such an AVP that is not supported, or
- whose value is not supported, MAY simply ignore the AVP.
-
- The 'V' bit, known as the Vendor-Specific bit, indicates whether
- the optional Vendor-ID field is present in the AVP header. When
- set, the AVP Code belongs to the specific vendor code address
- space.
-
- AVP Length
-
- The AVP Length field is three octets, and indicates the number of
- octets in this AVP including the AVP Code field, AVP Length field,
- AVP Flags field, Vendor-ID field (if present), and the AVP Data
- field. If a message is received with an invalid attribute length,
- the message MUST be rejected.
-
-4.1.1. Optional Header Elements
-
- The AVP header contains one optional field. This field is only
- present if the respective bit-flag is enabled.
-
- Vendor-ID
-
- The Vendor-ID field is present if the 'V' bit is set in the AVP
- Flags field. The optional four-octet Vendor-ID field contains the
- IANA-assigned "SMI Network Management Private Enterprise Codes"
- [ENTERPRISE] value, encoded in network byte order. Any vendors or
- standardization organizations that are also treated like vendors
- in the IANA-managed "SMI Network Management Private Enterprise
- Codes" space wishing to implement a vendor-specific Diameter AVP
- MUST use their own Vendor-ID along with their privately managed
- AVP address space, guaranteeing that they will not collide with
- any other vendor's vendor-specific AVP(s) or with future IETF
- AVPs.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 42]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- A Vendor-ID value of zero (0) corresponds to the IETF-adopted AVP
- values, as managed by IANA. Since the absence of the Vendor-ID
- field implies that the AVP in question is not vendor specific,
- implementations MUST NOT use the value of zero (0) for the
- Vendor-ID field.
-
-4.2. Basic AVP Data Formats
-
- The Data field is zero or more octets and contains information
- specific to the Attribute. The format and length of the Data field
- is determined by the AVP Code and AVP Length fields. The format of
- the Data field MUST be one of the following base data types or a data
- type derived from the base data types. In the event that a new Basic
- AVP Data Format is needed, a new version of this RFC MUST be created.
-
- OctetString
-
- The data contains arbitrary data of variable length. Unless
- otherwise noted, the AVP Length field MUST be set to at least 8
- (12 if the 'V' bit is enabled). AVP values of this type that are
- not a multiple of 4 octets in length are followed by the necessary
- padding so that the next AVP (if any) will start on a 32-bit
- boundary.
-
- Integer32
-
- 32-bit signed value, in network byte order. The AVP Length field
- MUST be set to 12 (16 if the 'V' bit is enabled).
-
- Integer64
-
- 64-bit signed value, in network byte order. The AVP Length field
- MUST be set to 16 (20 if the 'V' bit is enabled).
-
- Unsigned32
-
- 32-bit unsigned value, in network byte order. The AVP Length
- field MUST be set to 12 (16 if the 'V' bit is enabled).
-
- Unsigned64
-
- 64-bit unsigned value, in network byte order. The AVP Length
- field MUST be set to 16 (20 if the 'V' bit is enabled).
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 43]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Float32
-
- This represents floating point values of single precision as
- described by [FLOATPOINT]. The 32-bit value is transmitted in
- network byte order. The AVP Length field MUST be set to 12 (16 if
- the 'V' bit is enabled).
-
- Float64
-
- This represents floating point values of double precision as
- described by [FLOATPOINT]. The 64-bit value is transmitted in
- network byte order. The AVP Length field MUST be set to 16 (20 if
- the 'V' bit is enabled).
-
- Grouped
-
- The Data field is specified as a sequence of AVPs. These AVPs are
- concatenated -- including their headers and padding -- in the
- order in which they are specified and the result encapsulated in
- the Data field. The AVP Length field is set to 8 (12 if the 'V'
- bit is enabled) plus the total length of all included AVPs,
- including their headers and padding. Thus, the AVP Length field
- of an AVP of type Grouped is always a multiple of 4.
-
-4.3. Derived AVP Data Formats
-
- In addition to using the Basic AVP Data Formats, applications may
- define data formats derived from the Basic AVP Data Formats. An
- application that defines new Derived AVP Data Formats MUST include
- them in a section titled "Derived AVP Data Formats", using the same
- format as the definitions below. Each new definition MUST be either
- defined or listed with a reference to the RFC that defines the
- format.
-
-4.3.1. Common Derived AVP Data Formats
-
- The following are commonly used Derived AVP Data Formats.
-
- Address
-
- The Address format is derived from the OctetString Basic AVP
- Format. It is a discriminated union representing, for example, a
- 32-bit (IPv4) [RFC0791] or 128-bit (IPv6) [RFC4291] address, most
- significant octet first. The first two octets of the Address AVP
- represent the AddressType, which contains an Address Family,
- defined in [IANAADFAM]. The AddressType is used to discriminate
- the content and format of the remaining octets.
-
-
-
-
-Fajardo, et al. Standards Track [Page 44]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Time
-
- The Time format is derived from the OctetString Basic AVP Format.
- The string MUST contain four octets, in the same format as the
- first four bytes are in the NTP timestamp format. The NTP
- timestamp format is defined in Section 3 of [RFC5905].
-
- This represents the number of seconds since 0h on 1 January 1900
- with respect to the Coordinated Universal Time (UTC).
-
- On 6h 28m 16s UTC, 7 February 2036, the time value will overflow.
- Simple Network Time Protocol (SNTP) [RFC5905] describes a
- procedure to extend the time to 2104. This procedure MUST be
- supported by all Diameter nodes.
-
- UTF8String
-
- The UTF8String format is derived from the OctetString Basic AVP
- Format. This is a human-readable string represented using the
- ISO/IEC IS 10646-1 character set, encoded as an OctetString using
- the UTF-8 transformation format [RFC3629].
-
- Since additional code points are added by amendments to the 10646
- standard from time to time, implementations MUST be prepared to
- encounter any code point from 0x00000001 to 0x7fffffff. Byte
- sequences that do not correspond to the valid encoding of a code
- point into UTF-8 charset or are outside this range are prohibited.
-
- The use of control codes SHOULD be avoided. When it is necessary
- to represent a new line, the control code sequence CR LF SHOULD be
- used.
-
- The use of leading or trailing white space SHOULD be avoided.
-
- For code points not directly supported by user interface hardware
- or software, an alternative means of entry and display, such as
- hexadecimal, MAY be provided.
-
- For information encoded in 7-bit US-ASCII, the UTF-8 charset is
- identical to the US-ASCII charset.
-
- UTF-8 may require multiple bytes to represent a single character /
- code point; thus, the length of a UTF8String in octets may be
- different from the number of characters encoded.
-
- Note that the AVP Length field of an UTF8String is measured in
- octets not characters.
-
-
-
-
-Fajardo, et al. Standards Track [Page 45]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DiameterIdentity
-
- The DiameterIdentity format is derived from the OctetString Basic
- AVP Format.
-
- DiameterIdentity = FQDN/Realm
-
- The DiameterIdentity value is used to uniquely identify either:
-
- * A Diameter node for purposes of duplicate connection and
- routing loop detection.
-
- * A Realm to determine whether messages can be satisfied locally
- or whether they must be routed or redirected.
-
- When a DiameterIdentity value is used to identify a Diameter node,
- the contents of the string MUST be the Fully Qualified Domain Name
- (FQDN) of the Diameter node. If multiple Diameter nodes run on
- the same host, each Diameter node MUST be assigned a unique
- DiameterIdentity. If a Diameter node can be identified by several
- FQDNs, a single FQDN should be picked at startup and used as the
- only DiameterIdentity for that node, whatever the connection on
- which it is sent. In this document, note that DiameterIdentity is
- in ASCII form in order to be compatible with existing DNS
- infrastructure. See Appendix D for interactions between the
- Diameter protocol and Internationalized Domain Names (IDNs).
-
- DiameterURI
-
- The DiameterURI MUST follow the Uniform Resource Identifiers (RFC
- 3986) syntax [RFC3986] rules specified below:
-
- "aaa://" FQDN [ port ] [ transport ] [ protocol ]
-
- ; No transport security
-
- "aaas://" FQDN [ port ] [ transport ] [ protocol ]
-
- ; Transport security used
-
- FQDN = &lt; Fully Qualified Domain Name >
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 46]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- port = ":" 1*DIGIT
-
- ; One of the ports used to listen for
- ; incoming connections.
- ; If absent, the default Diameter port
- ; (3868) is assumed if no transport
- ; security is used and port 5658 when
- ; transport security (TLS/TCP and DTLS/SCTP)
- ; is used.
-
- transport = ";transport=" transport-protocol
-
- ; One of the transports used to listen
- ; for incoming connections. If absent,
- ; the default protocol is assumed to be TCP.
- ; UDP MUST NOT be used when the aaa-protocol
- ; field is set to diameter.
-
- transport-protocol = ( "tcp" / "sctp" / "udp" )
-
- protocol = ";protocol=" aaa-protocol
-
- ; If absent, the default AAA protocol
- ; is Diameter.
-
- aaa-protocol = ( "diameter" / "radius" / "tacacs+" )
-
- The following are examples of valid Diameter host identities:
-
- aaa://host.example.com;transport=tcp
- aaa://host.example.com:6666;transport=tcp
- aaa://host.example.com;protocol=diameter
- aaa://host.example.com:6666;protocol=diameter
- aaa://host.example.com:6666;transport=tcp;protocol=diameter
- aaa://host.example.com:1813;transport=udp;protocol=radius
-
- Enumerated
-
- The Enumerated format is derived from the Integer32 Basic AVP
- Format. The definition contains a list of valid values and their
- interpretation and is described in the Diameter application
- introducing the AVP.
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 47]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- IPFilterRule
-
- The IPFilterRule format is derived from the OctetString Basic AVP
- Format and uses the ASCII charset. The rule syntax is a modified
- subset of ipfw(8) from FreeBSD. Packets may be filtered based on
- the following information that is associated with it:
-
- Direction (in or out)
- Source and destination IP address (possibly masked)
- Protocol
- Source and destination port (lists or ranges)
- TCP flags
- IP fragment flag
- IP options
- ICMP types
-
- Rules for the appropriate direction are evaluated in order, with the
- first matched rule terminating the evaluation. Each packet is
- evaluated once. If no rule matches, the packet is dropped if the
- last rule evaluated was a permit, and passed if the last rule was a
- deny.
-
- IPFilterRule filters MUST follow the format:
-
- action dir proto from src to dst [options]
-
- action permit - Allow packets that match the rule.
- deny - Drop packets that match the rule.
-
- dir "in" is from the terminal, "out" is to the
- terminal.
-
- proto An IP protocol specified by number. The "ip"
- keyword means any protocol will match.
-
- src and dst &lt;address/mask> [ports]
-
- The &lt;address/mask> may be specified as:
- ipno An IPv4 or IPv6 number in dotted-
- quad or canonical IPv6 form. Only
- this exact IP number will match the
- rule.
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 48]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- ipno/bits An IP number as above with a mask
- width of the form 192.0.2.10/24. In
- this case, all IP numbers from
- 192.0.2.0 to 192.0.2.255 will match.
- The bit width MUST be valid for the
- IP version, and the IP number MUST
- NOT have bits set beyond the mask.
- For a match to occur, the same IP
- version must be present in the
- packet that was used in describing
- the IP address. To test for a
- particular IP version, the bits part
- can be set to zero. The keyword
- "any" is 0.0.0.0/0 or the IPv6
- equivalent. The keyword "assigned"
- is the address or set of addresses
- assigned to the terminal. For IPv4,
- a typical first rule is often "deny
- in ip! assigned".
-
- The sense of the match can be inverted by
- preceding an address with the not modifier (!),
- causing all other addresses to be matched
- instead. This does not affect the selection of
- port numbers.
-
- With the TCP, UDP, and SCTP protocols, optional
- ports may be specified as:
-
- {port/port-port}[,ports[,...]]
-
- The '-' notation specifies a range of ports
- (including boundaries).
-
- Fragmented packets that have a non-zero offset
- (i.e., not the first fragment) will never match
- a rule that has one or more port
- specifications. See the frag option for
- details on matching fragmented packets.
-
- options:
- frag Match if the packet is a fragment and this is not
- the first fragment of the datagram. frag may not
- be used in conjunction with either tcpflags or
- TCP/UDP port specifications.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 49]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- ipoptions spec
- Match if the IP header contains the comma-separated
- list of options specified in spec. The
- supported IP options are:
-
- ssrr (strict source route), lsrr (loose source
- route), rr (record packet route), and ts
- (timestamp). The absence of a particular option
- may be denoted with a '!'.
-
- tcpoptions spec
- Match if the TCP header contains the comma-separated
- list of options specified in spec. The
- supported TCP options are:
-
- mss (maximum segment size), window (tcp window
- advertisement), sack (selective ack), ts (rfc1323
- timestamp), and cc (rfc1644 t/tcp connection
- count). The absence of a particular option may
- be denoted with a '!'.
-
- established
- TCP packets only. Match packets that have the RST
- or ACK bits set.
-
- setup TCP packets only. Match packets that have the SYN
- bit set but no ACK bit.
-
-
- tcpflags spec
- TCP packets only. Match if the TCP header
- contains the comma-separated list of flags
- specified in spec. The supported TCP flags are:
-
- fin, syn, rst, psh, ack, and urg. The absence of a
- particular flag may be denoted with a '!'. A rule
- that contains a tcpflags specification can never
- match a fragmented packet that has a non-zero
- offset. See the frag option for details on
- matching fragmented packets.
-
- icmptypes types
- ICMP packets only. Match if the ICMP type is in
- the list types. The list may be specified as any
- combination of ranges or individual types
- separated by commas. Both the numeric values and
- the symbolic values listed below can be used. The
- supported ICMP types are:
-
-
-
-Fajardo, et al. Standards Track [Page 50]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- echo reply (0), destination unreachable (3),
- source quench (4), redirect (5), echo request
- (8), router advertisement (9), router
- solicitation (10), time-to-live exceeded (11), IP
- header bad (12), timestamp request (13),
- timestamp reply (14), information request (15),
- information reply (16), address mask request (17),
- and address mask reply (18).
-
- There is one kind of packet that the access device MUST always
- discard, that is an IP fragment with a fragment offset of one. This
- is a valid packet, but it only has one use, to try to circumvent
- firewalls.
-
- An access device that is unable to interpret or apply a deny rule
- MUST terminate the session. An access device that is unable to
- interpret or apply a permit rule MAY apply a more restrictive rule.
- An access device MAY apply deny rules of its own before the supplied
- rules, for example to protect the access device owner's
- infrastructure.
-
-4.4. Grouped AVP Values
-
- The Diameter protocol allows AVP values of type 'Grouped'. This
- implies that the Data field is actually a sequence of AVPs. It is
- possible to include an AVP with a Grouped type within a Grouped type,
- that is, to nest them. AVPs within an AVP of type Grouped have the
- same padding requirements as non-Grouped AVPs, as defined in
- Section 4.4.
-
- The AVP Code numbering space of all AVPs included in a Grouped AVP is
- the same as for non-Grouped AVPs. Receivers of a Grouped AVP that
- does not have the 'M' (mandatory) bit set and one or more of the
- encapsulated AVPs within the group has the 'M' (mandatory) bit set
- MAY simply be ignored if the Grouped AVP itself is unrecognized. The
- rule applies even if the encapsulated AVP with its 'M' (mandatory)
- bit set is further encapsulated within other sub-groups, i.e., other
- Grouped AVPs embedded within the Grouped AVP.
-
- Every Grouped AVP definition MUST include a corresponding grammar,
- using ABNF [RFC5234] (with modifications), as defined below.
-
- grouped-avp-def = "&lt;" name ">" "::=" avp
-
- name-fmt = ALPHA *(ALPHA / DIGIT / "-")
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 51]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- name = name-fmt
- ; The name has to be the name of an AVP,
- ; defined in the base or extended Diameter
- ; specifications.
-
- avp = header *fixed *required *optional
-
- header = "&lt;" "AVP-Header:" avpcode [vendor] ">"
-
- avpcode = 1*DIGIT
- ; The AVP Code assigned to the Grouped AVP.
-
- vendor = 1*DIGIT
- ; The Vendor-ID assigned to the Grouped AVP.
- ; If absent, the default value of zero is
- ; used.
-
-4.4.1. Example AVP with a Grouped Data Type
-
- The Example-AVP (AVP Code 999999) is of type Grouped and is used to
- clarify how Grouped AVP values work. The Grouped Data field has the
- following CCF grammar:
-
- Example-AVP ::= &lt; AVP Header: 999999 >
- { Origin-Host }
- 1*{ Session-Id }
- *[ AVP ]
-
- An Example-AVP with Grouped Data follows.
-
- The Origin-Host AVP (Section 6.3) is required. In this case:
-
- Origin-Host = "example.com".
-
- One or more Session-Ids must follow. Here there are two:
-
- Session-Id =
- "grump.example.com:33041;23432;893;0AF3B81"
-
- Session-Id =
- "grump.example.com:33054;23561;2358;0AF3B82"
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 52]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- optional AVPs included are
-
- Recovery-Policy = &lt;binary>
- 2163bc1d0ad82371f6bc09484133c3f09ad74a0dd5346d54195a7cf0b35
- 2cabc881839a4fdcfbc1769e2677a4c1fb499284c5f70b48f58503a45c5
- c2d6943f82d5930f2b7c1da640f476f0e9c9572a50db8ea6e51e1c2c7bd
- f8bb43dc995144b8dbe297ac739493946803e1cee3e15d9b765008a1b2a
- cf4ac777c80041d72c01e691cf751dbf86e85f509f3988e5875dc905119
- 26841f00f0e29a6d1ddc1a842289d440268681e052b30fb638045f7779c
- 1d873c784f054f688f5001559ecff64865ef975f3e60d2fd7966b8c7f92
-
- Futuristic-Acct-Record = &lt;binary>
- fe19da5802acd98b07a5b86cb4d5d03f0314ab9ef1ad0b67111ff3b90a0
- 57fe29620bf3585fd2dd9fcc38ce62f6cc208c6163c008f4258d1bc88b8
- 17694a74ccad3ec69269461b14b2e7a4c111fb239e33714da207983f58c
- 41d018d56fe938f3cbf089aac12a912a2f0d1923a9390e5f789cb2e5067
- d3427475e49968f841
-
- The data for the optional AVPs is represented in hexadecimal form
- since the format of these AVPs is not known at the time of definition
- of the Example-AVP group nor (likely) at the time when the example
- instance of this AVP is interpreted -- except by Diameter
- implementations that support the same set of AVPs. The encoding
- example illustrates how padding is used and how length fields are
- calculated. Also, note that AVPs may be present in the Grouped AVP
- value that the receiver cannot interpret (here, the Recover-Policy
- and Futuristic-Acct-Record AVPs). The length of the Example-AVP is
- the sum of all the length of the member AVPs, including their
- padding, plus the Example-AVP header size.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 53]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- This AVP would be encoded as follows:
-
- 0 1 2 3 4 5 6 7
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 0 | Example AVP Header (AVP Code = 999999), Length = 496 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 8 | Origin-Host AVP Header (AVP Code = 264), Length = 19 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 16 | 'e' | 'x' | 'a' | 'm' | 'p' | 'l' | 'e' | '.' |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 24 | 'c' | 'o' | 'm' |Padding| Session-Id AVP Header |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 32 | (AVP Code = 263), Length = 49 | 'g' | 'r' | 'u' | 'm' |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- . . .
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 72 | 'F' | '3' | 'B' | '8' | '1' |Padding|Padding|Padding|
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 80 | Session-Id AVP Header (AVP Code = 263), Length = 50 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 88 | 'g' | 'r' | 'u' | 'm' | 'p' | '.' | 'e' | 'x' |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- . . .
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 120| '5' | '8' | ';' | '0' | 'A' | 'F' | '3' | 'B' |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 128| '8' | '2' |Padding|Padding| Recovery-Policy Header (AVP |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 136| Code = 8341), Length = 223 | 0x21 | 0x63 | 0xbc | 0x1d |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 144| 0x0a | 0xd8 | 0x23 | 0x71 | 0xf6 | 0xbc | 0x09 | 0x48 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- . . .
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 352| 0x8c | 0x7f | 0x92 |Padding| Futuristic-Acct-Record Header |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 328|(AVP Code = 15930),Length = 137| 0xfe | 0x19 | 0xda | 0x58 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 336| 0x02 | 0xac | 0xd9 | 0x8b | 0x07 | 0xa5 | 0xb8 | 0xc6 |
- +-------+-------+-------+-------+-------+-------+-------+-------+
- . . .
- +-------+-------+-------+-------+-------+-------+-------+-------+
- 488| 0xe4 | 0x99 | 0x68 | 0xf8 | 0x41 |Padding|Padding|Padding|
- +-------+-------+-------+-------+-------+-------+-------+-------+
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 54]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-4.5. Diameter Base Protocol AVPs
-
- The following table describes the Diameter AVPs defined in the base
- protocol, their AVP Code values, types, and possible flag values.
-
- Due to space constraints, the short form DiamIdent is used to
- represent DiameterIdentity.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 55]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- +----------+
- | AVP Flag |
- | rules |
- |----+-----|
- AVP Section | |MUST |
- Attribute Name Code Defined Data Type |MUST| NOT |
- -----------------------------------------|----+-----|
- Acct- 85 9.8.2 Unsigned32 | M | V |
- Interim-Interval | | |
- Accounting- 483 9.8.7 Enumerated | M | V |
- Realtime-Required | | |
- Acct- 50 9.8.5 UTF8String | M | V |
- Multi-Session-Id | | |
- Accounting- 485 9.8.3 Unsigned32 | M | V |
- Record-Number | | |
- Accounting- 480 9.8.1 Enumerated | M | V |
- Record-Type | | |
- Acct- 44 9.8.4 OctetString| M | V |
- Session-Id | | |
- Accounting- 287 9.8.6 Unsigned64 | M | V |
- Sub-Session-Id | | |
- Acct- 259 6.9 Unsigned32 | M | V |
- Application-Id | | |
- Auth- 258 6.8 Unsigned32 | M | V |
- Application-Id | | |
- Auth-Request- 274 8.7 Enumerated | M | V |
- Type | | |
- Authorization- 291 8.9 Unsigned32 | M | V |
- Lifetime | | |
- Auth-Grace- 276 8.10 Unsigned32 | M | V |
- Period | | |
- Auth-Session- 277 8.11 Enumerated | M | V |
- State | | |
- Re-Auth-Request- 285 8.12 Enumerated | M | V |
- Type | | |
- Class 25 8.20 OctetString| M | V |
- Destination-Host 293 6.5 DiamIdent | M | V |
- Destination- 283 6.6 DiamIdent | M | V |
- Realm | | |
- Disconnect-Cause 273 5.4.3 Enumerated | M | V |
- Error-Message 281 7.3 UTF8String | | V,M |
- Error-Reporting- 294 7.4 DiamIdent | | V,M |
- Host | | |
- Event-Timestamp 55 8.21 Time | M | V |
- Experimental- 297 7.6 Grouped | M | V |
- Result | | |
- -----------------------------------------|----+-----|
-
-
-
-
-Fajardo, et al. Standards Track [Page 56]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- +----------+
- | AVP Flag |
- | rules |
- |----+-----|
- AVP Section | |MUST |
- Attribute Name Code Defined Data Type |MUST| NOT |
- -----------------------------------------|----+-----|
- Experimental- 298 7.7 Unsigned32 | M | V |
- Result-Code | | |
- Failed-AVP 279 7.5 Grouped | M | V |
- Firmware- 267 5.3.4 Unsigned32 | | V,M |
- Revision | | |
- Host-IP-Address 257 5.3.5 Address | M | V |
- Inband-Security | M | V |
- -Id 299 6.10 Unsigned32 | | |
- Multi-Round- 272 8.19 Unsigned32 | M | V |
- Time-Out | | |
- Origin-Host 264 6.3 DiamIdent | M | V |
- Origin-Realm 296 6.4 DiamIdent | M | V |
- Origin-State-Id 278 8.16 Unsigned32 | M | V |
- Product-Name 269 5.3.7 UTF8String | | V,M |
- Proxy-Host 280 6.7.3 DiamIdent | M | V |
- Proxy-Info 284 6.7.2 Grouped | M | V |
- Proxy-State 33 6.7.4 OctetString| M | V |
- Redirect-Host 292 6.12 DiamURI | M | V |
- Redirect-Host- 261 6.13 Enumerated | M | V |
- Usage | | |
- Redirect-Max- 262 6.14 Unsigned32 | M | V |
- Cache-Time | | |
- Result-Code 268 7.1 Unsigned32 | M | V |
- Route-Record 282 6.7.1 DiamIdent | M | V |
- Session-Id 263 8.8 UTF8String | M | V |
- Session-Timeout 27 8.13 Unsigned32 | M | V |
- Session-Binding 270 8.17 Unsigned32 | M | V |
- Session-Server- 271 8.18 Enumerated | M | V |
- Failover | | |
- Supported- 265 5.3.6 Unsigned32 | M | V |
- Vendor-Id | | |
- Termination- 295 8.15 Enumerated | M | V |
- Cause | | |
- User-Name 1 8.14 UTF8String | M | V |
- Vendor-Id 266 5.3.3 Unsigned32 | M | V |
- Vendor-Specific- 260 6.11 Grouped | M | V |
- Application-Id | | |
- -----------------------------------------|----+-----|
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 57]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5. Diameter Peers
-
- This section describes how Diameter nodes establish connections and
- communicate with peers.
-
-5.1. Peer Connections
-
- Connections between diameter peers are established using their valid
- DiameterIdentity. A Diameter node initiating a connection to a peer
- MUST know the peer's DiameterIdentity. Methods for discovering a
- Diameter peer can be found in Section 5.2.
-
- Although a Diameter node may have many possible peers with which it
- is able to communicate, it may not be economical to have an
- established connection to all of them. At a minimum, a Diameter node
- SHOULD have an established connection with two peers per realm, known
- as the primary and secondary peers. Of course, a node MAY have
- additional connections, if it is deemed necessary. Typically, all
- messages for a realm are sent to the primary peer but, in the event
- that failover procedures are invoked, any pending requests are sent
- to the secondary peer. However, implementations are free to load
- balance requests between a set of peers.
-
- Note that a given peer MAY act as a primary for a given realm while
- acting as a secondary for another realm.
-
- When a peer is deemed suspect, which could occur for various reasons,
- including not receiving a DWA within an allotted time frame, no new
- requests should be forwarded to the peer, but failover procedures are
- invoked. When an active peer is moved to this mode, additional
- connections SHOULD be established to ensure that the necessary number
- of active connections exists.
-
- There are two ways that a peer is removed from the suspect peer list:
-
- 1. The peer is no longer reachable, causing the transport connection
- to be shut down. The peer is moved to the closed state.
-
- 2. Three watchdog messages are exchanged with accepted round-trip
- times, and the connection to the peer is considered stabilized.
-
- In the event the peer being removed is either the primary or
- secondary, an alternate peer SHOULD replace the deleted peer and
- assume the role of either primary or secondary.
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 58]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5.2. Diameter Peer Discovery
-
- Allowing for dynamic Diameter agent discovery makes possible simpler
- and more robust deployment of Diameter services. In order to promote
- interoperable implementations of Diameter peer discovery, the
- following mechanisms (manual configuration and DNS) are described.
- These are based on existing IETF standards. Both mechanisms MUST be
- supported by all Diameter implementations; either MAY be used.
-
- There are two cases where Diameter peer discovery may be performed.
- The first is when a Diameter client needs to discover a first-hop
- Diameter agent. The second case is when a Diameter agent needs to
- discover another agent for further handling of a Diameter operation.
- In both cases, the following 'search order' is recommended:
-
- 1. The Diameter implementation consults its list of statically
- (manually) configured Diameter agent locations. These will be
- used if they exist and respond.
-
- 2. The Diameter implementation performs a NAPTR query for a server
- in a particular realm. The Diameter implementation has to know,
- in advance, in which realm to look for a Diameter agent. This
- could be deduced, for example, from the 'realm' in an NAI on
- which a Diameter implementation needed to perform a Diameter
- operation.
-
- The NAPTR usage in Diameter follows the S-NAPTR DDDS application
- [RFC3958] in which the SERVICE field includes tags for the
- desired application and supported application protocol. The
- application service tag for a Diameter application is 'aaa' and
- the supported application protocol tags are 'diameter.tcp',
- 'diameter.sctp', 'diameter.dtls', or 'diameter.tls.tcp'
- [RFC6408].
-
- The client can follow the resolution process defined by the
- S-NAPTR DDDS [RFC3958] application to find a matching SRV, A, or
- AAAA record of a suitable peer. The domain suffixes in the NAPTR
- replacement field SHOULD match the domain of the original query.
- An example can be found in Appendix B.
-
- 3. If no NAPTR records are found, the requester directly queries for
- one of the following SRV records: for Diameter over TCP, use
- "_diameter._tcp.realm"; for Diameter over TLS, use
- "_diameters._tcp.realm"; for Diameter over SCTP, use
- "_diameter._sctp.realm"; for Diameter over DTLS, use
- "_diameters._sctp.realm". If SRV records are found, then the
- requester can perform address record query (A RR's and/or AAAA
-
-
-
-
-Fajardo, et al. Standards Track [Page 59]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- RR's) for the target hostname specified in the SRV records
- following the rules given in [RFC2782]. If no SRV records are
- found, the requester gives up.
-
- If the server is using a site certificate, the domain name in the
- NAPTR query and the domain name in the replacement field MUST both be
- valid based on the site certificate handed out by the server in the
- TLS/TCP and DTLS/SCTP or Internet Key Exchange Protocol (IKE)
- exchange. Similarly, the domain name in the SRV query and the domain
- name in the target in the SRV record MUST both be valid based on the
- same site certificate. Otherwise, an attacker could modify the DNS
- records to contain replacement values in a different domain, and the
- client could not validate whether this was the desired behavior or
- the result of an attack.
-
- Also, the Diameter peer MUST check to make sure that the discovered
- peers are authorized to act in its role. Authentication via IKE or
- TLS/TCP and DTLS/SCTP, or validation of DNS RRs via DNSSEC is not
- sufficient to conclude this. For example, a web server may have
- obtained a valid TLS/TCP and DTLS/SCTP certificate, and secured RRs
- may be included in the DNS, but this does not imply that it is
- authorized to act as a Diameter server.
-
- Authorization can be achieved, for example, by the configuration of a
- Diameter server Certification Authority (CA). The server CA issues a
- certificate to the Diameter server, which includes an Object
- Identifier (OID) to indicate the subject is a Diameter server in the
- Extended Key Usage extension [RFC5280]. This certificate is then
- used during TLS/TCP, DTLS/SCTP, or IKE security negotiation.
- However, note that, at the time of writing, no Diameter server
- Certification Authorities exist.
-
- A dynamically discovered peer causes an entry in the peer table (see
- Section 2.6) to be created. Note that entries created via DNS MUST
- expire (or be refreshed) within the DNS Time to Live (TTL). If a
- peer is discovered outside of the local realm, a routing table entry
- (see Section 2.7) for the peer's realm is created. The routing table
- entry's expiration MUST match the peer's expiration value.
-
-5.3. Capabilities Exchange
-
- When two Diameter peers establish a transport connection, they MUST
- exchange the Capabilities Exchange messages, as specified in the peer
- state machine (see Section 5.6). This message allows the discovery
- of a peer's identity and its capabilities (protocol version number,
- the identifiers of supported Diameter applications, security
- mechanisms, etc.).
-
-
-
-
-Fajardo, et al. Standards Track [Page 60]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The receiver only issues commands to its peers that have advertised
- support for the Diameter application that defines the command. A
- Diameter node MUST cache the supported Application Ids in order to
- ensure that unrecognized commands and/or AVPs are not unnecessarily
- sent to a peer.
-
- A receiver of a Capabilities-Exchange-Request (CER) message that does
- not have any applications in common with the sender MUST return a
- Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to
- DIAMETER_NO_COMMON_APPLICATION and SHOULD disconnect the transport
- layer connection. Note that receiving a CER or CEA from a peer
- advertising itself as a relay (see Section 2.4) MUST be interpreted
- as having common applications with the peer.
-
- The receiver of the Capabilities-Exchange-Request (CER) MUST
- determine common applications by computing the intersection of its
- own set of supported Application Ids against all of the
- Application-Id AVPs (Auth-Application-Id, Acct-Application-Id, and
- Vendor-Specific-Application-Id) present in the CER. The value of the
- Vendor-Id AVP in the Vendor-Specific-Application-Id MUST NOT be used
- during computation. The sender of the Capabilities-Exchange-Answer
- (CEA) SHOULD include all of its supported applications as a hint to
- the receiver regarding all of its application capabilities.
-
- Diameter implementations SHOULD first attempt to establish a TLS/TCP
- and DTLS/SCTP connection prior to the CER/CEA exchange. This
- protects the capabilities information of both peers. To support
- older Diameter implementations that do not fully conform to this
- document, the transport security MAY still be negotiated via an
- Inband-Security AVP. In this case, the receiver of a Capabilities-
- Exchange-Request (CER) message that does not have any security
- mechanisms in common with the sender MUST return a Capabilities-
- Exchange-Answer (CEA) with the Result-Code AVP set to
- DIAMETER_NO_COMMON_SECURITY and SHOULD disconnect the transport layer
- connection.
-
- CERs received from unknown peers MAY be silently discarded, or a CEA
- MAY be issued with the Result-Code AVP set to DIAMETER_UNKNOWN_PEER.
- In both cases, the transport connection is closed. If the local
- policy permits receiving CERs from unknown hosts, a successful CEA
- MAY be returned. If a CER from an unknown peer is answered with a
- successful CEA, the lifetime of the peer entry is equal to the
- lifetime of the transport connection. In case of a transport
- failure, all the pending transactions destined to the unknown peer
- can be discarded.
-
- The CER and CEA messages MUST NOT be proxied, redirected, or relayed.
-
-
-
-
-Fajardo, et al. Standards Track [Page 61]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Since the CER/CEA messages cannot be proxied, it is still possible
- that an upstream agent will receive a message for which it has no
- available peers to handle the application that corresponds to the
- Command Code. In such instances, the 'E' bit is set in the answer
- message (Section 7) with the Result-Code AVP set to
- DIAMETER_UNABLE_TO_DELIVER to inform the downstream agent to take
- action (e.g., re-routing request to an alternate peer).
-
- With the exception of the Capabilities-Exchange-Request message, a
- message of type Request that includes the Auth-Application-Id or
- Acct-Application-Id AVPs, or a message with an application-specific
- Command Code MAY only be forwarded to a host that has explicitly
- advertised support for the application (or has advertised the Relay
- Application Id).
-
-5.3.1. Capabilities-Exchange-Request
-
- The Capabilities-Exchange-Request (CER), indicated by the Command
- Code set to 257 and the Command Flags' 'R' bit set, is sent to
- exchange local capabilities. Upon detection of a transport failure,
- this message MUST NOT be sent to an alternate peer.
-
- When Diameter is run over SCTP [RFC4960] or DTLS/SCTP [RFC6083],
- which allow for connections to span multiple interfaces and multiple
- IP addresses, the Capabilities-Exchange-Request message MUST contain
- one Host-IP-Address AVP for each potential IP address that MAY be
- locally used when transmitting Diameter messages.
-
- Message Format
-
- &lt;CER> ::= &lt; Diameter Header: 257, REQ >
- { Origin-Host }
- { Origin-Realm }
- 1* { Host-IP-Address }
- { Vendor-Id }
- { Product-Name }
- [ Origin-State-Id ]
- * [ Supported-Vendor-Id ]
- * [ Auth-Application-Id ]
- * [ Inband-Security-Id ]
- * [ Acct-Application-Id ]
- * [ Vendor-Specific-Application-Id ]
- [ Firmware-Revision ]
- * [ AVP ]
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 62]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5.3.2. Capabilities-Exchange-Answer
-
- The Capabilities-Exchange-Answer (CEA), indicated by the Command Code
- set to 257 and the Command Flags' 'R' bit cleared, is sent in
- response to a CER message.
-
- When Diameter is run over SCTP [RFC4960] or DTLS/SCTP [RFC6083],
- which allow connections to span multiple interfaces, hence, multiple
- IP addresses, the Capabilities-Exchange-Answer message MUST contain
- one Host-IP-Address AVP for each potential IP address that MAY be
- locally used when transmitting Diameter messages.
-
- Message Format
-
- &lt;CEA> ::= &lt; Diameter Header: 257 >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- 1* { Host-IP-Address }
- { Vendor-Id }
- { Product-Name }
- [ Origin-State-Id ]
- [ Error-Message ]
- [ Failed-AVP ]
- * [ Supported-Vendor-Id ]
- * [ Auth-Application-Id ]
- * [ Inband-Security-Id ]
- * [ Acct-Application-Id ]
- * [ Vendor-Specific-Application-Id ]
- [ Firmware-Revision ]
- * [ AVP ]
-
-5.3.3. Vendor-Id AVP
-
- The Vendor-Id AVP (AVP Code 266) is of type Unsigned32 and contains
- the IANA "SMI Network Management Private Enterprise Codes"
- [ENTERPRISE] value assigned to the Diameter Software vendor. It is
- envisioned that the combination of the Vendor-Id, Product-Name
- (Section 5.3.7), and Firmware-Revision (Section 5.3.4) AVPs may
- provide useful debugging information.
-
- A Vendor-Id value of zero in the CER or CEA message is reserved and
- indicates that this field is ignored.
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 63]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5.3.4. Firmware-Revision AVP
-
- The Firmware-Revision AVP (AVP Code 267) is of type Unsigned32 and is
- used to inform a Diameter peer of the firmware revision of the
- issuing device.
-
- For devices that do not have a firmware revision (general-purpose
- computers running Diameter software modules, for instance), the
- revision of the Diameter software module may be reported instead.
-
-5.3.5. Host-IP-Address AVP
-
- The Host-IP-Address AVP (AVP Code 257) is of type Address and is used
- to inform a Diameter peer of the sender's IP address. All source
- addresses that a Diameter node expects to use with SCTP [RFC4960] or
- DTLS/SCTP [RFC6083] MUST be advertised in the CER and CEA messages by
- including a Host-IP-Address AVP for each address.
-
-5.3.6. Supported-Vendor-Id AVP
-
- The Supported-Vendor-Id AVP (AVP Code 265) is of type Unsigned32 and
- contains the IANA "SMI Network Management Private Enterprise Codes"
- [ENTERPRISE] value assigned to a vendor other than the device vendor
- but including the application vendor. This is used in the CER and
- CEA messages in order to inform the peer that the sender supports (a
- subset of) the Vendor-Specific AVPs defined by the vendor identified
- in this AVP. The value of this AVP MUST NOT be set to zero.
- Multiple instances of this AVP containing the same value SHOULD NOT
- be sent.
-
-5.3.7. Product-Name AVP
-
- The Product-Name AVP (AVP Code 269) is of type UTF8String and
- contains the vendor-assigned name for the product. The Product-Name
- AVP SHOULD remain constant across firmware revisions for the same
- product.
-
-5.4. Disconnecting Peer Connections
-
- When a Diameter node disconnects one of its transport connections,
- its peer cannot know the reason for the disconnect and will most
- likely assume that a connectivity problem occurred or that the peer
- has rebooted. In these cases, the peer may periodically attempt to
- reconnect, as stated in Section 2.1. In the event that the
- disconnect was a result of either a shortage of internal resources or
- simply that the node in question has no intentions of forwarding any
- Diameter messages to the peer in the foreseeable future, a periodic
-
-
-
-
-Fajardo, et al. Standards Track [Page 64]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- connection request would not be welcomed. The Disconnection-Reason
- AVP contains the reason the Diameter node issued the Disconnect-Peer-
- Request message.
-
- The Disconnect-Peer-Request message is used by a Diameter node to
- inform its peer of its intent to disconnect the transport layer and
- that the peer shouldn't reconnect unless it has a valid reason to do
- so (e.g., message to be forwarded). Upon receipt of the message, the
- Disconnect-Peer-Answer message is returned, which SHOULD contain an
- error if messages have recently been forwarded, and are likely in
- flight, which would otherwise cause a race condition.
-
- The receiver of the Disconnect-Peer-Answer message initiates the
- transport disconnect. The sender of the Disconnect-Peer-Answer
- message should be able to detect the transport closure and clean up
- the connection.
-
-5.4.1. Disconnect-Peer-Request
-
- The Disconnect-Peer-Request (DPR), indicated by the Command Code set
- to 282 and the Command Flags' 'R' bit set, is sent to a peer to
- inform it of its intentions to shut down the transport connection.
- Upon detection of a transport failure, this message MUST NOT be sent
- to an alternate peer.
-
- Message Format
-
- &lt;DPR> ::= &lt; Diameter Header: 282, REQ >
- { Origin-Host }
- { Origin-Realm }
- { Disconnect-Cause }
- * [ AVP ]
-
-5.4.2. Disconnect-Peer-Answer
-
- The Disconnect-Peer-Answer (DPA), indicated by the Command Code set
- to 282 and the Command Flags' 'R' bit cleared, is sent as a response
- to the Disconnect-Peer-Request message. Upon receipt of this
- message, the transport connection is shut down.
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 65]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Message Format
-
- &lt;DPA> ::= &lt; Diameter Header: 282 >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- [ Error-Message ]
- [ Failed-AVP ]
- * [ AVP ]
-
-
-5.4.3. Disconnect-Cause AVP
-
- The Disconnect-Cause AVP (AVP Code 273) is of type Enumerated. A
- Diameter node MUST include this AVP in the Disconnect-Peer-Request
- message to inform the peer of the reason for its intention to shut
- down the transport connection. The following values are supported:
-
- REBOOTING 0
- A scheduled reboot is imminent. A receiver of a DPR with
- above result code MAY attempt reconnection.
-
- BUSY 1
- The peer's internal resources are constrained, and it has
- determined that the transport connection needs to be closed.
- A receiver of a DPR with above result code SHOULD NOT attempt
- reconnection.
-
- DO_NOT_WANT_TO_TALK_TO_YOU 2
- The peer has determined that it does not see a need for the
- transport connection to exist, since it does not expect any
- messages to be exchanged in the near future. A receiver of a
- DPR with above result code SHOULD NOT attempt reconnection.
-
-5.5. Transport Failure Detection
-
- Given the nature of the Diameter protocol, it is recommended that
- transport failures be detected as soon as possible. Detecting such
- failures will minimize the occurrence of messages sent to unavailable
- agents, resulting in unnecessary delays, and will provide better
- failover performance. The Device-Watchdog-Request and Device-
- Watchdog-Answer messages, defined in this section, are used to pro-
- actively detect transport failures.
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 66]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5.5.1. Device-Watchdog-Request
-
- The Device-Watchdog-Request (DWR), indicated by the Command Code set
- to 280 and the Command Flags' 'R' bit set, is sent to a peer when no
- traffic has been exchanged between two peers (see Section 5.5.3).
- Upon detection of a transport failure, this message MUST NOT be sent
- to an alternate peer.
-
- Message Format
-
- &lt;DWR> ::= &lt; Diameter Header: 280, REQ >
- { Origin-Host }
- { Origin-Realm }
- [ Origin-State-Id ]
- * [ AVP ]
-
-5.5.2. Device-Watchdog-Answer
-
- The Device-Watchdog-Answer (DWA), indicated by the Command Code set
- to 280 and the Command Flags' 'R' bit cleared, is sent as a response
- to the Device-Watchdog-Request message.
-
- Message Format
-
- &lt;DWA> ::= &lt; Diameter Header: 280 >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- [ Error-Message ]
- [ Failed-AVP ]
- [ Origin-State-Id ]
- * [ AVP ]
-
-5.5.3. Transport Failure Algorithm
-
- The transport failure algorithm is defined in [RFC3539]. All
- Diameter implementations MUST support the algorithm defined in that
- specification in order to be compliant to the Diameter base protocol.
-
-5.5.4. Failover and Failback Procedures
-
- In the event that a transport failure is detected with a peer, it is
- necessary for all pending request messages to be forwarded to an
- alternate agent, if possible. This is commonly referred to as
- "failover".
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 67]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- In order for a Diameter node to perform failover procedures, it is
- necessary for the node to maintain a pending message queue for a
- given peer. When an answer message is received, the corresponding
- request is removed from the queue. The Hop-by-Hop Identifier field
- is used to match the answer with the queued request.
-
- When a transport failure is detected, if possible, all messages in
- the queue are sent to an alternate agent with the T flag set. On
- booting a Diameter client or agent, the T flag is also set on any
- remaining records in non-volatile storage that are still waiting to
- be transmitted. An example of a case where it is not possible to
- forward the message to an alternate server is when the message has a
- fixed destination, and the unavailable peer is the message's final
- destination (see Destination-Host AVP). Such an error requires that
- the agent return an answer message with the 'E' bit set and the
- Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER.
-
- It is important to note that multiple identical requests or answers
- MAY be received as a result of a failover. The End-to-End Identifier
- field in the Diameter header along with the Origin-Host AVP MUST be
- used to identify duplicate messages.
-
- As described in Section 2.1, a connection request should be
- periodically attempted with the failed peer in order to re-establish
- the transport connection. Once a connection has been successfully
- established, messages can once again be forwarded to the peer. This
- is commonly referred to as "failback".
-
-5.6. Peer State Machine
-
- This section contains a finite state machine that MUST be observed by
- all Diameter implementations. Each Diameter node MUST follow the
- state machine described below when communicating with each peer.
- Multiple actions are separated by commas, and may continue on
- succeeding lines, as space requires. Similarly, state and next state
- may also span multiple lines, as space requires.
-
- This state machine is closely coupled with the state machine
- described in [RFC3539], which is used to open, close, failover,
- probe, and reopen transport connections. In particular, note that
- [RFC3539] requires the use of watchdog messages to probe connections.
- For Diameter, DWR and DWA messages are to be used.
-
- The I- prefix is used to represent the initiator (connecting)
- connection, while the R- prefix is used to represent the responder
- (listening) connection. The lack of a prefix indicates that the
- event or action is the same regardless of the connection on which the
- event occurred.
-
-
-
-Fajardo, et al. Standards Track [Page 68]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The stable states that a state machine may be in are Closed, I-Open,
- and R-Open; all other states are intermediate. Note that I-Open and
- R-Open are equivalent except for whether the initiator or responder
- transport connection is used for communication.
-
- A CER message is always sent on the initiating connection immediately
- after the connection request is successfully completed. In the case
- of an election, one of the two connections will shut down. The
- responder connection will survive if the Origin-Host of the local
- Diameter entity is higher than that of the peer; the initiator
- connection will survive if the peer's Origin-Host is higher. All
- subsequent messages are sent on the surviving connection. Note that
- the results of an election on one peer are guaranteed to be the
- inverse of the results on the other.
-
- For TLS/TCP and DTLS/SCTP usage, a TLS/TCP and DTLS/SCTP handshake
- SHOULD begin when both ends are in the closed state prior to any
- Diameter message exchanges. The TLS/TCP and DTLS/SCTP connection
- SHOULD be established before sending any CER or CEA message to secure
- and protect the capabilities information of both peers. The TLS/TCP
- and DTLS/SCTP connection SHOULD be disconnected when the state
- machine moves to the closed state. When connecting to responders
- that do not conform to this document (i.e., older Diameter
- implementations that are not prepared to received TLS/TCP and DTLS/
- SCTP connections in the closed state), the initial TLS/TCP and DTLS/
- SCTP connection attempt will fail. The initiator MAY then attempt to
- connect via TCP or SCTP and initiate the TLS/TCP and DTLS/SCTP
- handshake when both ends are in the open state. If the handshake is
- successful, all further messages will be sent via TLS/TCP and DTLS/
- SCTP. If the handshake fails, both ends move to the closed state.
-
- The state machine constrains only the behavior of a Diameter
- implementation as seen by Diameter peers through events on the wire.
-
- Any implementation that produces equivalent results is considered
- compliant.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 69]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- state event action next state
- -----------------------------------------------------------------
- Closed Start I-Snd-Conn-Req Wait-Conn-Ack
- R-Conn-CER R-Accept, R-Open
- Process-CER,
- R-Snd-CEA
-
- Wait-Conn-Ack I-Rcv-Conn-Ack I-Snd-CER Wait-I-CEA
- I-Rcv-Conn-Nack Cleanup Closed
- R-Conn-CER R-Accept, Wait-Conn-Ack/
- Process-CER Elect
- Timeout Error Closed
-
- Wait-I-CEA I-Rcv-CEA Process-CEA I-Open
- R-Conn-CER R-Accept, Wait-Returns
- Process-CER,
- Elect
- I-Peer-Disc I-Disc Closed
- I-Rcv-Non-CEA Error Closed
- Timeout Error Closed
-
- Wait-Conn-Ack/ I-Rcv-Conn-Ack I-Snd-CER,Elect Wait-Returns
- Elect I-Rcv-Conn-Nack R-Snd-CEA R-Open
- R-Peer-Disc R-Disc Wait-Conn-Ack
- R-Conn-CER R-Reject Wait-Conn-Ack/
- Elect
- Timeout Error Closed
-
- Wait-Returns Win-Election I-Disc,R-Snd-CEA R-Open
- I-Peer-Disc I-Disc, R-Open
- R-Snd-CEA
- I-Rcv-CEA R-Disc I-Open
- R-Peer-Disc R-Disc Wait-I-CEA
- R-Conn-CER R-Reject Wait-Returns
- Timeout Error Closed
-
- R-Open Send-Message R-Snd-Message R-Open
- R-Rcv-Message Process R-Open
- R-Rcv-DWR Process-DWR, R-Open
- R-Snd-DWA
- R-Rcv-DWA Process-DWA R-Open
- R-Conn-CER R-Reject R-Open
- Stop R-Snd-DPR Closing
- R-Rcv-DPR R-Snd-DPA Closing
- R-Peer-Disc R-Disc Closed
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 70]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- I-Open Send-Message I-Snd-Message I-Open
- I-Rcv-Message Process I-Open
- I-Rcv-DWR Process-DWR, I-Open
- I-Snd-DWA
- I-Rcv-DWA Process-DWA I-Open
- R-Conn-CER R-Reject I-Open
- Stop I-Snd-DPR Closing
- I-Rcv-DPR I-Snd-DPA Closing
- I-Peer-Disc I-Disc Closed
-
- Closing I-Rcv-DPA I-Disc Closed
- R-Rcv-DPA R-Disc Closed
- Timeout Error Closed
- I-Peer-Disc I-Disc Closed
- R-Peer-Disc R-Disc Closed
-
-5.6.1. Incoming Connections
-
- When a connection request is received from a Diameter peer, it is
- not, in the general case, possible to know the identity of that peer
- until a CER is received from it. This is because host and port
- determine the identity of a Diameter peer; the source port of an
- incoming connection is arbitrary. Upon receipt of a CER, the
- identity of the connecting peer can be uniquely determined from the
- Origin-Host.
-
- For this reason, a Diameter peer must employ logic separate from the
- state machine to receive connection requests, accept them, and await
- the CER. Once the CER arrives on a new connection, the Origin-Host
- that identifies the peer is used to locate the state machine
- associated with that peer, and the new connection and CER are passed
- to the state machine as an R-Conn-CER event.
-
- The logic that handles incoming connections SHOULD close and discard
- the connection if any message other than a CER arrives or if an
- implementation-defined timeout occurs prior to receipt of CER.
-
- Because handling of incoming connections up to and including receipt
- of a CER requires logic, separate from that of any individual state
- machine associated with a particular peer, it is described separately
- in this section rather than in the state machine above.
-
-5.6.2. Events
-
- Transitions and actions in the automaton are caused by events. In
- this section, we will ignore the I- and R- prefixes, since the actual
- event would be identical, but it would occur on one of two possible
- connections.
-
-
-
-Fajardo, et al. Standards Track [Page 71]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Start The Diameter application has signaled that a
- connection should be initiated with the peer.
-
- R-Conn-CER An acknowledgement is received stating that the
- transport connection has been established, and the
- associated CER has arrived.
-
- Rcv-Conn-Ack A positive acknowledgement is received confirming that
- the transport connection is established.
-
- Rcv-Conn-Nack A negative acknowledgement was received stating that
- the transport connection was not established.
-
- Timeout An application-defined timer has expired while waiting
- for some event.
-
- Rcv-CER A CER message from the peer was received.
-
- Rcv-CEA A CEA message from the peer was received.
-
- Rcv-Non-CEA A message, other than a CEA, from the peer was
- received.
-
- Peer-Disc A disconnection indication from the peer was received.
-
- Rcv-DPR A DPR message from the peer was received.
-
- Rcv-DPA A DPA message from the peer was received.
-
- Win-Election An election was held, and the local node was the
- winner.
-
- Send-Message A message is to be sent.
-
- Rcv-Message A message other than CER, CEA, DPR, DPA, DWR, or DWA
- was received.
-
- Stop The Diameter application has signaled that a
- connection should be terminated (e.g., on system
- shutdown).
-
-5.6.3. Actions
-
- Actions in the automaton are caused by events and typically indicate
- the transmission of packets and/or an action to be taken on the
- connection. In this section, we will ignore the I- and R- prefixes,
- since the actual action would be identical, but it would occur on one
- of two possible connections.
-
-
-
-Fajardo, et al. Standards Track [Page 72]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Snd-Conn-Req A transport connection is initiated with the peer.
-
- Accept The incoming connection associated with the R-Conn-CER
- is accepted as the responder connection.
-
- Reject The incoming connection associated with the R-Conn-CER
- is disconnected.
-
- Process-CER The CER associated with the R-Conn-CER is processed.
-
- Snd-CER A CER message is sent to the peer.
-
- Snd-CEA A CEA message is sent to the peer.
-
- Cleanup If necessary, the connection is shut down, and any
- local resources are freed.
-
- Error The transport layer connection is disconnected,
- either politely or abortively, in response to
- an error condition. Local resources are freed.
-
- Process-CEA A received CEA is processed.
-
- Snd-DPR A DPR message is sent to the peer.
-
- Snd-DPA A DPA message is sent to the peer.
-
- Disc The transport layer connection is disconnected,
- and local resources are freed.
-
- Elect An election occurs (see Section 5.6.4 for more
- information).
-
- Snd-Message A message is sent.
-
- Snd-DWR A DWR message is sent.
-
- Snd-DWA A DWA message is sent.
-
- Process-DWR The DWR message is serviced.
-
- Process-DWA The DWA message is serviced.
-
- Process A message is serviced.
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 73]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-5.6.4. The Election Process
-
- The election is performed on the responder. The responder compares
- the Origin-Host received in the CER with its own Origin-Host as two
- streams of octets. If the local Origin-Host lexicographically
- succeeds the received Origin-Host, a Win-Election event is issued
- locally. Diameter identities are in ASCII form; therefore, the
- lexical comparison is consistent with DNS case insensitivity, where
- octets that fall in the ASCII range 'a' through 'z' MUST compare
- equally to their uppercase counterparts between 'A' and 'Z'. See
- Appendix D for interactions between the Diameter protocol and
- Internationalized Domain Name (IDNs).
-
- The winner of the election MUST close the connection it initiated.
- Historically, maintaining the responder side of a connection was more
- efficient than maintaining the initiator side. However, current
- practices makes this distinction irrelevant.
-
-6. Diameter Message Processing
-
- This section describes how Diameter requests and answers are created
- and processed.
-
-6.1. Diameter Request Routing Overview
-
- A request is sent towards its final destination using one of the
- following three combinations of the Destination-Realm and
- Destination-Host AVPs:
-
- o A request that is not able to be proxied (such as a CER) MUST NOT
- contain either Destination-Realm or Destination-Host AVPs.
-
- o A request that needs to be sent to a home server serving a
- specific realm, but not to a specific server (such as the first
- request of a series of round trips), MUST contain a Destination-
- Realm AVP but MUST NOT contain a Destination-Host AVP. For
- Diameter clients, the value of the Destination-Realm AVP MAY be
- extracted from the User-Name AVP, or other methods.
-
- o Otherwise, a request that needs to be sent to a specific home
- server among those serving a given realm MUST contain both the
- Destination-Realm and Destination-Host AVPs.
-
- The Destination-Host AVP is used as described above when the
- destination of the request is fixed, which includes:
-
- o Authentication requests that span multiple round trips.
-
-
-
-
-Fajardo, et al. Standards Track [Page 74]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o A Diameter message that uses a security mechanism that makes use
- of a pre-established session key shared between the source and the
- final destination of the message.
-
- o Server-initiated messages that MUST be received by a specific
- Diameter client (e.g., access device), such as the Abort-Session-
- Request message, which is used to request that a particular user's
- session be terminated.
-
- Note that an agent can only forward a request to a host described in
- the Destination-Host AVP if the host in question is included in its
- peer table (see Section 2.6). Otherwise, the request is routed based
- on the Destination-Realm only (see Section 6.1.6).
-
- When a message is received, the message is processed in the following
- order:
-
- o If the message is destined for the local host, the procedures
- listed in Section 6.1.4 are followed.
-
- o If the message is intended for a Diameter peer with whom the local
- host is able to directly communicate, the procedures listed in
- Section 6.1.5 are followed. This is known as "Request
- Forwarding".
-
- o The procedure listed in Section 6.1.6 is followed, which is known
- as "Request Routing".
-
- o If none of the above are successful, an answer is returned with
- the Result-Code set to DIAMETER_UNABLE_TO_DELIVER, with the 'E'
- bit set.
-
- For routing of Diameter messages to work within an administrative
- domain, all Diameter nodes within the realm MUST be peers.
-
- The overview contained in this section (6.1) is intended to provide
- general guidelines to Diameter developers. Implementations are free
- to use different methods than the ones described here as long as they
- conform to the requirements specified in Sections 6.1.1 through
- 6.1.9. See Section 7 for more details on error handling.
-
-6.1.1. Originating a Request
-
- When creating a request, in addition to any other procedures
- described in the application definition for that specific request,
- the following procedures MUST be followed:
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 75]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o the Command Code is set to the appropriate value;
-
- o the 'R' bit is set;
-
- o the End-to-End Identifier is set to a locally unique value;
-
- o the Origin-Host and Origin-Realm AVPs MUST be set to the
- appropriate values, used to identify the source of the message;
- and
-
- o the Destination-Host and Destination-Realm AVPs MUST be set to the
- appropriate values, as described in Section 6.1.
-
-6.1.2. Sending a Request
-
- When sending a request, originated either locally or as the result of
- a forwarding or routing operation, the following procedures SHOULD be
- followed:
-
- o The Hop-by-Hop Identifier SHOULD be set to a locally unique value.
-
- o The message SHOULD be saved in the list of pending requests.
-
- Other actions to perform on the message based on the particular role
- the agent is playing are described in the following sections.
-
-6.1.3. Receiving Requests
-
- A relay or proxy agent MUST check for forwarding loops when receiving
- requests. A loop is detected if the server finds its own identity in
- a Route-Record AVP. When such an event occurs, the agent MUST answer
- with the Result-Code AVP set to DIAMETER_LOOP_DETECTED.
-
-6.1.4. Processing Local Requests
-
- A request is known to be for local consumption when one of the
- following conditions occurs:
-
- o The Destination-Host AVP contains the local host's identity;
-
- o The Destination-Host AVP is not present, the Destination-Realm AVP
- contains a realm the server is configured to process locally, and
- the Diameter application is locally supported; or
-
- o Both the Destination-Host and the Destination-Realm are not
- present.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 76]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- When a request is locally processed, the rules in Section 6.2 should
- be used to generate the corresponding answer.
-
-6.1.5. Request Forwarding
-
- Request forwarding is done using the Diameter peer table. The
- Diameter peer table contains all of the peers with which the local
- node is able to directly communicate.
-
- When a request is received, and the host encoded in the Destination-
- Host AVP is one that is present in the peer table, the message SHOULD
- be forwarded to the peer.
-
-6.1.6. Request Routing
-
- Diameter request message routing is done via realms and Application
- Ids. A Diameter message that may be forwarded by Diameter agents
- (proxies, redirect agents, or relay agents) MUST include the target
- realm in the Destination-Realm AVP. Request routing SHOULD rely on
- the Destination-Realm AVP and the Application Id present in the
- request message header to aid in the routing decision. The realm MAY
- be retrieved from the User-Name AVP, which is in the form of a
- Network Access Identifier (NAI). The realm portion of the NAI is
- inserted in the Destination-Realm AVP.
-
- Diameter agents MAY have a list of locally supported realms and
- applications, and they MAY have a list of externally supported realms
- and applications. When a request is received that includes a realm
- and/or application that is not locally supported, the message is
- routed to the peer configured in the routing table (see Section 2.7).
-
- Realm names and Application Ids are the minimum supported routing
- criteria, additional information may be needed to support redirect
- semantics.
-
-6.1.7. Predictive Loop Avoidance
-
- Before forwarding or routing a request, Diameter agents, in addition
- to performing the processing described in Section 6.1.3, SHOULD check
- for the presence of a candidate route's peer identity in any of the
- Route-Record AVPs. In the event of the agent detecting the presence
- of a candidate route's peer identity in a Route-Record AVP, the agent
- MUST ignore such a route for the Diameter request message and attempt
- alternate routes if any exist. In case all the candidate routes are
- eliminated by the above criteria, the agent SHOULD return a
- DIAMETER_UNABLE_TO_DELIVER message.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 77]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-6.1.8. Redirecting Requests
-
- When a redirect agent receives a request whose routing entry is set
- to REDIRECT, it MUST reply with an answer message with the 'E' bit
- set, while maintaining the Hop-by-Hop Identifier in the header, and
- include the Result-Code AVP to DIAMETER_REDIRECT_INDICATION. Each of
- the servers associated with the routing entry are added in a separate
- Redirect-Host AVP.
-
- +------------------+
- | Diameter |
- | Redirect Agent |
- +------------------+
- ^ | 2. command + 'E' bit
- 1. Request | | Result-Code =
- [email protected] | | DIAMETER_REDIRECT_INDICATION +
- | | Redirect-Host AVP(s)
- | v
- +-------------+ 3. Request +-------------+
- | example.com |------------->| example.net |
- | Relay | | Diameter |
- | Agent |&lt;-------------| Server |
- +-------------+ 4. Answer +-------------+
-
- Figure 5: Diameter Redirect Agent
-
- The receiver of an answer message with the 'E' bit set and the
- Result-Code AVP set to DIAMETER_REDIRECT_INDICATION uses the Hop-by-
- Hop Identifier in the Diameter header to identify the request in the
- pending message queue (see Section 5.5.4) that is to be redirected.
- If no transport connection exists with the new peer, one is created,
- and the request is sent directly to it.
-
- Multiple Redirect-Host AVPs are allowed. The receiver of the answer
- message with the 'E' bit set selects exactly one of these hosts as
- the destination of the redirected message.
-
- When the Redirect-Host-Usage AVP included in the answer message has a
- non-zero value, a route entry for the redirect indications is created
- and cached by the receiver. The redirect usage for such a route
- entry is set by the value of Redirect-Host-Usage AVP and the lifetime
- of the cached route entry is set by Redirect-Max-Cache-Time AVP
- value.
-
- It is possible that multiple redirect indications can create multiple
- cached route entries differing only in their redirect usage and the
- peer to forward messages to. As an example, two(2) route entries
- that are created by two(2) redirect indications results in two(2)
-
-
-
-Fajardo, et al. Standards Track [Page 78]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- cached routes for the same realm and Application Id. However, one
- has a redirect usage of ALL_SESSION, where matching requests will be
- forwarded to one peer; the other has a redirect usage of ALL_REALM,
- where request are forwarded to another peer. Therefore, an incoming
- request that matches the realm and Application Id of both routes will
- need additional resolution. In such a case, a routing precedence
- rule MUST be used against the redirect usage value to resolve the
- contention. The precedence rule can be found in Section 6.13.
-
-6.1.9. Relaying and Proxying Requests
-
- A relay or proxy agent MUST append a Route-Record AVP to all requests
- forwarded. The AVP contains the identity of the peer from which the
- request was received.
-
- The Hop-by-Hop Identifier in the request is saved and replaced with a
- locally unique value. The source of the request is also saved, which
- includes the IP address, port, and protocol.
-
- A relay or proxy agent MAY include the Proxy-Info AVP in requests if
- it requires access to any local state information when the
- corresponding response is received. The Proxy-Info AVP has security
- implications as state information is distributed to other entities.
- As such, it is RECOMMENDED that the content of the Proxy-Info AVP be
- protected with cryptographic mechanisms, for example, by using a
- keyed message digest such as HMAC-SHA1 [RFC2104]. Such a mechanism,
- however, requires the management of keys, although only locally at
- the Diameter server. Still, a full description of the management of
- the keys used to protect the Proxy-Info AVP is beyond the scope of
- this document. Below is a list of common recommendations:
-
- o The keys should be generated securely following the randomness
- recommendations in [RFC4086].
-
- o The keys and cryptographic protection algorithms should be at
- least 128 bits in strength.
-
- o The keys should not be used for any other purpose than generating
- and verifying instances of the Proxy-Info AVP.
-
- o The keys should be changed regularly.
-
- o The keys should be changed if the AVP format or cryptographic
- protection algorithms change.
-
- The message is then forwarded to the next hop, as identified in the
- routing table.
-
-
-
-
-Fajardo, et al. Standards Track [Page 79]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Figure 6 provides an example of message routing using the procedures
- listed in these sections.
-
- (Origin-Host=nas.example.net) (Origin-Host=nas.example.net)
- (Origin-Realm=example.net) (Origin-Realm=example.net)
- (Destination-Realm=example.com) (Destination-Realm=example.com)
- (Route-Record=nas.example.net)
- +------+ ------> +------+ ------> +------+
- | | (Request) | | (Request) | |
- | NAS +-------------------+ DRL +-------------------+ HMS |
- | | | | | |
- +------+ &lt;------ +------+ &lt;------ +------+
- example.net (Answer) example.net (Answer) example.com
- (Origin-Host=hms.example.com) (Origin-Host=hms.example.com)
- (Origin-Realm=example.com) (Origin-Realm=example.com)
-
- Figure 6: Routing of Diameter messages
-
- Relay and proxy agents are not required to perform full inspection of
- incoming messages. At a minimum, validation of the message header
- and relevant routing AVPs has to be done when relaying messages.
- Proxy agents may optionally perform more in-depth message validation
- for applications in which it is interested.
-
-6.2. Diameter Answer Processing
-
- When a request is locally processed, the following procedures MUST be
- applied to create the associated answer, in addition to any
- additional procedures that MAY be discussed in the Diameter
- application defining the command:
-
- o The same Hop-by-Hop Identifier in the request is used in the
- answer.
-
- o The local host's identity is encoded in the Origin-Host AVP.
-
- o The Destination-Host and Destination-Realm AVPs MUST NOT be
- present in the answer message.
-
- o The Result-Code AVP is added with its value indicating success or
- failure.
-
- o If the Session-Id is present in the request, it MUST be included
- in the answer.
-
- o Any Proxy-Info AVPs in the request MUST be added to the answer
- message, in the same order they were present in the request.
-
-
-
-
-Fajardo, et al. Standards Track [Page 80]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o The 'P' bit is set to the same value as the one in the request.
-
- o The same End-to-End identifier in the request is used in the
- answer.
-
- Note that the error messages (see Section 7) are also subjected to
- the above processing rules.
-
-6.2.1. Processing Received Answers
-
- A Diameter client or proxy MUST match the Hop-by-Hop Identifier in an
- answer received against the list of pending requests. The
- corresponding message should be removed from the list of pending
- requests. It SHOULD ignore answers received that do not match a
- known Hop-by-Hop Identifier.
-
-6.2.2. Relaying and Proxying Answers
-
- If the answer is for a request that was proxied or relayed, the agent
- MUST restore the original value of the Diameter header's Hop-by-Hop
- Identifier field.
-
- If the last Proxy-Info AVP in the message is targeted to the local
- Diameter server, the AVP MUST be removed before the answer is
- forwarded.
-
- If a relay or proxy agent receives an answer with a Result-Code AVP
- indicating a failure, it MUST NOT modify the contents of the AVP.
- Any additional local errors detected SHOULD be logged but not
- reflected in the Result-Code AVP. If the agent receives an answer
- message with a Result-Code AVP indicating success, and it wishes to
- modify the AVP to indicate an error, it MUST modify the Result-Code
- AVP to contain the appropriate error in the message destined towards
- the access device as well as include the Error-Reporting-Host AVP; it
- MUST also issue an STR on behalf of the access device towards the
- Diameter server.
-
- The agent MUST then send the answer to the host that it received the
- original request from.
-
-6.3. Origin-Host AVP
-
- The Origin-Host AVP (AVP Code 264) is of type DiameterIdentity, and
- it MUST be present in all Diameter messages. This AVP identifies the
- endpoint that originated the Diameter message. Relay agents MUST NOT
- modify this AVP.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 81]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The value of the Origin-Host AVP is guaranteed to be unique within a
- single host.
-
- Note that the Origin-Host AVP may resolve to more than one address as
- the Diameter peer may support more than one address.
-
- This AVP SHOULD be placed as close to the Diameter header as
- possible.
-
-6.4. Origin-Realm AVP
-
- The Origin-Realm AVP (AVP Code 296) is of type DiameterIdentity.
- This AVP contains the Realm of the originator of any Diameter message
- and MUST be present in all messages.
-
- This AVP SHOULD be placed as close to the Diameter header as
- possible.
-
-6.5. Destination-Host AVP
-
- The Destination-Host AVP (AVP Code 293) is of type DiameterIdentity.
- This AVP MUST be present in all unsolicited agent initiated messages,
- MAY be present in request messages, and MUST NOT be present in answer
- messages.
-
- The absence of the Destination-Host AVP will cause a message to be
- sent to any Diameter server supporting the application within the
- realm specified in Destination-Realm AVP.
-
- This AVP SHOULD be placed as close to the Diameter header as
- possible.
-
-6.6. Destination-Realm AVP
-
- The Destination-Realm AVP (AVP Code 283) is of type DiameterIdentity
- and contains the realm to which the message is to be routed. The
- Destination-Realm AVP MUST NOT be present in answer messages.
- Diameter clients insert the realm portion of the User-Name AVP.
- Diameter servers initiating a request message use the value of the
- Origin-Realm AVP from a previous message received from the intended
- target host (unless it is known a priori). When present, the
- Destination-Realm AVP is used to perform message routing decisions.
-
- The CCF for a request message that includes the Destination-Realm AVP
- SHOULD list the Destination-Realm AVP as a required AVP (an AVP
- indicated as {AVP}); otherwise, the message is inherently a non-
- routable message.
-
-
-
-
-Fajardo, et al. Standards Track [Page 82]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- This AVP SHOULD be placed as close to the Diameter header as
- possible.
-
-6.7. Routing AVPs
-
- The AVPs defined in this section are Diameter AVPs used for routing
- purposes. These AVPs change as Diameter messages are processed by
- agents.
-
-6.7.1. Route-Record AVP
-
- The Route-Record AVP (AVP Code 282) is of type DiameterIdentity. The
- identity added in this AVP MUST be the same as the one received in
- the Origin-Host of the Capabilities Exchange message.
-
-6.7.2. Proxy-Info AVP
-
- The Proxy-Info AVP (AVP Code 284) is of type Grouped. This AVP
- contains the identity and local state information of the Diameter
- node that creates and adds it to a message. The Grouped Data field
- has the following CCF grammar:
-
- Proxy-Info ::= &lt; AVP Header: 284 >
- { Proxy-Host }
- { Proxy-State }
- * [ AVP ]
-
-6.7.3. Proxy-Host AVP
-
- The Proxy-Host AVP (AVP Code 280) is of type DiameterIdentity. This
- AVP contains the identity of the host that added the Proxy-Info AVP.
-
-6.7.4. Proxy-State AVP
-
- The Proxy-State AVP (AVP Code 33) is of type OctetString. It
- contains state information that would otherwise be stored at the
- Diameter entity that created it. As such, this AVP MUST be treated
- as opaque data by other Diameter entities.
-
-6.8. Auth-Application-Id AVP
-
- The Auth-Application-Id AVP (AVP Code 258) is of type Unsigned32 and
- is used in order to advertise support of the Authentication and
- Authorization portion of an application (see Section 2.4). If
- present in a message other than CER and CEA, the value of the Auth-
- Application-Id AVP MUST match the Application Id present in the
- Diameter message header.
-
-
-
-
-Fajardo, et al. Standards Track [Page 83]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-6.9. Acct-Application-Id AVP
-
- The Acct-Application-Id AVP (AVP Code 259) is of type Unsigned32 and
- is used in order to advertise support of the accounting portion of an
- application (see Section 2.4). If present in a message other than
- CER and CEA, the value of the Acct-Application-Id AVP MUST match the
- Application Id present in the Diameter message header.
-
-6.10. Inband-Security-Id AVP
-
- The Inband-Security-Id AVP (AVP Code 299) is of type Unsigned32 and
- is used in order to advertise support of the security portion of the
- application. The use of this AVP in CER and CEA messages is NOT
- RECOMMENDED. Instead, discovery of a Diameter entity's security
- capabilities can be done either through static configuration or via
- Diameter Peer Discovery as described in Section 5.2.
-
- The following values are supported:
-
-
- NO_INBAND_SECURITY 0
-
- This peer does not support TLS/TCP and DTLS/SCTP. This is the
- default value, if the AVP is omitted.
-
- TLS 1
-
- This node supports TLS/TCP [RFC5246] and DTLS/SCTP [RFC6083]
- security.
-
-6.11. Vendor-Specific-Application-Id AVP
-
- The Vendor-Specific-Application-Id AVP (AVP Code 260) is of type
- Grouped and is used to advertise support of a vendor-specific
- Diameter application. Exactly one instance of either Auth-
- Application-Id or Acct-Application-Id AVP MUST be present. The
- Application Id carried by either Auth-Application-Id or Acct-
- Application-Id AVP MUST comply with vendor-specific Application Id
- assignment described in Section 11.3. It MUST also match the
- Application Id present in the Diameter header except when used in a
- CER or CEA message.
-
- The Vendor-Id AVP is an informational AVP pertaining to the vendor
- who may have authorship of the vendor-specific Diameter application.
- It MUST NOT be used as a means of defining a completely separate
- vendor-specific Application Id space.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 84]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The Vendor-Specific-Application-Id AVP SHOULD be placed as close to
- the Diameter header as possible.
-
- AVP Format
-
- &lt;Vendor-Specific-Application-Id> ::= &lt; AVP Header: 260 >
- { Vendor-Id }
- [ Auth-Application-Id ]
- [ Acct-Application-Id ]
-
- A Vendor-Specific-Application-Id AVP MUST contain exactly one of
- either Auth-Application-Id or Acct-Application-Id. If a Vendor-
- Specific-Application-Id is received without one of these two AVPs,
- then the recipient SHOULD issue an answer with a Result-Code set to
- DIAMETER_MISSING_AVP. The answer SHOULD also include a Failed-AVP,
- which MUST contain an example of an Auth-Application-Id AVP and an
- Acct-Application-Id AVP.
-
- If a Vendor-Specific-Application-Id is received that contains both
- Auth-Application-Id and Acct-Application-Id, then the recipient MUST
- issue an answer with Result-Code set to
- DIAMETER_AVP_OCCURS_TOO_MANY_TIMES. The answer MUST also include a
- Failed-AVP, which MUST contain the received Auth-Application-Id AVP
- and Acct-Application-Id AVP.
-
-6.12. Redirect-Host AVP
-
- The Redirect-Host AVP (AVP Code 292) is of type DiameterURI. One or
- more instances of this AVP MUST be present if the answer message's
- 'E' bit is set and the Result-Code AVP is set to
- DIAMETER_REDIRECT_INDICATION.
-
- Upon receiving the above, the receiving Diameter node SHOULD forward
- the request directly to one of the hosts identified in these AVPs.
- The server contained in the selected Redirect-Host AVP SHOULD be used
- for all messages matching the criteria set by the Redirect-Host-Usage
- AVP.
-
-6.13. Redirect-Host-Usage AVP
-
- The Redirect-Host-Usage AVP (AVP Code 261) is of type Enumerated.
- This AVP MAY be present in answer messages whose 'E' bit is set and
- the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION.
-
- When present, this AVP provides hints about how the routing entry
- resulting from the Redirect-Host is to be used. The following values
- are supported:
-
-
-
-
-Fajardo, et al. Standards Track [Page 85]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DONT_CACHE 0
-
- The host specified in the Redirect-Host AVP SHOULD NOT be cached.
- This is the default value.
-
- ALL_SESSION 1
-
- All messages within the same session, as defined by the same value
- of the Session-ID AVP SHOULD be sent to the host specified in the
- Redirect-Host AVP.
-
- ALL_REALM 2
-
- All messages destined for the realm requested SHOULD be sent to
- the host specified in the Redirect-Host AVP.
-
- REALM_AND_APPLICATION 3
-
- All messages for the application requested to the realm specified
- SHOULD be sent to the host specified in the Redirect-Host AVP.
-
- ALL_APPLICATION 4
-
- All messages for the application requested SHOULD be sent to the
- host specified in the Redirect-Host AVP.
-
- ALL_HOST 5
-
- All messages that would be sent to the host that generated the
- Redirect-Host SHOULD be sent to the host specified in the
- Redirect-Host AVP.
-
- ALL_USER 6
-
- All messages for the user requested SHOULD be sent to the host
- specified in the Redirect-Host AVP.
-
- When multiple cached routes are created by redirect indications and
- they differ only in redirect usage and peers to forward requests to
- (see Section 6.1.8), a precedence rule MUST be applied to the
- redirect usage values of the cached routes during normal routing to
- resolve contentions that may occur. The precedence rule is the order
- that dictate which redirect usage should be considered before any
- other as they appear. The order is as follows:
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 86]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- 1. ALL_SESSION
-
- 2. ALL_USER
-
- 3. REALM_AND_APPLICATION
-
- 4. ALL_REALM
-
- 5. ALL_APPLICATION
-
- 6. ALL_HOST
-
-6.14. Redirect-Max-Cache-Time AVP
-
- The Redirect-Max-Cache-Time AVP (AVP Code 262) is of type Unsigned32.
- This AVP MUST be present in answer messages whose 'E' bit is set,
- whose Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION, and
- whose Redirect-Host-Usage AVP set to a non-zero value.
-
- This AVP contains the maximum number of seconds the peer and route
- table entries, created as a result of the Redirect-Host, SHOULD be
- cached. Note that once a host is no longer reachable, any associated
- cache, peer, and routing table entries MUST be deleted.
-
-7. Error Handling
-
- There are two different types of errors in Diameter; protocol errors
- and application errors. A protocol error is one that occurs at the
- base protocol level and MAY require per-hop attention (e.g., a
- message routing error). Application errors, on the other hand,
- generally occur due to a problem with a function specified in a
- Diameter application (e.g., user authentication, missing AVP).
-
- Result-Code AVP values that are used to report protocol errors MUST
- only be present in answer messages whose 'E' bit is set. When a
- request message is received that causes a protocol error, an answer
- message is returned with the 'E' bit set, and the Result-Code AVP is
- set to the appropriate protocol error value. As the answer is sent
- back towards the originator of the request, each proxy or relay agent
- MAY take action on the message.
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 87]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- 1. Request +---------+ Link Broken
- +-------------------------->|Diameter |----///----+
- | +---------------------| | v
- +------+--+ | 2. answer + 'E' set | Relay 2 | +--------+
- |Diameter |&lt;-+ (Unable to Forward) +---------+ |Diameter|
- | | | Home |
- | Relay 1 |--+ +---------+ | Server |
- +---------+ | 3. Request |Diameter | +--------+
- +-------------------->| | ^
- | Relay 3 |-----------+
- +---------+
-
- Figure 7: Example of Protocol Error Causing Answer Message
-
- Figure 7 provides an example of a message forwarded upstream by a
- Diameter relay. When the message is received by Relay 2, and it
- detects that it cannot forward the request to the home server, an
- answer message is returned with the 'E' bit set and the Result-Code
- AVP set to DIAMETER_UNABLE_TO_DELIVER. Given that this error falls
- within the protocol error category, Relay 1 would take special
- action, and given the error, attempt to route the message through its
- alternate Relay 3.
-
- +---------+ 1. Request +---------+ 2. Request +---------+
- | Access |------------>|Diameter |------------>|Diameter |
- | | | | | Home |
- | Device |&lt;------------| Relay |&lt;------------| Server |
- +---------+ 4. Answer +---------+ 3. Answer +---------+
- (Missing AVP) (Missing AVP)
-
- Figure 8: Example of Application Error Answer Message
-
- Figure 8 provides an example of a Diameter message that caused an
- application error. When application errors occur, the Diameter
- entity reporting the error clears the 'R' bit in the Command Flags
- and adds the Result-Code AVP with the proper value. Application
- errors do not require any proxy or relay agent involvement;
- therefore, the message would be forwarded back to the originator of
- the request.
-
- In the case where the answer message itself contains errors, any
- related session SHOULD be terminated by sending an STR or ASR
- message. The Termination-Cause AVP in the STR MAY be filled with the
- appropriate value to indicate the cause of the error. An application
- MAY also send an application-specific request instead of an STR or
- ASR message to signal the error in the case where no state is
- maintained or to allow for some form of error recovery with the
- corresponding Diameter entity.
-
-
-
-Fajardo, et al. Standards Track [Page 88]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- There are certain Result-Code AVP application errors that require
- additional AVPs to be present in the answer. In these cases, the
- Diameter node that sets the Result-Code AVP to indicate the error
- MUST add the AVPs. Examples are as follows:
-
- o A request with an unrecognized AVP is received with the 'M' bit
- (Mandatory bit) set causes an answer to be sent with the Result-
- Code AVP set to DIAMETER_AVP_UNSUPPORTED and the Failed-AVP AVP
- containing the offending AVP.
-
- o A request with an AVP that is received with an unrecognized value
- causes an answer to be returned with the Result-Code AVP set to
- DIAMETER_INVALID_AVP_VALUE, with the Failed-AVP AVP containing the
- AVP causing the error.
-
- o A received command that is missing AVPs that are defined as
- required in the commands CCF; examples are AVPs indicated as
- {AVP}. The receiver issues an answer with the Result-Code set to
- DIAMETER_MISSING_AVP and creates an AVP with the AVP Code and
- other fields set as expected in the missing AVP. The created AVP
- is then added to the Failed-AVP AVP.
-
- The Result-Code AVP describes the error that the Diameter node
- encountered in its processing. In case there are multiple errors,
- the Diameter node MUST report only the first error it encountered
- (detected possibly in some implementation-dependent order). The
- specific errors that can be described by this AVP are described in
- the following section.
-
-7.1. Result-Code AVP
-
- The Result-Code AVP (AVP Code 268) is of type Unsigned32 and
- indicates whether a particular request was completed successfully or
- an error occurred. All Diameter answer messages in IETF-defined
- Diameter application specifications MUST include one Result-Code AVP.
- A non-successful Result-Code AVP (one containing a non-2xxx value
- other than DIAMETER_REDIRECT_INDICATION) MUST include the Error-
- Reporting-Host AVP if the host setting the Result-Code AVP is
- different from the identity encoded in the Origin-Host AVP.
-
- The Result-Code data field contains an IANA-managed 32-bit address
- space representing errors (see Section 11.3.2). Diameter provides
- the following classes of errors, all identified by the thousands
- digit in the decimal notation:
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 89]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o 1xxx (Informational)
-
- o 2xxx (Success)
-
- o 3xxx (Protocol Errors)
-
- o 4xxx (Transient Failures)
-
- o 5xxx (Permanent Failure)
-
- An unrecognized class (one whose first digit is not defined in this
- section) MUST be handled as a permanent failure.
-
-7.1.1. Informational
-
- Errors that fall within this category are used to inform the
- requester that a request could not be satisfied, and additional
- action is required on its part before access is granted.
-
- DIAMETER_MULTI_ROUND_AUTH 1001
-
- This informational error is returned by a Diameter server to
- inform the access device that the authentication mechanism being
- used requires multiple round trips, and a subsequent request needs
- to be issued in order for access to be granted.
-
-7.1.2. Success
-
- Errors that fall within the Success category are used to inform a
- peer that a request has been successfully completed.
-
- DIAMETER_SUCCESS 2001
-
- The request was successfully completed.
-
- DIAMETER_LIMITED_SUCCESS 2002
-
- When returned, the request was successfully completed, but
- additional processing is required by the application in order to
- provide service to the user.
-
-7.1.3. Protocol Errors
-
- Errors that fall within the Protocol Error category SHOULD be treated
- on a per-hop basis, and Diameter proxies MAY attempt to correct the
- error, if it is possible. Note that these errors MUST only be used
- in answer messages whose 'E' bit is set.
-
-
-
-
-Fajardo, et al. Standards Track [Page 90]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DIAMETER_COMMAND_UNSUPPORTED 3001
-
- This error code is used when a Diameter entity receives a message
- with a Command Code that it does not support.
-
- DIAMETER_UNABLE_TO_DELIVER 3002
-
- This error is given when Diameter cannot deliver the message to
- the destination, either because no host within the realm
- supporting the required application was available to process the
- request or because the Destination-Host AVP was given without the
- associated Destination-Realm AVP.
-
- DIAMETER_REALM_NOT_SERVED 3003
-
- The intended realm of the request is not recognized.
-
- DIAMETER_TOO_BUSY 3004
-
- When returned, a Diameter node SHOULD attempt to send the message
- to an alternate peer. This error MUST only be used when a
- specific server is requested, and it cannot provide the requested
- service.
-
- DIAMETER_LOOP_DETECTED 3005
-
- An agent detected a loop while trying to get the message to the
- intended recipient. The message MAY be sent to an alternate peer,
- if one is available, but the peer reporting the error has
- identified a configuration problem.
-
- DIAMETER_REDIRECT_INDICATION 3006
-
- A redirect agent has determined that the request could not be
- satisfied locally, and the initiator of the request SHOULD direct
- the request directly to the server, whose contact information has
- been added to the response. When set, the Redirect-Host AVP MUST
- be present.
-
- DIAMETER_APPLICATION_UNSUPPORTED 3007
-
- A request was sent for an application that is not supported.
-
- DIAMETER_INVALID_HDR_BITS 3008
-
- A request was received whose bits in the Diameter header were set
- either to an invalid combination or to a value that is
- inconsistent with the Command Code's definition.
-
-
-
-Fajardo, et al. Standards Track [Page 91]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DIAMETER_INVALID_AVP_BITS 3009
-
- A request was received that included an AVP whose flag bits are
- set to an unrecognized value or that is inconsistent with the
- AVP's definition.
-
- DIAMETER_UNKNOWN_PEER 3010
-
- A CER was received from an unknown peer.
-
-7.1.4. Transient Failures
-
- Errors that fall within the transient failures category are used to
- inform a peer that the request could not be satisfied at the time it
- was received but MAY be able to satisfy the request in the future.
- Note that these errors MUST be used in answer messages whose 'E' bit
- is not set.
-
- DIAMETER_AUTHENTICATION_REJECTED 4001
-
- The authentication process for the user failed, most likely due to
- an invalid password used by the user. Further attempts MUST only
- be tried after prompting the user for a new password.
-
- DIAMETER_OUT_OF_SPACE 4002
-
- A Diameter node received the accounting request but was unable to
- commit it to stable storage due to a temporary lack of space.
-
- ELECTION_LOST 4003
-
- The peer has determined that it has lost the election process and
- has therefore disconnected the transport connection.
-
-7.1.5. Permanent Failures
-
- Errors that fall within the permanent failures category are used to
- inform the peer that the request failed and should not be attempted
- again. Note that these errors SHOULD be used in answer messages
- whose 'E' bit is not set. In error conditions where it is not
- possible or efficient to compose application-specific answer grammar,
- answer messages with the 'E' bit set and which comply to the grammar
- described in Section 7.2 MAY also be used for permanent errors.
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 92]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DIAMETER_AVP_UNSUPPORTED 5001
-
- The peer received a message that contained an AVP that is not
- recognized or supported and was marked with the 'M' (Mandatory)
- bit. A Diameter message with this error MUST contain one or more
- Failed-AVP AVPs containing the AVPs that caused the failure.
-
- DIAMETER_UNKNOWN_SESSION_ID 5002
-
- The request contained an unknown Session-Id.
-
- DIAMETER_AUTHORIZATION_REJECTED 5003
-
- A request was received for which the user could not be authorized.
- This error could occur if the service requested is not permitted
- to the user.
-
- DIAMETER_INVALID_AVP_VALUE 5004
-
- The request contained an AVP with an invalid value in its data
- portion. A Diameter message indicating this error MUST include
- the offending AVPs within a Failed-AVP AVP.
-
- DIAMETER_MISSING_AVP 5005
-
- The request did not contain an AVP that is required by the Command
- Code definition. If this value is sent in the Result-Code AVP, a
- Failed-AVP AVP SHOULD be included in the message. The Failed-AVP
- AVP MUST contain an example of the missing AVP complete with the
- Vendor-Id if applicable. The value field of the missing AVP
- should be of correct minimum length and contain zeroes.
-
- DIAMETER_RESOURCES_EXCEEDED 5006
-
- A request was received that cannot be authorized because the user
- has already expended allowed resources. An example of this error
- condition is when a user that is restricted to one dial-up PPP
- port attempts to establish a second PPP connection.
-
- DIAMETER_CONTRADICTING_AVPS 5007
-
- The Home Diameter server has detected AVPs in the request that
- contradicted each other, and it is not willing to provide service
- to the user. The Failed-AVP AVP MUST be present, which contain
- the AVPs that contradicted each other.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 93]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- DIAMETER_AVP_NOT_ALLOWED 5008
-
- A message was received with an AVP that MUST NOT be present. The
- Failed-AVP AVP MUST be included and contain a copy of the
- offending AVP.
-
- DIAMETER_AVP_OCCURS_TOO_MANY_TIMES 5009
-
- A message was received that included an AVP that appeared more
- often than permitted in the message definition. The Failed-AVP
- AVP MUST be included and contain a copy of the first instance of
- the offending AVP that exceeded the maximum number of occurrences.
-
- DIAMETER_NO_COMMON_APPLICATION 5010
-
- This error is returned by a Diameter node that receives a CER
- whereby no applications are common between the CER sending peer
- and the CER receiving peer.
-
- DIAMETER_UNSUPPORTED_VERSION 5011
-
- This error is returned when a request was received, whose version
- number is unsupported.
-
- DIAMETER_UNABLE_TO_COMPLY 5012
-
- This error is returned when a request is rejected for unspecified
- reasons.
-
- DIAMETER_INVALID_BIT_IN_HEADER 5013
-
- This error is returned when a reserved bit in the Diameter header
- is set to one (1) or the bits in the Diameter header are set
- incorrectly.
-
- DIAMETER_INVALID_AVP_LENGTH 5014
-
- The request contained an AVP with an invalid length. A Diameter
- message indicating this error MUST include the offending AVPs
- within a Failed-AVP AVP. In cases where the erroneous AVP length
- value exceeds the message length or is less than the minimum AVP
- header length, it is sufficient to include the offending AVP
- header and a zero filled payload of the minimum required length
- for the payloads data type. If the AVP is a Grouped AVP, the
- Grouped AVP header with an empty payload would be sufficient to
- indicate the offending AVP. In the case where the offending AVP
- header cannot be fully decoded when the AVP length is less than
-
-
-
-
-Fajardo, et al. Standards Track [Page 94]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- the minimum AVP header length, it is sufficient to include an
- offending AVP header that is formulated by padding the incomplete
- AVP header with zero up to the minimum AVP header length.
-
- DIAMETER_INVALID_MESSAGE_LENGTH 5015
-
- This error is returned when a request is received with an invalid
- message length.
-
- DIAMETER_INVALID_AVP_BIT_COMBO 5016
-
- The request contained an AVP with which is not allowed to have the
- given value in the AVP Flags field. A Diameter message indicating
- this error MUST include the offending AVPs within a Failed-AVP
- AVP.
-
- DIAMETER_NO_COMMON_SECURITY 5017
-
- This error is returned when a CER message is received, and there
- are no common security mechanisms supported between the peers. A
- Capabilities-Exchange-Answer (CEA) message MUST be returned with
- the Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY.
-
-7.2. Error Bit
-
- The 'E' (Error Bit) in the Diameter header is set when the request
- caused a protocol-related error (see Section 7.1.3). A message with
- the 'E' bit MUST NOT be sent as a response to an answer message.
- Note that a message with the 'E' bit set is still subjected to the
- processing rules defined in Section 6.2. When set, the answer
- message will not conform to the CCF specification for the command;
- instead, it and will conform to the following CCF:
-
- Message Format
-
- &lt;answer-message> ::= &lt; Diameter Header: code, ERR [, PXY] >
- 0*1&lt; Session-Id >
- { Origin-Host }
- { Origin-Realm }
- { Result-Code }
- [ Origin-State-Id ]
- [ Error-Message ]
- [ Error-Reporting-Host ]
- [ Failed-AVP ]
- [ Experimental-Result ]
- * [ Proxy-Info ]
- * [ AVP ]
-
-
-
-
-Fajardo, et al. Standards Track [Page 95]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Note that the code used in the header is the same than the one found
- in the request message, but with the 'R' bit cleared and the 'E' bit
- set. The 'P' bit in the header is set to the same value as the one
- found in the request message.
-
-7.3. Error-Message AVP
-
- The Error-Message AVP (AVP Code 281) is of type UTF8String. It MAY
- accompany a Result-Code AVP as a human-readable error message. The
- Error-Message AVP is not intended to be useful in an environment
- where error messages are processed automatically. It SHOULD NOT be
- expected that the content of this AVP be parsed by network entities.
-
-7.4. Error-Reporting-Host AVP
-
- The Error-Reporting-Host AVP (AVP Code 294) is of type
- DiameterIdentity. This AVP contains the identity of the Diameter
- host that sent the Result-Code AVP to a value other than 2001
- (Success), only if the host setting the Result-Code is different from
- the one encoded in the Origin-Host AVP. This AVP is intended to be
- used for troubleshooting purposes, and it MUST be set when the
- Result-Code AVP indicates a failure.
-
-7.5. Failed-AVP AVP
-
- The Failed-AVP AVP (AVP Code 279) is of type Grouped and provides
- debugging information in cases where a request is rejected or not
- fully processed due to erroneous information in a specific AVP. The
- value of the Result-Code AVP will provide information on the reason
- for the Failed-AVP AVP. A Diameter answer message SHOULD contain an
- instance of the Failed-AVP AVP that corresponds to the error
- indicated by the Result-Code AVP. For practical purposes, this
- Failed-AVP would typically refer to the first AVP processing error
- that a Diameter node encounters.
-
- The possible reasons for this AVP are the presence of an improperly
- constructed AVP, an unsupported or unrecognized AVP, an invalid AVP
- value, the omission of a required AVP, the presence of an explicitly
- excluded AVP (see tables in Section 10) or the presence of two or
- more occurrences of an AVP that is restricted to 0, 1, or 0-1
- occurrences.
-
- A Diameter message SHOULD contain one Failed-AVP AVP, containing the
- entire AVP that could not be processed successfully. If the failure
- reason is omission of a required AVP, an AVP with the missing AVP
- code, the missing Vendor-Id, and a zero-filled payload of the minimum
- required length for the omitted AVP will be added. If the failure
- reason is an invalid AVP length where the reported length is less
-
-
-
-Fajardo, et al. Standards Track [Page 96]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- than the minimum AVP header length or greater than the reported
- message length, a copy of the offending AVP header and a zero-filled
- payload of the minimum required length SHOULD be added.
-
- In the case where the offending AVP is embedded within a Grouped AVP,
- the Failed-AVP MAY contain the grouped AVP, which in turn contains
- the single offending AVP. The same method MAY be employed if the
- grouped AVP itself is embedded in yet another grouped AVP and so on.
- In this case, the Failed-AVP MAY contain the grouped AVP hierarchy up
- to the single offending AVP. This enables the recipient to detect
- the location of the offending AVP when embedded in a group.
-
- AVP Format
-
- &lt;Failed-AVP> ::= &lt; AVP Header: 279 >
- 1* {AVP}
-
-7.6. Experimental-Result AVP
-
- The Experimental-Result AVP (AVP Code 297) is of type Grouped, and
- indicates whether a particular vendor-specific request was completed
- successfully or whether an error occurred. This AVP has the
- following structure:
-
- AVP Format
-
- Experimental-Result ::= &lt; AVP Header: 297 >
- { Vendor-Id }
- { Experimental-Result-Code }
-
- The Vendor-Id AVP (see Section 5.3.3) in this grouped AVP identifies
- the vendor responsible for the assignment of the result code that
- follows. All Diameter answer messages defined in vendor-specific
- applications MUST include either one Result-Code AVP or one
- Experimental-Result AVP.
-
-7.7. Experimental-Result-Code AVP
-
- The Experimental-Result-Code AVP (AVP Code 298) is of type Unsigned32
- and contains a vendor-assigned value representing the result of
- processing the request.
-
- It is recommended that vendor-specific result codes follow the same
- conventions given for the Result-Code AVP regarding the different
- types of result codes and the handling of errors (for non-2xxx
- values).
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 97]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-8. Diameter User Sessions
-
- In general, Diameter can provide two different types of services to
- applications. The first involves authentication and authorization,
- and it can optionally make use of accounting. The second only makes
- use of accounting.
-
- When a service makes use of the authentication and/or authorization
- portion of an application, and a user requests access to the network,
- the Diameter client issues an auth request to its local server. The
- auth request is defined in a service-specific Diameter application
- (e.g., NASREQ). The request contains a Session-Id AVP, which is used
- in subsequent messages (e.g., subsequent authorization, accounting,
- etc.) relating to the user's session. The Session-Id AVP is a means
- for the client and servers to correlate a Diameter message with a
- user session.
-
- When a Diameter server authorizes a user to implement network
- resources for a finite amount of time, and it is willing to extend
- the authorization via a future request, it MUST add the
- Authorization- Lifetime AVP to the answer message. The
- Authorization-Lifetime AVP defines the maximum number of seconds a
- user MAY make use of the resources before another authorization
- request is expected by the server. The Auth-Grace-Period AVP
- contains the number of seconds following the expiration of the
- Authorization-Lifetime, after which the server will release all state
- information related to the user's session. Note that if payment for
- services is expected by the serving realm from the user's home realm,
- the Authorization-Lifetime AVP, combined with the Auth-Grace-Period
- AVP, implies the maximum length of the session for which the home
- realm is willing to be fiscally responsible. Services provided past
- the expiration of the Authorization-Lifetime and Auth-Grace-Period
- AVPs are the responsibility of the access device. Of course, the
- actual cost of services rendered is clearly outside the scope of the
- protocol.
-
- An access device that does not expect to send a re-authorization or a
- session termination request to the server MAY include the Auth-
- Session-State AVP with the value set to NO_STATE_MAINTAINED as a hint
- to the server. If the server accepts the hint, it agrees that since
- no session termination message will be received once service to the
- user is terminated, it cannot maintain state for the session. If the
- answer message from the server contains a different value in the
- Auth-Session-State AVP (or the default value if the AVP is absent),
- the access device MUST follow the server's directives. Note that the
- value NO_STATE_MAINTAINED MUST NOT be set in subsequent re-
- authorization requests and answers.
-
-
-
-
-Fajardo, et al. Standards Track [Page 98]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The base protocol does not include any authorization request
- messages, since these are largely application-specific and are
- defined in a Diameter application document. However, the base
- protocol does define a set of messages that are used to terminate
- user sessions. These are used to allow servers that maintain state
- information to free resources.
-
- When a service only makes use of the accounting portion of the
- Diameter protocol, even in combination with an application, the
- Session-Id is still used to identify user sessions. However, the
- session termination messages are not used, since a session is
- signaled as being terminated by issuing an accounting stop message.
-
- Diameter may also be used for services that cannot be easily
- categorized as authentication, authorization, or accounting (e.g.,
- certain Third Generation Partnership Project Internet Multimedia
- System (3GPP IMS) interfaces). In such cases, the finite state
- machine defined in subsequent sections may not be applicable.
- Therefore, the application itself MAY need to define its own finite
- state machine. However, such application-specific state machines
- SHOULD follow the general state machine framework outlined in this
- document such as the use of Session-Id AVPs and the use of STR/STA,
- ASR/ASA messages for stateful sessions.
-
-8.1. Authorization Session State Machine
-
- This section contains a set of finite state machines, which represent
- the life cycle of Diameter sessions and which MUST be observed by all
- Diameter implementations that make use of the authentication and/or
- authorization portion of a Diameter application. The term "Service-
- Specific" below refers to a message defined in a Diameter application
- (e.g., Mobile IPv4, NASREQ).
-
- There are four different authorization session state machines
- supported in the Diameter base protocol. The first two describe a
- session in which the server is maintaining session state, indicated
- by the value of the Auth-Session-State AVP (or its absence). One
- describes the session from a client perspective, the other from a
- server perspective. The second two state machines are used when the
- server does not maintain session state. Here again, one describes
- the session from a client perspective, the other from a server
- perspective.
-
- When a session is moved to the Idle state, any resources that were
- allocated for the particular session must be released. Any event not
- listed in the state machines MUST be considered an error condition,
- and an answer, if applicable, MUST be returned to the originator of
- the message.
-
-
-
-Fajardo, et al. Standards Track [Page 99]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- In the case that an application does not support re-auth, the state
- transitions related to server-initiated re-auth, when both client and
- server sessions maintain state (e.g., Send RAR, Pending, Receive
- RAA), MAY be ignored.
-
- In the state table, the event "Failure to send X" means that the
- Diameter agent is unable to send command X to the desired
- destination. This could be due to the peer being down or due to the
- peer sending back a transient failure or temporary protocol error
- notification DIAMETER_TOO_BUSY or DIAMETER_LOOP_DETECTED in the
- Result-Code AVP of the corresponding Answer command. The event 'X
- successfully sent' is the complement of 'Failure to send X'.
-
- The following state machine is observed by a client when state is
- maintained on the server:
-
- CLIENT, STATEFUL
- State Event Action New State
- ---------------------------------------------------------------
- Idle Client or device requests Send Pending
- access service-
- specific
- auth req
-
- Idle ASR Received Send ASA Idle
- for unknown session with
- Result-Code =
- UNKNOWN_
- SESSION_ID
-
- Idle RAR Received Send RAA Idle
- for unknown session with
- Result-Code =
- UNKNOWN_
- SESSION_ID
-
- Pending Successful service-specific Grant Open
- authorization answer Access
- received with default
- Auth-Session-State value
-
- Pending Successful service-specific Sent STR Discon
- authorization answer received,
- but service not provided
-
- Pending Error processing successful Sent STR Discon
- service-specific authorization
- answer
-
-
-
-Fajardo, et al. Standards Track [Page 100]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Pending Failed service-specific Clean up Idle
- authorization answer received
-
- Open User or client device Send Open
- requests access to service service-
- specific
- auth req
-
- Open Successful service-specific Provide Open
- authorization answer received service
-
- Open Failed service-specific Discon. Idle
- authorization answer user/device
- received.
-
- Open RAR received and client will Send RAA Open
- perform subsequent re-auth with
- Result-Code =
- SUCCESS
-
- Open RAR received and client will Send RAA Idle
- not perform subsequent with
- re-auth Result-Code !=
- SUCCESS,
- Discon.
- user/device
-
- Open Session-Timeout expires on Send STR Discon
- access device
-
- Open ASR received, Send ASA Discon
- client will comply with
- with request to end the Result-Code =
- session = SUCCESS,
- Send STR.
-
- Open ASR Received, Send ASA Open
- client will not comply with
- with request to end the Result-Code !=
- session != SUCCESS
-
- Open Authorization-Lifetime + Send STR Discon
- Auth-Grace-Period expires on
- access device
-
- Discon ASR received Send ASA Discon
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 101]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Discon STA received Discon. Idle
- user/device
-
- The following state machine is observed by a server when it is
- maintaining state for the session:
-
- SERVER, STATEFUL
- State Event Action New State
- ---------------------------------------------------------------
- Idle Service-specific authorization Send Open
- request received, and successful
- user is authorized service-
- specific
- answer
-
- Idle Service-specific authorization Send Idle
- request received, and failed
- user is not authorized service-
- specific
- answer
-
- Open Service-specific authorization Send Open
- request received, and user successful
- is authorized service-
- specific
- answer
-
- Open Service-specific authorization Send Idle
- request received, and user failed
- is not authorized service-
- specific
- answer,
- Clean up
-
- Open Home server wants to confirm Send RAR Pending
- authentication and/or
- authorization of the user
-
- Pending Received RAA with a failed Clean up Idle
- Result-Code
-
- Pending Received RAA with Result-Code Update Open
- = SUCCESS session
-
- Open Home server wants to Send ASR Discon
- terminate the service
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 102]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Open Authorization-Lifetime (and Clean up Idle
- Auth-Grace-Period) expires
- on home server
-
- Open Session-Timeout expires on Clean up Idle
- home server
-
- Discon Failure to send ASR Wait, Discon
- resend ASR
-
- Discon ASR successfully sent and Clean up Idle
- ASA Received with Result-Code
-
- Not ASA Received None No Change
- Discon
-
- Any STR Received Send STA, Idle
- Clean up
-
- The following state machine is observed by a client when state is not
- maintained on the server:
-
- CLIENT, STATELESS
- State Event Action New State
- ---------------------------------------------------------------
- Idle Client or device requests Send Pending
- access service-
- specific
- auth req
-
- Pending Successful service-specific Grant Open
- authorization answer access
- received with Auth-Session-
- State set to
- NO_STATE_MAINTAINED
-
- Pending Failed service-specific Clean up Idle
- authorization answer
- received
-
- Open Session-Timeout expires on Discon. Idle
- access device user/device
-
- Open Service to user is terminated Discon. Idle
- user/device
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 103]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The following state machine is observed by a server when it is not
- maintaining state for the session:
-
- SERVER, STATELESS
- State Event Action New State
- ---------------------------------------------------------------
- Idle Service-specific authorization Send Idle
- request received, and service-
- successfully processed specific
- answer
-
-8.2. Accounting Session State Machine
-
- The following state machines MUST be supported for applications that
- have an accounting portion or that require only accounting services.
- The first state machine is to be observed by clients.
-
- See Section 9.7 for Accounting Command Codes and Section 9.8 for
- Accounting AVPs.
-
- The server side in the accounting state machine depends in some cases
- on the particular application. The Diameter base protocol defines a
- default state machine that MUST be followed by all applications that
- have not specified other state machines. This is the second state
- machine in this section described below.
-
- The default server side state machine requires the reception of
- accounting records in any order and at any time, and it does not
- place any standards requirement on the processing of these records.
- Implementations of Diameter may perform checking, ordering,
- correlation, fraud detection, and other tasks based on these records.
- AVPs may need to be inspected as a part of these tasks. The tasks
- can happen either immediately after record reception or in a post-
- processing phase. However, as these tasks are typically application
- or even policy dependent, they are not standardized by the Diameter
- specifications. Applications MAY define requirements on when to
- accept accounting records based on the used value of Accounting-
- Realtime-Required AVP, credit-limit checks, and so on.
-
- However, the Diameter base protocol defines one optional server side
- state machine that MAY be followed by applications that require
- keeping track of the session state at the accounting server. Note
- that such tracking is incompatible with the ability to sustain long
- duration connectivity problems. Therefore, the use of this state
- machine is recommended only in applications where the value of the
- Accounting-Realtime-Required AVP is DELIVER_AND_GRANT; hence,
- accounting connectivity problems are required to cause the serviced
- user to be disconnected. Otherwise, records produced by the client
-
-
-
-Fajardo, et al. Standards Track [Page 104]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- may be lost by the server, which no longer accepts them after the
- connectivity is re-established. This state machine is the third
- state machine in this section. The state machine is supervised by a
- supervision session timer Ts, whose value should be reasonably higher
- than the Acct_Interim_Interval value. Ts MAY be set to two times the
- value of the Acct_Interim_Interval so as to avoid the accounting
- session in the Diameter server to change to Idle state in case of
- short transient network failure.
-
- Any event not listed in the state machines MUST be considered as an
- error condition, and a corresponding answer, if applicable, MUST be
- returned to the originator of the message.
-
- In the state table, the event "Failure to send" means that the
- Diameter client is unable to communicate with the desired
- destination. This could be due to the peer being down, or due to the
- peer sending back a transient failure or temporary protocol error
- notification DIAMETER_OUT_OF_SPACE, DIAMETER_TOO_BUSY, or
- DIAMETER_LOOP_DETECTED in the Result-Code AVP of the Accounting
- Answer command.
-
- The event "Failed answer" means that the Diameter client received a
- non-transient failure notification in the Accounting Answer command.
-
- Note that the action "Disconnect user/dev" MUST also have an effect
- on the authorization session state table, e.g., cause the STR message
- to be sent, if the given application has both authentication/
- authorization and accounting portions.
-
- The states PendingS, PendingI, PendingL, PendingE, and PendingB stand
- for pending states to wait for an answer to an accounting request
- related to a Start, Interim, Stop, Event, or buffered record,
- respectively.
-
- CLIENT, ACCOUNTING
- State Event Action New State
- ---------------------------------------------------------------
- Idle Client or device requests Send PendingS
- access accounting
- start req.
-
- Idle Client or device requests Send PendingE
- a one-time service accounting
- event req
-
- Idle Records in storage Send PendingB
- record
-
-
-
-
-Fajardo, et al. Standards Track [Page 105]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- PendingS Successful accounting Open
- start answer received
-
- PendingS Failure to send and buffer Store Open
- space available and real time Start
- not equal to DELIVER_AND_GRANT Record
-
- PendingS Failure to send and no buffer Open
- space available and real time
- equal to GRANT_AND_LOSE
-
- PendingS Failure to send and no Disconnect Idle
- buffer space available and user/dev
- real time not equal to
- GRANT_AND_LOSE
-
- PendingS Failed accounting start answer Open
- received and real time equal
- to GRANT_AND_LOSE
-
- PendingS Failed accounting start answer Disconnect Idle
- received and real time not user/dev
- equal to GRANT_AND_LOSE
-
- PendingS User service terminated Store PendingS
- stop
- record
-
- Open Interim interval elapses Send PendingI
- accounting
- interim
- record
-
- Open User service terminated Send PendingL
- accounting
- stop req.
-
- PendingI Successful accounting interim Open
- answer received
-
- PendingI Failure to send and (buffer Store Open
- space available or old interim
- record can be overwritten) record
- and real time not equal to
- DELIVER_AND_GRANT
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 106]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- PendingI Failure to send and no buffer Open
- space available and real time
- equal to GRANT_AND_LOSE
-
- PendingI Failure to send and no Disconnect Idle
- buffer space available and user/dev
- real time not equal to
- GRANT_AND_LOSE
-
- PendingI Failed accounting interim Open
- answer received and real time
- equal to GRANT_AND_LOSE
-
- PendingI Failed accounting interim Disconnect Idle
- answer received and user/dev
- real time not equal to
- GRANT_AND_LOSE
-
- PendingI User service terminated Store PendingI
- stop
- record
- PendingE Successful accounting Idle
- event answer received
-
- PendingE Failure to send and buffer Store Idle
- space available event
- record
-
- PendingE Failure to send and no buffer Idle
- space available
-
- PendingE Failed accounting event answer Idle
- received
-
- PendingB Successful accounting answer Delete Idle
- received record
-
- PendingB Failure to send Idle
-
- PendingB Failed accounting answer Delete Idle
- received record
-
- PendingL Successful accounting Idle
- stop answer received
-
- PendingL Failure to send and buffer Store Idle
- space available stop
- record
-
-
-
-Fajardo, et al. Standards Track [Page 107]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- PendingL Failure to send and no buffer Idle
- space available
-
- PendingL Failed accounting stop answer Idle
- received
-
-
- SERVER, STATELESS ACCOUNTING
- State Event Action New State
- ---------------------------------------------------------------
-
- Idle Accounting start request Send Idle
- received and successfully accounting
- processed. start
- answer
-
- Idle Accounting event request Send Idle
- received and successfully accounting
- processed. event
- answer
-
- Idle Interim record received Send Idle
- and successfully processed. accounting
- interim
- answer
-
- Idle Accounting stop request Send Idle
- received and successfully accounting
- processed stop answer
-
- Idle Accounting request received; Send Idle
- no space left to store accounting
- records answer;
- Result-Code =
- OUT_OF_
- SPACE
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 108]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- SERVER, STATEFUL ACCOUNTING
- State Event Action New State
- ---------------------------------------------------------------
-
- Idle Accounting start request Send Open
- received and successfully accounting
- processed. start
- answer;
- Start Ts
-
- Idle Accounting event request Send Idle
- received and successfully accounting
- processed. event
- answer
- Idle Accounting request received; Send Idle
- no space left to store accounting
- records answer;
- Result-Code =
- OUT_OF_
- SPACE
-
- Open Interim record received Send Open
- and successfully processed. accounting
- interim
- answer;
- Restart Ts
-
- Open Accounting stop request Send Idle
- received and successfully accounting
- processed stop answer;
- Stop Ts
-
- Open Accounting request received; Send Idle
- no space left to store accounting
- records answer;
- Result-Code =
- OUT_OF_
- SPACE;
- Stop Ts
-
- Open Session supervision timer Ts Stop Ts Idle
- expired
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 109]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-8.3. Server-Initiated Re-Auth
-
- A Diameter server may initiate a re-authentication and/or re-
- authorization service for a particular session by issuing a Re-Auth-
- Request (RAR).
-
- For example, for prepaid services, the Diameter server that
- originally authorized a session may need some confirmation that the
- user is still using the services.
-
- An access device that receives an RAR message with the Session-Id
- equal to a currently active session MUST initiate a re-auth towards
- the user, if the service supports this particular feature. Each
- Diameter application MUST state whether server-initiated re-auth is
- supported, since some applications do not allow access devices to
- prompt the user for re-auth.
-
-8.3.1. Re-Auth-Request
-
- The Re-Auth-Request (RAR), indicated by the Command Code set to 258
- and the message flags' 'R' bit set, may be sent by any server to the
- access device that is providing session service, to request that the
- user be re-authenticated and/or re-authorized.
-
-
- Message Format
-
- &lt;RAR> ::= &lt; Diameter Header: 258, REQ, PXY >
- &lt; Session-Id >
- { Origin-Host }
- { Origin-Realm }
- { Destination-Realm }
- { Destination-Host }
- { Auth-Application-Id }
- { Re-Auth-Request-Type }
- [ User-Name ]
- [ Origin-State-Id ]
- * [ Proxy-Info ]
- * [ Route-Record ]
- * [ AVP ]
-
-8.3.2. Re-Auth-Answer
-
- The Re-Auth-Answer (RAA), indicated by the Command Code set to 258
- and the message flags' 'R' bit clear, is sent in response to the RAR.
- The Result-Code AVP MUST be present, and it indicates the disposition
- of the request.
-
-
-
-
-Fajardo, et al. Standards Track [Page 110]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- A successful RAA message MUST be followed by an application-specific
- authentication and/or authorization message.
-
- Message Format
-
- &lt;RAA> ::= &lt; Diameter Header: 258, PXY >
- &lt; Session-Id >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- [ User-Name ]
- [ Origin-State-Id ]
- [ Error-Message ]
- [ Error-Reporting-Host ]
- [ Failed-AVP ]
- * [ Redirect-Host ]
- [ Redirect-Host-Usage ]
- [ Redirect-Max-Cache-Time ]
- * [ Proxy-Info ]
- * [ AVP ]
-
-8.4. Session Termination
-
- It is necessary for a Diameter server that authorized a session, for
- which it is maintaining state, to be notified when that session is no
- longer active, both for tracking purposes as well as to allow
- stateful agents to release any resources that they may have provided
- for the user's session. For sessions whose state is not being
- maintained, this section is not used.
-
- When a user session that required Diameter authorization terminates,
- the access device that provided the service MUST issue a Session-
- Termination-Request (STR) message to the Diameter server that
- authorized the service, to notify it that the session is no longer
- active. An STR MUST be issued when a user session terminates for any
- reason, including user logoff, expiration of Session-Timeout,
- administrative action, termination upon receipt of an Abort-Session-
- Request (see below), orderly shutdown of the access device, etc.
-
- The access device also MUST issue an STR for a session that was
- authorized but never actually started. This could occur, for
- example, due to a sudden resource shortage in the access device, or
- because the access device is unwilling to provide the type of service
- requested in the authorization, or because the access device does not
- support a mandatory AVP returned in the authorization, etc.
-
- It is also possible that a session that was authorized is never
- actually started due to action of a proxy. For example, a proxy may
-
-
-
-Fajardo, et al. Standards Track [Page 111]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- modify an authorization answer, converting the result from success to
- failure, prior to forwarding the message to the access device. If
- the answer did not contain an Auth-Session-State AVP with the value
- NO_STATE_MAINTAINED, a proxy that causes an authorized session not to
- be started MUST issue an STR to the Diameter server that authorized
- the session, since the access device has no way of knowing that the
- session had been authorized.
-
- A Diameter server that receives an STR message MUST clean up
- resources (e.g., session state) associated with the Session-Id
- specified in the STR and return a Session-Termination-Answer.
-
- A Diameter server also MUST clean up resources when the Session-
- Timeout expires, or when the Authorization-Lifetime and the Auth-
- Grace-Period AVPs expire without receipt of a re-authorization
- request, regardless of whether an STR for that session is received.
- The access device is not expected to provide service beyond the
- expiration of these timers; thus, expiration of either of these
- timers implies that the access device may have unexpectedly shut
- down.
-
-8.4.1. Session-Termination-Request
-
- The Session-Termination-Request (STR), indicated by the Command Code
- set to 275 and the Command Flags' 'R' bit set, is sent by a Diameter
- client or by a Diameter proxy to inform the Diameter server that an
- authenticated and/or authorized session is being terminated.
-
- Message Format
-
- &lt;STR> ::= &lt; Diameter Header: 275, REQ, PXY >
- &lt; Session-Id >
- { Origin-Host }
- { Origin-Realm }
- { Destination-Realm }
- { Auth-Application-Id }
- { Termination-Cause }
- [ User-Name ]
- [ Destination-Host ]
- * [ Class ]
- [ Origin-State-Id ]
- * [ Proxy-Info ]
- * [ Route-Record ]
- * [ AVP ]
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 112]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-8.4.2. Session-Termination-Answer
-
- The Session-Termination-Answer (STA), indicated by the Command Code
- set to 275 and the message flags' 'R' bit clear, is sent by the
- Diameter server to acknowledge the notification that the session has
- been terminated. The Result-Code AVP MUST be present, and it MAY
- contain an indication that an error occurred while servicing the STR.
-
- Upon sending or receipt of the STA, the Diameter server MUST release
- all resources for the session indicated by the Session-Id AVP. Any
- intermediate server in the Proxy-Chain MAY also release any
- resources, if necessary.
-
- Message Format
-
- &lt;STA> ::= &lt; Diameter Header: 275, PXY >
- &lt; Session-Id >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- [ User-Name ]
- * [ Class ]
- [ Error-Message ]
- [ Error-Reporting-Host ]
- [ Failed-AVP ]
- [ Origin-State-Id ]
- * [ Redirect-Host ]
- [ Redirect-Host-Usage ]
- [ Redirect-Max-Cache-Time ]
- * [ Proxy-Info ]
- * [ AVP ]
-
-8.5. Aborting a Session
-
- A Diameter server may request that the access device stop providing
- service for a particular session by issuing an Abort-Session-Request
- (ASR).
-
- For example, the Diameter server that originally authorized the
- session may be required to cause that session to be stopped for lack
- of credit or other reasons that were not anticipated when the session
- was first authorized.
-
- An access device that receives an ASR with Session-ID equal to a
- currently active session MAY stop the session. Whether the access
- device stops the session or not is implementation and/or
- configuration dependent. For example, an access device may honor
- ASRs from certain agents only. In any case, the access device MUST
-
-
-
-Fajardo, et al. Standards Track [Page 113]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- respond with an Abort-Session-Answer, including a Result-Code AVP to
- indicate what action it took.
-
-8.5.1. Abort-Session-Request
-
- The Abort-Session-Request (ASR), indicated by the Command Code set to
- 274 and the message flags' 'R' bit set, may be sent by any Diameter
- server or any Diameter proxy to the access device that is providing
- session service, to request that the session identified by the
- Session-Id be stopped.
-
- Message Format
-
- &lt;ASR> ::= &lt; Diameter Header: 274, REQ, PXY >
- &lt; Session-Id >
- { Origin-Host }
- { Origin-Realm }
- { Destination-Realm }
- { Destination-Host }
- { Auth-Application-Id }
- [ User-Name ]
- [ Origin-State-Id ]
- * [ Proxy-Info ]
- * [ Route-Record ]
- * [ AVP ]
-
-8.5.2. Abort-Session-Answer
-
- The Abort-Session-Answer (ASA), indicated by the Command Code set to
- 274 and the message flags' 'R' bit clear, is sent in response to the
- ASR. The Result-Code AVP MUST be present and indicates the
- disposition of the request.
-
- If the session identified by Session-Id in the ASR was successfully
- terminated, the Result-Code is set to DIAMETER_SUCCESS. If the
- session is not currently active, the Result-Code is set to
- DIAMETER_UNKNOWN_SESSION_ID. If the access device does not stop the
- session for any other reason, the Result-Code is set to
- DIAMETER_UNABLE_TO_COMPLY.
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 114]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Message Format
-
- &lt;ASA> ::= &lt; Diameter Header: 274, PXY >
- &lt; Session-Id >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- [ User-Name ]
- [ Origin-State-Id ]
- [ Error-Message ]
- [ Error-Reporting-Host ]
- [ Failed-AVP ]
- * [ Redirect-Host ]
- [ Redirect-Host-Usage ]
- [ Redirect-Max-Cache-Time ]
- * [ Proxy-Info ]
- * [ AVP ]
-
-8.6. Inferring Session Termination from Origin-State-Id
-
- The Origin-State-Id is used to allow detection of terminated sessions
- for which no STR would have been issued, due to unanticipated
- shutdown of an access device.
-
- A Diameter client or access device increments the value of the
- Origin-State-Id every time it is started or powered up. The new
- Origin-State-Id is then sent in the CER/CEA message immediately upon
- connection to the server. The Diameter server receiving the new
- Origin-State-Id can determine whether the sending Diameter client had
- abruptly shut down by comparing the old value of the Origin-State-Id
- it has kept for that specific client is less than the new value and
- whether it has un-terminated sessions originating from that client.
-
- An access device can also include the Origin-State-Id in request
- messages other than the CER if there are relays or proxies in between
- the access device and the server. In this case, however, the server
- cannot discover that the access device has been restarted unless and
- until it receives a new request from it. Therefore, this mechanism
- is more opportunistic across proxies and relays.
-
- The Diameter server may assume that all sessions that were active
- prior to detection of a client restart have been terminated. The
- Diameter server MAY clean up all session state associated with such
- lost sessions, and it MAY also issue STRs for all such lost sessions
- that were authorized on upstream servers, to allow session state to
- be cleaned up globally.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 115]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-8.7. Auth-Request-Type AVP
-
- The Auth-Request-Type AVP (AVP Code 274) is of type Enumerated and is
- included in application-specific auth requests to inform the peers
- whether a user is to be authenticated only, authorized only, or both.
- Note any value other than both MAY cause RADIUS interoperability
- issues. The following values are defined:
-
- AUTHENTICATE_ONLY 1
-
- The request being sent is for authentication only, and it MUST
- contain the relevant application-specific authentication AVPs that
- are needed by the Diameter server to authenticate the user.
-
- AUTHORIZE_ONLY 2
-
- The request being sent is for authorization only, and it MUST
- contain the application-specific authorization AVPs that are
- necessary to identify the service being requested/offered.
-
- AUTHORIZE_AUTHENTICATE 3
-
- The request contains a request for both authentication and
- authorization. The request MUST include both the relevant
- application-specific authentication information and authorization
- information necessary to identify the service being requested/
- offered.
-
-8.8. Session-Id AVP
-
- The Session-Id AVP (AVP Code 263) is of type UTF8String and is used
- to identify a specific session (see Section 8). All messages
- pertaining to a specific session MUST include only one Session-Id
- AVP, and the same value MUST be used throughout the life of a
- session. When present, the Session-Id SHOULD appear immediately
- following the Diameter header (see Section 3).
-
- The Session-Id MUST be globally and eternally unique, as it is meant
- to uniquely identify a user session without reference to any other
- information, and it may be needed to correlate historical
- authentication information with accounting information. The
- Session-Id includes a mandatory portion and an implementation-defined
- portion; a recommended format for the implementation-defined portion
- is outlined below.
-
- The Session-Id MUST begin with the sender's identity encoded in the
- DiameterIdentity type (see Section 4.3.1). The remainder of the
- Session-Id is delimited by a ";" character, and it MAY be any
-
-
-
-Fajardo, et al. Standards Track [Page 116]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- sequence that the client can guarantee to be eternally unique;
- however, the following format is recommended, (square brackets []
- indicate an optional element):
-
- &lt;DiameterIdentity>;&lt;high 32 bits>;&lt;low 32 bits>[;&lt;optional value>]
-
- &lt;high 32 bits> and &lt;low 32 bits> are decimal representations of the
- high and low 32 bits of a monotonically increasing 64-bit value. The
- 64-bit value is rendered in two part to simplify formatting by 32-bit
- processors. At startup, the high 32 bits of the 64-bit value MAY be
- initialized to the time in NTP format [RFC5905], and the low 32 bits
- MAY be initialized to zero. This will for practical purposes
- eliminate the possibility of overlapping Session-Ids after a reboot,
- assuming the reboot process takes longer than a second.
- Alternatively, an implementation MAY keep track of the increasing
- value in non-volatile memory.
-
-
- &lt;optional value> is implementation specific, but it may include a
- modem's device Id, a Layer 2 address, timestamp, etc.
-
- Example, in which there is no optional value:
-
- accesspoint7.example.com;1876543210;523
-
- Example, in which there is an optional value:
-
- accesspoint7.example.com;1876543210;523;[email protected]
-
- The Session-Id is created by the Diameter application initiating the
- session, which, in most cases, is done by the client. Note that a
- Session-Id MAY be used for both the authentication, authorization,
- and accounting commands of a given application.
-
-8.9. Authorization-Lifetime AVP
-
- The Authorization-Lifetime AVP (AVP Code 291) is of type Unsigned32
- and contains the maximum number of seconds of service to be provided
- to the user before the user is to be re-authenticated and/or re-
- authorized. Care should be taken when the Authorization-Lifetime
- value is determined, since a low, non-zero value could create
- significant Diameter traffic, which could congest both the network
- and the agents.
-
- A value of zero (0) means that immediate re-auth is necessary by the
- access device. The absence of this AVP, or a value of all ones
- (meaning all bits in the 32-bit field are set to one) means no re-
- auth is expected.
-
-
-
-Fajardo, et al. Standards Track [Page 117]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- If both this AVP and the Session-Timeout AVP are present in a
- message, the value of the latter MUST NOT be smaller than the
- Authorization-Lifetime AVP.
-
- An Authorization-Lifetime AVP MAY be present in re-authorization
- messages, and it contains the number of seconds the user is
- authorized to receive service from the time the re-auth answer
- message is received by the access device.
-
- This AVP MAY be provided by the client as a hint of the maximum
- lifetime that it is willing to accept. The server MUST return a
- value that is equal to, or smaller than, the one provided by the
- client.
-
-8.10. Auth-Grace-Period AVP
-
- The Auth-Grace-Period AVP (AVP Code 276) is of type Unsigned32 and
- contains the number of seconds the Diameter server will wait
- following the expiration of the Authorization-Lifetime AVP before
- cleaning up resources for the session.
-
-8.11. Auth-Session-State AVP
-
- The Auth-Session-State AVP (AVP Code 277) is of type Enumerated and
- specifies whether state is maintained for a particular session. The
- client MAY include this AVP in requests as a hint to the server, but
- the value in the server's answer message is binding. The following
- values are supported:
-
- STATE_MAINTAINED 0
-
- This value is used to specify that session state is being
- maintained, and the access device MUST issue a session termination
- message when service to the user is terminated. This is the
- default value.
-
- NO_STATE_MAINTAINED 1
-
- This value is used to specify that no session termination messages
- will be sent by the access device upon expiration of the
- Authorization-Lifetime.
-
-8.12. Re-Auth-Request-Type AVP
-
- The Re-Auth-Request-Type AVP (AVP Code 285) is of type Enumerated and
- is included in application-specific auth answers to inform the client
- of the action expected upon expiration of the Authorization-Lifetime.
-
-
-
-
-Fajardo, et al. Standards Track [Page 118]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- If the answer message contains an Authorization-Lifetime AVP with a
- positive value, the Re-Auth-Request-Type AVP MUST be present in an
- answer message. The following values are defined:
-
- AUTHORIZE_ONLY 0
-
- An authorization only re-auth is expected upon expiration of the
- Authorization-Lifetime. This is the default value if the AVP is
- not present in answer messages that include the Authorization-
- Lifetime.
-
- AUTHORIZE_AUTHENTICATE 1
-
- An authentication and authorization re-auth is expected upon
- expiration of the Authorization-Lifetime.
-
-8.13. Session-Timeout AVP
-
- The Session-Timeout AVP (AVP Code 27) [RFC2865] is of type Unsigned32
- and contains the maximum number of seconds of service to be provided
- to the user before termination of the session. When both the
- Session-Timeout and the Authorization-Lifetime AVPs are present in an
- answer message, the former MUST be equal to or greater than the value
- of the latter.
-
- A session that terminates on an access device due to the expiration
- of the Session-Timeout MUST cause an STR to be issued, unless both
- the access device and the home server had previously agreed that no
- session termination messages would be sent (see Section 8).
-
- A Session-Timeout AVP MAY be present in a re-authorization answer
- message, and it contains the remaining number of seconds from the
- beginning of the re-auth.
-
- A value of zero, or the absence of this AVP, means that this session
- has an unlimited number of seconds before termination.
-
- This AVP MAY be provided by the client as a hint of the maximum
- timeout that it is willing to accept. However, the server MAY return
- a value that is equal to, or smaller than, the one provided by the
- client.
-
-8.14. User-Name AVP
-
- The User-Name AVP (AVP Code 1) [RFC2865] is of type UTF8String, which
- contains the User-Name, in a format consistent with the NAI
- specification [RFC4282].
-
-
-
-
-Fajardo, et al. Standards Track [Page 119]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-8.15. Termination-Cause AVP
-
- The Termination-Cause AVP (AVP Code 295) is of type Enumerated, and
- is used to indicate the reason why a session was terminated on the
- access device. The currently assigned values for this AVP can be
- found in the IANA registry for Termination-Cause AVP Values
- [IANATCV].
-
-8.16. Origin-State-Id AVP
-
- The Origin-State-Id AVP (AVP Code 278), of type Unsigned32, is a
- monotonically increasing value that is advanced whenever a Diameter
- entity restarts with loss of previous state, for example, upon
- reboot. Origin-State-Id MAY be included in any Diameter message,
- including CER.
-
- A Diameter entity issuing this AVP MUST create a higher value for
- this AVP each time its state is reset. A Diameter entity MAY set
- Origin-State-Id to the time of startup, or it MAY use an incrementing
- counter retained in non-volatile memory across restarts.
-
- The Origin-State-Id, if present, MUST reflect the state of the entity
- indicated by Origin-Host. If a proxy modifies Origin-Host, it MUST
- either remove Origin-State-Id or modify it appropriately as well.
- Typically, Origin-State-Id is used by an access device that always
- starts up with no active sessions; that is, any session active prior
- to restart will have been lost. By including Origin-State-Id in a
- message, it allows other Diameter entities to infer that sessions
- associated with a lower Origin-State-Id are no longer active. If an
- access device does not intend for such inferences to be made, it MUST
- either not include Origin-State-Id in any message or set its value to
- 0.
-
-8.17. Session-Binding AVP
-
- The Session-Binding AVP (AVP Code 270) is of type Unsigned32, and it
- MAY be present in application-specific authorization answer messages.
- If present, this AVP MAY inform the Diameter client that all future
- application-specific re-auth and Session-Termination-Request messages
- for this session MUST be sent to the same authorization server.
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 120]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- This field is a bit mask, and the following bits have been defined:
-
- RE_AUTH 1
-
- When set, future re-auth messages for this session MUST NOT
- include the Destination-Host AVP. When cleared, the default
- value, the Destination-Host AVP MUST be present in all re-auth
- messages for this session.
-
- STR 2
-
- When set, the STR message for this session MUST NOT include the
- Destination-Host AVP. When cleared, the default value, the
- Destination-Host AVP MUST be present in the STR message for this
- session.
-
- ACCOUNTING 4
-
- When set, all accounting messages for this session MUST NOT
- include the Destination-Host AVP. When cleared, the default
- value, the Destination-Host AVP, if known, MUST be present in all
- accounting messages for this session.
-
-8.18. Session-Server-Failover AVP
-
- The Session-Server-Failover AVP (AVP Code 271) is of type Enumerated
- and MAY be present in application-specific authorization answer
- messages that either do not include the Session-Binding AVP or
- include the Session-Binding AVP with any of the bits set to a zero
- value. If present, this AVP MAY inform the Diameter client that if a
- re-auth or STR message fails due to a delivery problem, the Diameter
- client SHOULD issue a subsequent message without the Destination-Host
- AVP. When absent, the default value is REFUSE_SERVICE.
-
- The following values are supported:
-
- REFUSE_SERVICE 0
-
- If either the re-auth or the STR message delivery fails, terminate
- service with the user and do not attempt any subsequent attempts.
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 121]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- TRY_AGAIN 1
-
- If either the re-auth or the STR message delivery fails, resend
- the failed message without the Destination-Host AVP present.
-
- ALLOW_SERVICE 2
-
- If re-auth message delivery fails, assume that re-authorization
- succeeded. If STR message delivery fails, terminate the session.
-
- TRY_AGAIN_ALLOW_SERVICE 3
-
- If either the re-auth or the STR message delivery fails, resend
- the failed message without the Destination-Host AVP present. If
- the second delivery fails for re-auth, assume re-authorization
- succeeded. If the second delivery fails for STR, terminate the
- session.
-
-8.19. Multi-Round-Time-Out AVP
-
- The Multi-Round-Time-Out AVP (AVP Code 272) is of type Unsigned32 and
- SHOULD be present in application-specific authorization answer
- messages whose Result-Code AVP is set to DIAMETER_MULTI_ROUND_AUTH.
- This AVP contains the maximum number of seconds that the access
- device MUST provide the user in responding to an authentication
- request.
-
-8.20. Class AVP
-
- The Class AVP (AVP Code 25) is of type OctetString and is used by
- Diameter servers to return state information to the access device.
- When one or more Class AVPs are present in application-specific
- authorization answer messages, they MUST be present in subsequent re-
- authorization, session termination and accounting messages. Class
- AVPs found in a re-authorization answer message override the ones
- found in any previous authorization answer message. Diameter server
- implementations SHOULD NOT return Class AVPs that require more than
- 4096 bytes of storage on the Diameter client. A Diameter client that
- receives Class AVPs whose size exceeds local available storage MUST
- terminate the session.
-
-8.21. Event-Timestamp AVP
-
- The Event-Timestamp (AVP Code 55) is of type Time and MAY be included
- in an Accounting-Request and Accounting-Answer messages to record the
- time that the reported event occurred, in seconds since January 1,
- 1900 00:00 UTC.
-
-
-
-
-Fajardo, et al. Standards Track [Page 122]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-9. Accounting
-
- This accounting protocol is based on a server directed model with
- capabilities for real-time delivery of accounting information.
- Several fault resilience methods [RFC2975] have been built into the
- protocol in order minimize loss of accounting data in various fault
- situations and under different assumptions about the capabilities of
- the used devices.
-
-9.1. Server Directed Model
-
- The server directed model means that the device generating the
- accounting data gets information from either the authorization server
- (if contacted) or the accounting server regarding the way accounting
- data shall be forwarded. This information includes accounting record
- timeliness requirements.
-
- As discussed in [RFC2975], real-time transfer of accounting records
- is a requirement, such as the need to perform credit-limit checks and
- fraud detection. Note that batch accounting is not a requirement,
- and is therefore not supported by Diameter. Should batched
- accounting be required in the future, a new Diameter application will
- need to be created, or it could be handled using another protocol.
- Note, however, that even if at the Diameter layer, accounting
- requests are processed one by one; transport protocols used under
- Diameter typically batch several requests in the same packet under
- heavy traffic conditions. This may be sufficient for many
- applications.
-
- The authorization server (chain) directs the selection of proper
- transfer strategy, based on its knowledge of the user and
- relationships of roaming partnerships. The server (or agents) uses
- the Acct-Interim-Interval and Accounting-Realtime-Required AVPs to
- control the operation of the Diameter peer operating as a client.
- The Acct-Interim-Interval AVP, when present, instructs the Diameter
- node acting as a client to produce accounting records continuously
- even during a session. Accounting-Realtime-Required AVP is used to
- control the behavior of the client when the transfer of accounting
- records from the Diameter client is delayed or unsuccessful.
-
- The Diameter accounting server MAY override the interim interval or
- the real-time requirements by including the Acct-Interim-Interval or
- Accounting-Realtime-Required AVP in the Accounting-Answer message.
- When one of these AVPs is present, the latest value received SHOULD
- be used in further accounting activities for the same session.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 123]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-9.2. Protocol Messages
-
- A Diameter node that receives a successful authentication and/or
- authorization message from the Diameter server SHOULD collect
- accounting information for the session. The Accounting-Request
- message is used to transmit the accounting information to the
- Diameter server, which MUST reply with the Accounting-Answer message
- to confirm reception. The Accounting-Answer message includes the
- Result-Code AVP, which MAY indicate that an error was present in the
- accounting message. The value of the Accounting-Realtime-Required
- AVP received earlier for the session in question may indicate that
- the user's session has to be terminated when a rejected Accounting-
- Request message was received.
-
-9.3. Accounting Application Extension and Requirements
-
- Each Diameter application (e.g., NASREQ, Mobile IP) SHOULD define its
- service-specific AVPs that MUST be present in the Accounting-Request
- message in a section titled "Accounting AVPs". The application MUST
- assume that the AVPs described in this document will be present in
- all Accounting messages, so only their respective service-specific
- AVPs need to be defined in that section.
-
- Applications have the option of using one or both of the following
- accounting application extension models:
-
- Split Accounting Service
-
- The accounting message will carry the Application Id of the
- Diameter base accounting application (see Section 2.4).
- Accounting messages may be routed to Diameter nodes other than the
- corresponding Diameter application. These nodes might be
- centralized accounting servers that provide accounting service for
- multiple different Diameter applications. These nodes MUST
- advertise the Diameter base accounting Application Id during
- capabilities exchange.
-
- Coupled Accounting Service
-
- The accounting message will carry the Application Id of the
- application that is using it. The application itself will process
- the received accounting records or forward them to an accounting
- server. There is no accounting application advertisement required
- during capabilities exchange, and the accounting messages will be
- routed the same way as any of the other application messages.
-
- In cases where an application does not define its own accounting
- service, it is preferred that the split accounting model be used.
-
-
-
-Fajardo, et al. Standards Track [Page 124]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-9.4. Fault Resilience
-
- Diameter base protocol mechanisms are used to overcome small message
- loss and network faults of a temporary nature.
-
- Diameter peers acting as clients MUST implement the use of failover
- to guard against server failures and certain network failures.
- Diameter peers acting as agents or related off-line processing
- systems MUST detect duplicate accounting records caused by the
- sending of the same record to several servers and duplication of
- messages in transit. This detection MUST be based on the inspection
- of the Session-Id and Accounting-Record-Number AVP pairs. Appendix C
- discusses duplicate detection needs and implementation issues.
-
- Diameter clients MAY have non-volatile memory for the safe storage of
- accounting records over reboots or extended network failures, network
- partitions, and server failures. If such memory is available, the
- client SHOULD store new accounting records there as soon as the
- records are created and until a positive acknowledgement of their
- reception from the Diameter server has been received. Upon a reboot,
- the client MUST start sending the records in the non-volatile memory
- to the accounting server with the appropriate modifications in
- termination cause, session length, and other relevant information in
- the records.
-
- A further application of this protocol may include AVPs to control
- the maximum number of accounting records that may be stored in the
- Diameter client without committing them to the non-volatile memory or
- transferring them to the Diameter server.
-
- The client SHOULD NOT remove the accounting data from any of its
- memory areas before the correct Accounting-Answer has been received.
- The client MAY remove the oldest, undelivered, or as yet
- unacknowledged accounting data if it runs out of resources such as
- memory. It is an implementation-dependent matter for the client to
- accept new sessions under this condition.
-
-9.5. Accounting Records
-
- In all accounting records, the Session-Id AVP MUST be present; the
- User-Name AVP MUST be present if it is available to the Diameter
- client.
-
- Different types of accounting records are sent depending on the
- actual type of accounted service and the authorization server's
- directions for interim accounting. If the accounted service is a
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 125]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- one-time event, meaning that the start and stop of the event are
- simultaneous, then the Accounting-Record-Type AVP MUST be present and
- set to the value EVENT_RECORD.
-
- If the accounted service is of a measurable length, then the AVP MUST
- use the values START_RECORD, STOP_RECORD, and possibly,
- INTERIM_RECORD. If the authorization server has not directed interim
- accounting to be enabled for the session, two accounting records MUST
- be generated for each service of type session. When the initial
- Accounting-Request for a given session is sent, the Accounting-
- Record-Type AVP MUST be set to the value START_RECORD. When the last
- Accounting-Request is sent, the value MUST be STOP_RECORD.
-
- If the authorization server has directed interim accounting to be
- enabled, the Diameter client MUST produce additional records between
- the START_RECORD and STOP_RECORD, marked INTERIM_RECORD. The
- production of these records is directed by Acct-Interim-Interval as
- well as any re-authentication or re-authorization of the session.
- The Diameter client MUST overwrite any previous interim accounting
- records that are locally stored for delivery, if a new record is
- being generated for the same session. This ensures that only one
- pending interim record can exist on an access device for any given
- session.
-
- A particular value of Accounting-Sub-Session-Id MUST appear only in
- one sequence of accounting records from a Diameter client, except for
- the purposes of retransmission. The one sequence that is sent MUST
- be either one record with Accounting-Record-Type AVP set to the value
- EVENT_RECORD or several records starting with one having the value
- START_RECORD, followed by zero or more INTERIM_RECORDs and a single
- STOP_RECORD. A particular Diameter application specification MUST
- define the type of sequences that MUST be used.
-
-9.6. Correlation of Accounting Records
-
- If an application uses accounting messages, it can correlate
- accounting records with a specific application session by using the
- Session-Id of the particular application session in the accounting
- messages. Accounting messages MAY also use a different Session-Id
- from that of the application sessions, in which case, other session-
- related information is needed to perform correlation.
-
- In cases where an application requires multiple accounting sub-
- sessions, an Accounting-Sub-Session-Id AVP is used to differentiate
- each sub-session. The Session-Id would remain constant for all sub-
- sessions and is used to correlate all the sub-sessions to a
- particular application session. Note that receiving a STOP_RECORD
-
-
-
-
-Fajardo, et al. Standards Track [Page 126]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- with no Accounting-Sub-Session-Id AVP when sub-sessions were
- originally used in the START_RECORD messages implies that all sub-
- sessions are terminated.
-
- There are also cases where an application needs to correlate multiple
- application sessions into a single accounting record; the accounting
- record may span multiple different Diameter applications and sessions
- used by the same user at a given time. In such cases, the Acct-
- Multi-Session-Id AVP is used. The Acct-Multi-Session-Id AVP SHOULD
- be signaled by the server to the access device (typically, during
- authorization) when it determines that a request belongs to an
- existing session. The access device MUST then include the Acct-
- Multi-Session-Id AVP in all subsequent accounting messages.
-
- The Acct-Multi-Session-Id AVP MAY include the value of the original
- Session-Id. Its contents are implementation specific, but the MUST
- be globally unique across other Acct-Multi-Session-Ids and MUST NOT
- change during the life of a session.
-
- A Diameter application document MUST define the exact concept of a
- session that is being accounted, and it MAY define the concept of a
- multi-session. For instance, the NASREQ DIAMETER application treats
- a single PPP connection to a Network Access Server as one session and
- a set of Multilink PPP sessions as one multi-session.
-
-9.7. Accounting Command Codes
-
- This section defines Command Code values that MUST be supported by
- all Diameter implementations that provide accounting services.
-
-9.7.1. Accounting-Request
-
- The Accounting-Request (ACR) command, indicated by the Command Code
- field set to 271 and the Command Flags' 'R' bit set, is sent by a
- Diameter node, acting as a client, in order to exchange accounting
- information with a peer.
-
- In addition to the AVPs listed below, Accounting-Request messages
- SHOULD include service-specific accounting AVPs.
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 127]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Message Format
-
- &lt;ACR> ::= &lt; Diameter Header: 271, REQ, PXY >
- &lt; Session-Id >
- { Origin-Host }
- { Origin-Realm }
- { Destination-Realm }
- { Accounting-Record-Type }
- { Accounting-Record-Number }
- [ Acct-Application-Id ]
- [ Vendor-Specific-Application-Id ]
- [ User-Name ]
- [ Destination-Host ]
- [ Accounting-Sub-Session-Id ]
- [ Acct-Session-Id ]
- [ Acct-Multi-Session-Id ]
- [ Acct-Interim-Interval ]
- [ Accounting-Realtime-Required ]
- [ Origin-State-Id ]
- [ Event-Timestamp ]
- * [ Proxy-Info ]
- * [ Route-Record ]
- * [ AVP ]
-
-9.7.2. Accounting-Answer
-
- The Accounting-Answer (ACA) command, indicated by the Command Code
- field set to 271 and the Command Flags' 'R' bit cleared, is used to
- acknowledge an Accounting-Request command. The Accounting-Answer
- command contains the same Session-Id as the corresponding request.
-
- Only the target Diameter server, known as the home Diameter server,
- SHOULD respond with the Accounting-Answer command.
-
- In addition to the AVPs listed below, Accounting-Answer messages
- SHOULD include service-specific accounting AVPs.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 128]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Message Format
-
- &lt;ACA> ::= &lt; Diameter Header: 271, PXY >
- &lt; Session-Id >
- { Result-Code }
- { Origin-Host }
- { Origin-Realm }
- { Accounting-Record-Type }
- { Accounting-Record-Number }
- [ Acct-Application-Id ]
- [ Vendor-Specific-Application-Id ]
- [ User-Name ]
- [ Accounting-Sub-Session-Id ]
- [ Acct-Session-Id ]
- [ Acct-Multi-Session-Id ]
- [ Error-Message ]
- [ Error-Reporting-Host ]
- [ Failed-AVP ]
- [ Acct-Interim-Interval ]
- [ Accounting-Realtime-Required ]
- [ Origin-State-Id ]
- [ Event-Timestamp ]
- * [ Proxy-Info ]
- * [ AVP ]
-
-9.8. Accounting AVPs
-
- This section contains AVPs that describe accounting usage information
- related to a specific session.
-
-9.8.1. Accounting-Record-Type AVP
-
- The Accounting-Record-Type AVP (AVP Code 480) is of type Enumerated
- and contains the type of accounting record being sent. The following
- values are currently defined for the Accounting-Record-Type AVP:
-
- EVENT_RECORD 1
-
- An Accounting Event Record is used to indicate that a one-time
- event has occurred (meaning that the start and end of the event
- are simultaneous). This record contains all information relevant
- to the service, and it is the only record of the service.
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 129]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- START_RECORD 2
-
- Accounting Start, Interim, and Stop Records are used to indicate
- that a service of a measurable length has been given. An
- Accounting Start Record is used to initiate an accounting session
- and contains accounting information that is relevant to the
- initiation of the session.
-
- INTERIM_RECORD 3
-
- An Interim Accounting Record contains cumulative accounting
- information for an existing accounting session. Interim
- Accounting Records SHOULD be sent every time a re-authentication
- or re-authorization occurs. Further, additional interim record
- triggers MAY be defined by application-specific Diameter
- applications. The selection of whether to use INTERIM_RECORD
- records is done by the Acct-Interim-Interval AVP.
-
- STOP_RECORD 4
-
- An Accounting Stop Record is sent to terminate an accounting
- session and contains cumulative accounting information relevant to
- the existing session.
-
-9.8.2. Acct-Interim-Interval AVP
-
- The Acct-Interim-Interval AVP (AVP Code 85) is of type Unsigned32 and
- is sent from the Diameter home authorization server to the Diameter
- client. The client uses information in this AVP to decide how and
- when to produce accounting records. With different values in this
- AVP, service sessions can result in one, two, or two+N accounting
- records, based on the needs of the home organization. The following
- accounting record production behavior is directed by the inclusion of
- this AVP:
-
- 1. The omission of the Acct-Interim-Interval AVP or its inclusion
- with Value field set to 0 means that EVENT_RECORD, START_RECORD,
- and STOP_RECORD are produced, as appropriate for the service.
-
- 2. The inclusion of the AVP with Value field set to a non-zero value
- means that INTERIM_RECORD records MUST be produced between the
- START_RECORD and STOP_RECORD records. The Value field of this
- AVP is the nominal interval between these records in seconds.
- The Diameter node that originates the accounting information,
- known as the client, MUST produce the first INTERIM_RECORD record
- roughly at the time when this nominal interval has elapsed from
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 130]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- the START_RECORD, the next one again as the interval has elapsed
- once more, and so on until the session ends and a STOP_RECORD
- record is produced.
-
- The client MUST ensure that the interim record production times
- are randomized so that large accounting message storms are not
- created either among records or around a common service start
- time.
-
-9.8.3. Accounting-Record-Number AVP
-
- The Accounting-Record-Number AVP (AVP Code 485) is of type Unsigned32
- and identifies this record within one session. As Session-Id AVPs
- are globally unique, the combination of Session-Id and Accounting-
- Record-Number AVPs is also globally unique and can be used in
- matching accounting records with confirmations. An easy way to
- produce unique numbers is to set the value to 0 for records of type
- EVENT_RECORD and START_RECORD and set the value to 1 for the first
- INTERIM_RECORD, 2 for the second, and so on until the value for
- STOP_RECORD is one more than for the last INTERIM_RECORD.
-
-9.8.4. Acct-Session-Id AVP
-
- The Acct-Session-Id AVP (AVP Code 44) is of type OctetString is only
- used when RADIUS/Diameter translation occurs. This AVP contains the
- contents of the RADIUS Acct-Session-Id attribute.
-
-9.8.5. Acct-Multi-Session-Id AVP
-
- The Acct-Multi-Session-Id AVP (AVP Code 50) is of type UTF8String,
- following the format specified in Section 8.8. The Acct-Multi-
- Session-Id AVP is used to link multiple related accounting sessions,
- where each session would have a unique Session-Id but the same Acct-
- Multi-Session-Id AVP. This AVP MAY be returned by the Diameter
- server in an authorization answer, and it MUST be used in all
- accounting messages for the given session.
-
-9.8.6. Accounting-Sub-Session-Id AVP
-
- The Accounting-Sub-Session-Id AVP (AVP Code 287) is of type
- Unsigned64 and contains the accounting sub-session identifier. The
- combination of the Session-Id and this AVP MUST be unique per sub-
- session, and the value of this AVP MUST be monotonically increased by
- one for all new sub-sessions. The absence of this AVP implies no
- sub-sessions are in use, with the exception of an Accounting-Request
- whose Accounting-Record-Type is set to STOP_RECORD. A STOP_RECORD
- message with no Accounting-Sub-Session-Id AVP present will signal the
- termination of all sub-sessions for a given Session-Id.
-
-
-
-Fajardo, et al. Standards Track [Page 131]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-9.8.7. Accounting-Realtime-Required AVP
-
- The Accounting-Realtime-Required AVP (AVP Code 483) is of type
- Enumerated and is sent from the Diameter home authorization server to
- the Diameter client or in the Accounting-Answer from the accounting
- server. The client uses information in this AVP to decide what to do
- if the sending of accounting records to the accounting server has
- been temporarily prevented due to, for instance, a network problem.
-
- DELIVER_AND_GRANT 1
-
- The AVP with Value field set to DELIVER_AND_GRANT means that the
- service MUST only be granted as long as there is a connection to
- an accounting server. Note that the set of alternative accounting
- servers are treated as one server in this sense. Having to move
- the accounting record stream to a backup server is not a reason to
- discontinue the service to the user.
-
- GRANT_AND_STORE 2
-
- The AVP with Value field set to GRANT_AND_STORE means that service
- SHOULD be granted if there is a connection, or as long as records
- can still be stored as described in Section 9.4.
-
- This is the default behavior if the AVP isn't included in the
- reply from the authorization server.
-
- GRANT_AND_LOSE 3
-
- The AVP with Value field set to GRANT_AND_LOSE means that service
- SHOULD be granted even if the records cannot be delivered or
- stored.
-
-10. AVP Occurrence Tables
-
- The following tables present the AVPs defined in this document and
- specify in which Diameter messages they MAY or MAY NOT be present.
- AVPs that occur only inside a Grouped AVP are not shown in these
- tables.
-
- The tables use the following symbols:
-
- 0 The AVP MUST NOT be present in the message.
-
- 0+ Zero or more instances of the AVP MAY be present in the
- message.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 132]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- 0-1 Zero or one instance of the AVP MAY be present in the message.
- It is considered an error if there are more than one instance
- of the AVP.
-
- 1 One instance of the AVP MUST be present in the message.
-
- 1+ At least one instance of the AVP MUST be present in the
- message.
-
-10.1. Base Protocol Command AVP Table
-
- The table in this section is limited to the non-Accounting Command
- Codes defined in this specification.
-
- +-----------------------------------------------+
- | Command Code |
- +---+---+---+---+---+---+---+---+---+---+---+---+
- Attribute Name |CER|CEA|DPR|DPA|DWR|DWA|RAR|RAA|ASR|ASA|STR|STA|
- --------------------+---+---+---+---+---+---+---+---+---+---+---+---+
- Acct-Interim- |0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 |
- Interval | | | | | | | | | | | | |
- Accounting-Realtime-|0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 |
- Required | | | | | | | | | | | | |
- Acct-Application-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Auth-Application-Id |0+ |0+ |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 |
- Auth-Grace-Period |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Auth-Request-Type |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Auth-Session-State |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Authorization- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Lifetime | | | | | | | | | | | | |
- Class |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0+ |0+ |
- Destination-Host |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |0-1|0 |
- Destination-Realm |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 |
- Disconnect-Cause |0 |0 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Error-Message |0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|
- Error-Reporting-Host|0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
- Failed-AVP |0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|
- Firmware-Revision |0-1|0-1|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Host-IP-Address |1+ |1+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Inband-Security-Id |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Multi-Round-Time-Out|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 133]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Origin-Host |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |
- Origin-Realm |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |
- Origin-State-Id |0-1|0-1|0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|0-1|0-1|
- Product-Name |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Proxy-Info |0 |0 |0 |0 |0 |0 |0+ |0+ |0+ |0+ |0+ |0+ |
- Redirect-Host |0 |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |
- Redirect-Host-Usage |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
- Redirect-Max-Cache- |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1|
- Time | | | | | | | | | | | | |
- Result-Code |0 |1 |0 |1 |0 |1 |0 |1 |0 |1 |0 |1 |
- Re-Auth-Request-Type|0 |0 |0 |0 |0 |0 |1 |0 |0 |0 |0 |0 |
- Route-Record |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |0 |
- Session-Binding |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Session-Id |0 |0 |0 |0 |0 |0 |1 |1 |1 |1 |1 |1 |
- Session-Server- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Failover | | | | | | | | | | | | |
- Session-Timeout |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Supported-Vendor-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Termination-Cause |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |1 |0 |
- User-Name |0 |0 |0 |0 |0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|
- Vendor-Id |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Vendor-Specific- |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
- Application-Id | | | | | | | | | | | | |
- --------------------+---+---+---+---+---+---+---+---+---+---+---+---+
-
-10.2. Accounting AVP Table
-
- The table in this section is used to represent which AVPs defined in
- this document are to be present in the Accounting messages. These
- AVP occurrence requirements are guidelines, which may be expanded,
- and/or overridden by application-specific requirements in the
- Diameter applications documents.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 134]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- +-----------+
- | Command |
- | Code |
- +-----+-----+
- Attribute Name | ACR | ACA |
- ------------------------------+-----+-----+
- Acct-Interim-Interval | 0-1 | 0-1 |
- Acct-Multi-Session-Id | 0-1 | 0-1 |
- Accounting-Record-Number | 1 | 1 |
- Accounting-Record-Type | 1 | 1 |
- Acct-Session-Id | 0-1 | 0-1 |
- Accounting-Sub-Session-Id | 0-1 | 0-1 |
- Accounting-Realtime-Required | 0-1 | 0-1 |
- Acct-Application-Id | 0-1 | 0-1 |
- Auth-Application-Id | 0 | 0 |
- Class | 0+ | 0+ |
- Destination-Host | 0-1 | 0 |
- Destination-Realm | 1 | 0 |
- Error-Reporting-Host | 0 | 0+ |
- Event-Timestamp | 0-1 | 0-1 |
- Failed-AVP | 0 | 0-1 |
- Origin-Host | 1 | 1 |
- Origin-Realm | 1 | 1 |
- Proxy-Info | 0+ | 0+ |
- Route-Record | 0+ | 0 |
- Result-Code | 0 | 1 |
- Session-Id | 1 | 1 |
- Termination-Cause | 0 | 0 |
- User-Name | 0-1 | 0-1 |
- Vendor-Specific-Application-Id| 0-1 | 0-1 |
- ------------------------------+-----+-----+
-
-11. IANA Considerations
-
- This section provides guidance to the Internet Assigned Numbers
- Authority (IANA) regarding registration of values related to the
- Diameter protocol, in accordance with [RFC5226]. Existing IANA
- registries and assignments put in place by RFC 3588 remain the same
- unless explicitly updated or deprecated in this section.
-
-11.1. AVP Header
-
- As defined in Section 4, the AVP header contains three fields that
- require IANA namespace management: the AVP Code, Vendor-ID, and Flags
- fields.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 135]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-11.1.1. AVP Codes
-
- There are multiple namespaces. Vendors can have their own AVP Codes
- namespace that will be identified by their Vendor-ID (also known as
- Enterprise-Number), and they control the assignments of their vendor-
- specific AVP Codes within their own namespace. The absence of a
- Vendor-ID or a Vendor-ID value of zero (0) identifies the IETF AVP
- Codes namespace, which is under IANA control. The AVP Codes and
- sometimes possible values in an AVP are controlled and maintained by
- IANA. AVP Code 0 is not used. AVP Codes 1-255 are managed
- separately as RADIUS Attribute Types. Where a Vendor-Specific AVP is
- implemented by more than one vendor, allocation of global AVPs should
- be encouraged instead.
-
- AVPs may be allocated following Expert Review (by a Designated
- Expert) with Specification Required [RFC5226]. A block allocation
- (release of more than three AVPs at a time for a given purpose)
- requires IETF Review [RFC5226].
-
-11.1.2. AVP Flags
-
- Section 4.1 describes the existing AVP Flags. The remaining bits can
- only be assigned via a Standards Action [RFC5226].
-
-11.2. Diameter Header
-
-11.2.1. Command Codes
-
- For the Diameter header, the Command Code namespace allocation has
- changed. The new allocation rules are as follows:
-
- The Command Code values 256 - 8,388,607 (0x100 to 0x7fffff) are
- for permanent, standard commands, allocated by IETF Review
- [RFC5226].
-
- The values 8,388,608 - 16,777,213 (0x800000 - 0xfffffd) are
- reserved for vendor-specific Command Codes, to be allocated on a
- First Come, First Served basis by IANA [RFC5226]. The request to
- IANA for a Vendor-Specific Command Code SHOULD include a reference
- to a publicly available specification that documents the command
- in sufficient detail to aid in interoperability between
- independent implementations. If the specification cannot be made
- publicly available, the request for a vendor-specific Command Code
- MUST include the contact information of persons and/or entities
- responsible for authoring and maintaining the command.
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 136]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- The values 16,777,214 and 16,777,215 (hexadecimal values 0xfffffe
- - 0xffffff) are reserved for experimental commands. As these
- codes are only for experimental and testing purposes, no guarantee
- is made for interoperability between Diameter peers using
- experimental commands.
-
-11.2.2. Command Flags
-
- Section 3 describes the existing Command Flags field. The remaining
- bits can only be assigned via a Standards Action [RFC5226].
-
-11.3. AVP Values
-
- For AVP values, the Experimental-Result-Code AVP value allocation has
- been added; see Section 11.3.1. The old AVP value allocation rule,
- IETF Consensus, has been updated to IETF Review as per [RFC5226], and
- affected AVPs are listed as reminders.
-
-11.3.1. Experimental-Result-Code AVP
-
- Values for this AVP are purely local to the indicated vendor, and no
- IANA registry is maintained for them.
-
-11.3.2. Result-Code AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.3. Accounting-Record-Type AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.4. Termination-Cause AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.5. Redirect-Host-Usage AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.6. Session-Server-Failover AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.7. Session-Binding AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 137]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-11.3.8. Disconnect-Cause AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.9. Auth-Request-Type AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.10. Auth-Session-State AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.11. Re-Auth-Request-Type AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.12. Accounting-Realtime-Required AVP Values
-
- New values are available for assignment via IETF Review [RFC5226].
-
-11.3.13. Inband-Security-Id AVP (code 299)
-
- The use of this AVP has been deprecated.
-
-11.4. _diameters Service Name and Port Number Registration
-
- IANA has registered the "_diameters" service name and assigned port
- numbers for TLS/TCP and DTLS/SCTP according to the guidelines given
- in [RFC6335].
-
- Service Name: _diameters
-
- Transport Protocols: TCP, SCTP
-
- Assignee: IESG &lt;[email protected]>
-
- Contact: IETF Chair &lt;[email protected]>
-
- Description: Diameter over TLS/TCP and DTLS/SCTP
-
- Reference: RFC 6733
-
- Port Number: 5868, from the User Range
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 138]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-11.5. SCTP Payload Protocol Identifiers
-
- Two SCTP payload protocol identifiers have been registered in the
- SCTP Payload Protocol Identifiers registry:
-
-
- Value | SCTP Payload Protocol Identifier
- -------|-----------------------------------
- 46 | Diameter in a SCTP DATA chunk
- 47 | Diameter in a DTLS/SCTP DATA chunk
-
-
-11.6. S-NAPTR Parameters
-
- The following tag has been registered in the S-NAPTR Application
- Protocol Tags registry:
-
- Tag | Protocol
- -------------------|---------
- diameter.dtls.sctp | DTLS/SCTP
-
-12. Diameter Protocol-Related Configurable Parameters
-
- This section contains the configurable parameters that are found
- throughout this document:
-
- Diameter Peer
-
- A Diameter entity MAY communicate with peers that are statically
- configured. A statically configured Diameter peer would require
- that either the IP address or the fully qualified domain name
- (FQDN) be supplied, which would then be used to resolve through
- DNS.
-
- Routing Table
-
- A Diameter proxy server routes messages based on the realm portion
- of a Network Access Identifier (NAI). The server MUST have a
- table of Realm Names, and the address of the peer to which the
- message must be forwarded. The routing table MAY also include a
- "default route", which is typically used for all messages that
- cannot be locally processed.
-
- Tc timer
-
- The Tc timer controls the frequency that transport connection
- attempts are done to a peer with whom no active transport
- connection exists. The recommended value is 30 seconds.
-
-
-
-Fajardo, et al. Standards Track [Page 139]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-13. Security Considerations
-
- The Diameter base protocol messages SHOULD be secured by using TLS
- [RFC5246] or DTLS/SCTP [RFC6083]. Additional security mechanisms
- such as IPsec [RFC4301] MAY also be deployed to secure connections
- between peers. However, all Diameter base protocol implementations
- MUST support the use of TLS/TCP and DTLS/SCTP, and the Diameter
- protocol MUST NOT be used without one of TLS, DTLS, or IPsec.
-
- If a Diameter connection is to be protected via TLS/TCP and DTLS/SCTP
- or IPsec, then TLS/TCP and DTLS/SCTP or IPsec/IKE SHOULD begin prior
- to any Diameter message exchange. All security parameters for TLS/
- TCP and DTLS/SCTP or IPsec are configured independent of the Diameter
- protocol. All Diameter messages will be sent through the TLS/TCP and
- DTLS/SCTP or IPsec connection after a successful setup.
-
- For TLS/TCP and DTLS/SCTP connections to be established in the open
- state, the CER/CEA exchange MUST include an Inband-Security-ID AVP
- with a value of TLS/TCP and DTLS/SCTP. The TLS/TCP and DTLS/SCTP
- handshake will begin when both ends successfully reach the open
- state, after completion of the CER/CEA exchange. If the TLS/TCP and
- DTLS/SCTP handshake is successful, all further messages will be sent
- via TLS/TCP and DTLS/SCTP. If the handshake fails, both ends MUST
- move to the closed state. See Section 13.1 for more details.
-
-13.1. TLS/TCP and DTLS/SCTP Usage
-
- Diameter nodes using TLS/TCP and DTLS/SCTP for security MUST mutually
- authenticate as part of TLS/TCP and DTLS/SCTP session establishment.
- In order to ensure mutual authentication, the Diameter node acting as
- the TLS/TCP and DTLS/SCTP server MUST request a certificate from the
- Diameter node acting as TLS/TCP and DTLS/SCTP client, and the
- Diameter node acting as the TLS/TCP and DTLS/SCTP client MUST be
- prepared to supply a certificate on request.
-
- Diameter nodes MUST be able to negotiate the following TLS/TCP and
- DTLS/SCTP cipher suites:
-
- TLS_RSA_WITH_RC4_128_MD5
- TLS_RSA_WITH_RC4_128_SHA
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
-
- Diameter nodes SHOULD be able to negotiate the following TLS/TCP and
- DTLS/SCTP cipher suite:
-
- TLS_RSA_WITH_AES_128_CBC_SHA
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 140]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- Note that it is quite possible that support for the
- TLS_RSA_WITH_AES_128_CBC_SHA cipher suite will be REQUIRED at some
- future date. Diameter nodes MAY negotiate other TLS/TCP and DTLS/
- SCTP cipher suites.
-
- If public key certificates are used for Diameter security (for
- example, with TLS), the value of the expiration times in the routing
- and peer tables MUST NOT be greater than the expiry time in the
- relevant certificates.
-
-13.2. Peer-to-Peer Considerations
-
- As with any peer-to-peer protocol, proper configuration of the trust
- model within a Diameter peer is essential to security. When
- certificates are used, it is necessary to configure the root
- certificate authorities trusted by the Diameter peer. These root CAs
- are likely to be unique to Diameter usage and distinct from the root
- CAs that might be trusted for other purposes such as Web browsing.
- In general, it is expected that those root CAs will be configured so
- as to reflect the business relationships between the organization
- hosting the Diameter peer and other organizations. As a result, a
- Diameter peer will typically not be configured to allow connectivity
- with any arbitrary peer. With certificate authentication, Diameter
- peers may not be known beforehand and therefore peer discovery may be
- required.
-
-13.3. AVP Considerations
-
- Diameter AVPs often contain security-sensitive data; for example,
- user passwords and location data, network addresses and cryptographic
- keys. The following AVPs defined in this document are considered to
- be security-sensitive:
-
- o Acct-Interim-Interval
-
- o Accounting-Realtime-Required
-
- o Acct-Multi-Session-Id
-
- o Accounting-Record-Number
-
- o Accounting-Record-Type
-
- o Accounting-Session-Id
-
- o Accounting-Sub-Session-Id
-
- o Class
-
-
-
-Fajardo, et al. Standards Track [Page 141]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- o Session-Id
-
- o Session-Binding
-
- o Session-Server-Failover
-
- o User-Name
-
- Diameter messages containing these or any other AVPs considered to be
- security-sensitive MUST only be sent protected via mutually
- authenticated TLS or IPsec. In addition, those messages MUST NOT be
- sent via intermediate nodes unless there is end-to-end security
- between the originator and recipient or the originator has locally
- trusted configuration that indicates that end-to-end security is not
- needed. For example, end-to-end security may not be required in the
- case where an intermediary node is known to be operated as part of
- the same administrative domain as the endpoints so that an ability to
- successfully compromise the intermediary would imply a high
- probability of being able to compromise the endpoints as well. Note
- that no end-to-end security mechanism is specified in this document.
-
-14. References
-
-14.1. Normative References
-
- [FLOATPOINT]
- Institute of Electrical and Electronics Engineers, "IEEE
- Standard for Binary Floating-Point Arithmetic, ANSI/IEEE
- Standard 754-1985", August 1985.
-
- [IANAADFAM]
- IANA, "Address Family Numbers",
- &lt;http://www.iana.org/assignments/address-family-numbers>.
-
- [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791,
- September 1981.
-
- [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
- RFC 793, September 1981.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode
- for Internationalized Domain Names in Applications
- (IDNA)", RFC 3492, March 2003.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 142]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- [RFC3539] Aboba, B. and J. Wood, "Authentication, Authorization and
- Accounting (AAA) Transport Profile", RFC 3539, June 2003.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [RFC3958] Daigle, L. and A. Newton, "Domain-Based Application
- Service Location Using SRV RRs and the Dynamic Delegation
- Discovery Service (DDDS)", RFC 3958, January 2005.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66,
- RFC 3986, January 2005.
-
- [RFC4004] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., and
- P. McCann, "Diameter Mobile IPv4 Application", RFC 4004,
- August 2005.
-
- [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton,
- "Diameter Network Access Server Application", RFC 4005,
- August 2005.
-
- [RFC4006] Hakala, H., Mattila, L., Koskinen, J-P., Stura, M., and J.
- Loughney, "Diameter Credit-Control Application", RFC 4006,
- August 2005.
-
- [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
- Requirements for Security", BCP 106, RFC 4086, June 2005.
-
- [RFC4282] Aboba, B., Beadles, M., Arkko, J., and P. Eronen, "The
- Network Access Identifier", RFC 4282, December 2005.
-
- [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 4291, February 2006.
-
- [RFC4960] Stewart, R., "Stream Control Transmission Protocol",
- RFC 4960, September 2007.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
- (TLS) Protocol Version 1.2", RFC 5246, August 2008.
-
-
-
-
-Fajardo, et al. Standards Track [Page 143]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
- Housley, R., and W. Polk, "Internet X.509 Public Key
- Infrastructure Certificate and Certificate Revocation List
- (CRL) Profile", RFC 5280, May 2008.
-
- [RFC5729] Korhonen, J., Jones, M., Morand, L., and T. Tsou,
- "Clarifications on the Routing of Diameter Requests Based
- on the Username and the Realm", RFC 5729, December 2009.
-
- [RFC5890] Klensin, J., "Internationalized Domain Names for
- Applications (IDNA): Definitions and Document Framework",
- RFC 5890, August 2010.
-
- [RFC5891] Klensin, J., "Internationalized Domain Names in
- Applications (IDNA): Protocol", RFC 5891, August 2010.
-
- [RFC6083] Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram
- Transport Layer Security (DTLS) for Stream Control
- Transmission Protocol (SCTP)", RFC 6083, January 2011.
-
- [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
- Security Version 1.2", RFC 6347, January 2012.
-
- [RFC6408] Jones, M., Korhonen, J., and L. Morand, "Diameter
- Straightforward-Naming Authority Pointer (S-NAPTR) Usage",
- RFC 6408, November 2011.
-
-14.2. Informative References
-
- [ENTERPRISE] IANA, "SMI Network Management Private Enterprise
- Codes",
- &lt;http://www.iana.org/assignments/enterprise-numbers>.
-
- [IANATCV] IANA, "Termination-Cause AVP Values (code 295)",
- &lt;http://www.iana.org/assignments/aaa-parameters/
- aaa-parameters.xml#aaa-parameters-16>.
-
- [RFC1492] Finseth, C., "An Access Control Protocol, Sometimes
- Called TACACS", RFC 1492, July 1993.
-
- [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)",
- STD 51, RFC 1661, July 1994.
-
- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC:
- Keyed-Hashing for Message Authentication", RFC 2104,
- February 1997.
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 144]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR
- for specifying the location of services (DNS SRV)",
- RFC 2782, February 2000.
-
- [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson,
- "Remote Authentication Dial In User Service (RADIUS)",
- RFC 2865, June 2000.
-
- [RFC2866] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000.
-
- [RFC2869] Rigney, C., Willats, W., and P. Calhoun, "RADIUS
- Extensions", RFC 2869, June 2000.
-
- [RFC2881] Mitton, D. and M. Beadles, "Network Access Server
- Requirements Next Generation (NASREQNG) NAS Model",
- RFC 2881, July 2000.
-
- [RFC2975] Aboba, B., Arkko, J., and D. Harrington, "Introduction
- to Accounting Management", RFC 2975, October 2000.
-
- [RFC2989] Aboba, B., Calhoun, P., Glass, S., Hiller, T., McCann,
- P., Shiino, H., Walsh, P., Zorn, G., Dommety, G.,
- Perkins, C., Patil, B., Mitton, D., Manning, S.,
- Beadles, M., Chen, X., Sivalingham, S., Hameed, A.,
- Munson, M., Jacobs, S., Lim, B., Hirschman, B., Hsu,
- R., Koo, H., Lipford, M., Campbell, E., Xu, Y., Baba,
- S., and E. Jaques, "Criteria for Evaluating AAA
- Protocols for Network Access", RFC 2989, November 2000.
-
- [RFC3162] Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6",
- RFC 3162, August 2001.
-
- [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and
- H. Levkowetz, "Extensible Authentication Protocol
- (EAP)", RFC 3748, June 2004.
-
- [RFC4301] Kent, S. and K. Seo, "Security Architecture for the
- Internet Protocol", RFC 4301, December 2005.
-
- [RFC4690] Klensin, J., Faltstrom, P., Karp, C., and IAB, "Review
- and Recommendations for Internationalized Domain Names
- (IDNs)", RFC 4690, September 2006.
-
- [RFC5176] Chiba, M., Dommety, G., Eklund, M., Mitton, D., and B.
- Aboba, "Dynamic Authorization Extensions to Remote
- Authentication Dial In User Service (RADIUS)",
- RFC 5176, January 2008.
-
-
-
-
-Fajardo, et al. Standards Track [Page 145]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461,
- February 2009.
-
- [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch,
- "Network Time Protocol Version 4: Protocol and
- Algorithms Specification", RFC 5905, June 2010.
-
- [RFC5927] Gont, F., "ICMP Attacks against TCP", RFC 5927,
- July 2010.
-
- [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and
- S. Cheshire, "Internet Assigned Numbers Authority
- (IANA) Procedures for the Management of the Service
- Name and Transport Protocol Port Number Registry",
- BCP 165, RFC 6335, August 2011.
-
- [RFC6737] Kang, J. and G. Zorn, "The Diameter Capabilities Update
- Application", RFC 6737, October 2012.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fajardo, et al. Standards Track [Page 146]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
-Appendix A. Acknowledgements
-
-A.1. This Document
-
- The authors would like to thank the following people that have
- provided proposals and contributions to this document:
-
- To Vishnu Ram and Satendra Gera for their contributions on
- capabilities updates, predictive loop avoidance, as well as many
- other technical proposals. To Tolga Asveren for his insights and
- contributions on almost all of the proposed solutions incorporated
- into this document. To Timothy Smith for helping on the capabilities
- Update and other topics. To Tony Zhang for providing fixes to
- loopholes on composing Failed-AVPs as well as many other issues and
- topics. To Jan Nordqvist for clearly stating the usage of
- Application Ids. To Anders Kristensen for providing needed technical
- opinions. To David Frascone for providing invaluable review of the
- document. To Mark Jones for providing clarifying text on vendor
- command codes and other vendor-specific indicators. To Victor
- Pascual and Sebastien Decugis for new text and recommendations on
- SCTP/DTLS. To Jouni Korhonen for taking over the editing task and
- resolving last bits from versions 27 through 29.
-
- Special thanks to the Diameter extensibility design team, which
- helped resolve the tricky question of mandatory AVPs and ABNF
- semantics. The members of this team are as follows:
-
- Avi Lior, Jari Arkko, Glen Zorn, Lionel Morand, Mark Jones, Tolga
- Asveren, Jouni Korhonen, and Glenn McGregor.
-
- Special thanks also to people who have provided invaluable comments
- and inputs especially in resolving controversial issues:
-
- Glen Zorn, Yoshihiro Ohba, Marco Stura, Stephen Farrel, Pete Resnick,
- Peter Saint-Andre, Robert Sparks, Krishna Prasad, Sean Turner, Barry
- Leiba, and Pasi Eronen.
-
- Finally, we would like to thank the original authors of this
- document:
-
- Pat Calhoun, John Loughney, Jari Arkko, Erik Guttman, and Glen Zorn.
-
- Their invaluable knowledge and experience has given us a robust and
- flexible AAA protocol that many people have seen great value in
- adopting. We greatly appreciate their support and stewardship for
- the continued improvements of Diameter as a protocol. We would also
- like to extend our gratitude to folks aside from the authors who have
-
-
-
-
-Fajardo, et al. Standards Track [Page 147]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- assisted and contributed to the original version of this document.
- Their efforts significantly contributed to the success of Diameter.
-
-A.2. RFC 3588
-
- The authors would like to thank Nenad Trifunovic, Tony Johansson and
- Pankaj Patel for their participation in the pre-IETF Document Reading
- Party. Allison Mankin, Jonathan Wood, and Bernard Aboba provided
- invaluable assistance in working out transport issues and this was
- also the case with Steven Bellovin in the security area.
-
- Paul Funk and David Mitton were instrumental in getting the Peer
- State Machine correct, and our deep thanks go to them for their time.
-
- Text in this document was also provided by Paul Funk, Mark Eklund,
- Mark Jones, and Dave Spence. Jacques Caron provided many great
- comments as a result of a thorough review of the spec.
-
- The authors would also like to acknowledge the following people for
- their contribution in the development of the Diameter protocol:
-
- Allan C. Rubens, Haseeb Akhtar, William Bulley, Stephen Farrell,
- David Frascone, Daniel C. Fox, Lol Grant, Ignacio Goyret, Nancy
- Greene, Peter Heitman, Fredrik Johansson, Mark Jones, Martin Julien,
- Bob Kopacz, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin,
- Kenneth Peirce, John Schnizlein, Sumit Vakil, John R. Vollbrecht, and
- Jeff Weisberg.
-
- Finally, Pat Calhoun would like to thank Sun Microsystems since most
- of the effort put into this document was done while he was in their
- employ.
-
-Appendix B. S-NAPTR Example
-
- As an example, consider a client that wishes to resolve aaa:
- ex1.example.com. The client performs a NAPTR query for that domain,
- and the following NAPTR records are returned:
-
- ;; order pref flags service regexp replacement
- IN NAPTR 50 50 "s" "aaa:diameter.tls.tcp" ""
- _diameter._tls.ex1.example.com
- IN NAPTR 100 50 "s" "aaa:diameter.tcp" ""
- _aaa._tcp.ex1.example.com
- IN NAPTR 150 50 "s" "aaa:diameter.sctp" ""
- _diameter._sctp.ex1.example.com
-
- This indicates that the server supports TLS, TCP, and SCTP in that
- order. If the client supports TLS, TLS will be used, targeted to a
-
-
-
-Fajardo, et al. Standards Track [Page 148]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- host determined by an SRV lookup of _diameter._tls.ex1.example.com.
- That lookup would return:
-
- ;; Priority Weight Port Target
- IN SRV 0 1 5060 server1.ex1.example.com
- IN SRV 0 2 5060 server2.ex1.example.com
-
- As an alternative example, a client that wishes to resolve aaa:
- ex2.example.com. The client performs a NAPTR query for that domain,
- and the following NAPTR records are returned:
-
- ;; order pref flags service regexp replacement
- IN NAPTR 150 50 "a" "aaa:diameter.tls.tcp" ""
- server1.ex2.example.com
- IN NAPTR 150 50 "a" "aaa:diameter.tls.tcp" ""
- server2.ex2.example.com
-
- This indicates that the server supports TCP available at the returned
- host names.
-
-Appendix C. Duplicate Detection
-
- As described in Section 9.4, accounting record duplicate detection is
- based on session identifiers. Duplicates can appear for various
- reasons:
-
- o Failover to an alternate server. Where close to real-time
- performance is required, failover thresholds need to be kept low.
- This may lead to an increased likelihood of duplicates. Failover
- can occur at the client or within Diameter agents.
-
- o Failure of a client or agent after sending a record from non-
- volatile memory, but prior to receipt of an application-layer ACK
- and deletion of the record to be sent. This will result in
- retransmission of the record soon after the client or agent has
- rebooted.
-
- o Duplicates received from RADIUS gateways. Since the
- retransmission behavior of RADIUS is not defined within [RFC2865],
- the likelihood of duplication will vary according to the
- implementation.
-
- o Implementation problems and misconfiguration.
-
- The T flag is used as an indication of an application-layer
- retransmission event, e.g., due to failover to an alternate server.
- It is defined only for request messages sent by Diameter clients or
- agents. For instance, after a reboot, a client may not know whether
-
-
-
-Fajardo, et al. Standards Track [Page 149]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- it has already tried to send the accounting records in its non-
- volatile memory before the reboot occurred. Diameter servers MAY use
- the T flag as an aid when processing requests and detecting duplicate
- messages. However, servers that do this MUST ensure that duplicates
- are found even when the first transmitted request arrives at the
- server after the retransmitted request. It can be used only in cases
- where no answer has been received from the server for a request and
- the request is sent again, (e.g., due to a failover to an alternate
- peer, due to a recovered primary peer or due to a client re-sending a
- stored record from non-volatile memory such as after reboot of a
- client or agent).
-
- In some cases, the Diameter accounting server can delay the duplicate
- detection and accounting record processing until a post-processing
- phase takes place. At that time records are likely to be sorted
- according to the included User-Name and duplicate elimination is easy
- in this case. In other situations, it may be necessary to perform
- real-time duplicate detection, such as when credit limits are imposed
- or real-time fraud detection is desired.
-
- In general, only generation of duplicates due to failover or re-
- sending of records in non-volatile storage can be reliably detected
- by Diameter clients or agents. In such cases, the Diameter client or
- agents can mark the message as a possible duplicate by setting the T
- flag. Since the Diameter server is responsible for duplicate
- detection, it can choose whether or not to make use of the T flag, in
- order to optimize duplicate detection. Since the T flag does not
- affect interoperability, and it may not be needed by some servers,
- generation of the T flag is REQUIRED for Diameter clients and agents,
- but it MAY be implemented by Diameter servers.
-
- As an example, it can be usually be assumed that duplicates appear
- within a time window of longest recorded network partition or device
- fault, perhaps a day. So only records within this time window need
- to be looked at in the backward direction. Secondly, hashing
- techniques or other schemes, such as the use of the T flag in the
- received messages, may be used to eliminate the need to do a full
- search even in this set except for rare cases.
-
- The following is an example of how the T flag may be used by the
- server to detect duplicate requests.
-
- A Diameter server MAY check the T flag of the received message to
- determine if the record is a possible duplicate. If the T flag is
- set in the request message, the server searches for a duplicate
- within a configurable duplication time window backward and
- forward. This limits database searching to those records where
- the T flag is set. In a well-run network, network partitions and
-
-
-
-Fajardo, et al. Standards Track [Page 150]
-
-RFC 6733 Diameter Base Protocol October 2012
-
-
- device faults will presumably be rare events, so this approach
- represents a substantial optimization of the duplicate detection
- process. During failover, it is possible for the original record
- to be received after the T-flag-marked record, due to differences
- in network delays experienced along the path by the original and
- duplicate transmissions. The likelihood of this occurring
- increases as the failover interval is decreased. In order to be
- able to detect duplicates that are out of order, the Diameter
- server should use backward and forward time windows when
- performing duplicate checking for the T-flag-marked request. For
- example, in order to allow time for the original record to exit
- the network and be recorded by the accounting server, the Diameter
- server can delay processing records with the T flag set until a
- time period TIME_WAIT + RECORD_PROCESSING_TIME has elapsed after
- the closing of the original transport connection. After this time
- period, it may check the T-flag-marked records against the
- database with relative assurance that the original records, if
- sent, have been received and recorded.
-
-Appendix D. Internationalized Domain Names
-
- To be compatible with the existing DNS infrastructure and simplify
- host and domain name comparison, Diameter identities (FQDNs) are
- represented in ASCII form. This allows the Diameter protocol to fall
- in-line with the DNS strategy of being transparent from the effects
- of Internationalized Domain Names (IDNs) by following the
- recommendations in [RFC4690] and [RFC5890]. Applications that
- provide support for IDNs outside of the Diameter protocol but
- interacting with it SHOULD use the representation and conversion
- framework described in [RFC5890], [RFC5891], and [RFC3492].
-</pre>
-
-</section>
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index 6ca280c52b..9f84eeb9fd 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -27,7 +27,8 @@
<erlref>
<header>
<copyright>
-<year>2011</year><year>2016</year>
+<year>2011</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -99,7 +100,9 @@ before configuring TLS capability on diameter transports.</p>
| {rport, integer()}
| {accept, Match}
| {port, integer()}
- | {fragment_timer, infinity | 0..16#FFFFFFFF}</v>
+ | {fragment_timer, infinity | 0..16#FFFFFFFF}
+ | {message_cb, &mod_eval;}
+ | {sender, boolean()}</v>
<v>SslOpt = {ssl_options, true | list()}</v>
<v>TcpOpt = term()</v>
<v>Match = &ip_address; | string() | [Match]</v>
@@ -140,6 +143,44 @@ such a message is received over the transport interface after
two successive timeouts without the reception of additional bytes.
Defaults to 1000.</p>
+<marker id="sender"/>
+<p>
+Option <c>sender</c> specifies whether or not to use a dedicated
+process for sending outgoing messages, which avoids the possibility of
+send blocking reception.
+Defaults to <c>false</c>.
+If set to <c>true</c> then a <c>message_cb</c> that avoids the
+possibility of messages being queued in the sender process without
+bound should be configured.</p>
+
+<p>
+Option <c>message_cb</c> specifies a callback that is invoked on
+incoming and outgoing messages, that can be used to implement
+flow control.
+It is applied to two arguments: an atom indicating the
+reason for the callback (<c>send</c>, <c>recv</c>, or <c>ack</c> after
+a completed send), and the message in question (binary() on
+<c>recv</c>, binary() or diameter_packet record on <c>send</c> or
+<c>ack</c>, or <c>false</c> on <c>ack</c> when an incoming request has
+been discarded).
+It should return a list of actions and a new callback as
+tail; eg. <c>[fun cb/3, State]</c>.
+Valid actions are the atoms <c>send</c> or <c>recv</c>, to
+cause a following message-valued action to be sent/received,
+a message to send/receive (binary() or
+diameter_packet record), or a boolean() to enable/disable reading on
+the socket.
+More than one <c>send</c>/<c>recv</c>/message sequence can be
+returned from the same callback, and an initial
+<c>send</c>/<c>recv</c> can be omitted if the same as the value passed
+as the callback's first argument.
+Reading is initially enabled, and returning <c>false</c> does not
+imply there cannot be subsequent <c>recv</c> callbacks since
+messages may already have been read.
+An empty tail is equivalent to the prevailing callback.
+Defaults to a callback equivalent to <c>fun(ack, _) -> []; (_, Msg) ->
+[Msg] end</c>.</p>
+
<p>
Remaining options are any accepted by &ssl_connect3; or
&gen_tcp_connect3; for
@@ -170,14 +211,11 @@ that will not be forthcoming, which will eventually cause the RFC 3539
watchdog to take down the connection.</p>
<p>
-If an <c>ip</c> option is not specified then the first element of a
-non-empty <c>Host-IP-Address</c> list in <c>Svc</c> provides the local
-IP address.
-If neither is specified then the default address selected by &gen_tcp;
-is used.
-In all cases, the selected address is either returned from
-&start; or passed in a <c>connected</c> message over the transport
-interface.</p>
+The first element of a non-empty <c>Host-IP-Address</c> list in
+<c>Svc</c> provides the local IP address if an <c>ip</c> option is not
+specified.
+The local address is either returned from&start; or passed in a
+<c>connected</c> message over the transport interface.</p>
</desc>
</func>
diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk
index cb4f88a375..4c1297f6cc 100644
--- a/lib/diameter/doc/src/files.mk
+++ b/lib/diameter/doc/src/files.mk
@@ -2,7 +2,7 @@
# %CopyrightBegin%
#
-# Copyright Ericsson AB 2010-2016. All Rights Reserved.
+# Copyright Ericsson AB 2010-2017. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -40,8 +40,7 @@ XML_PART_FILES = \
user_man.xml
XML_EXTRA_FILES = \
- seealso.ent \
- diameter_soc_rfc6733.xml
+ seealso.ent
XML_CHAPTER_FILES = \
diameter_intro.xml \
diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml
index 70e1880be5..fa1be39b5b 100644
--- a/lib/diameter/doc/src/notes.xml
+++ b/lib/diameter/doc/src/notes.xml
@@ -11,7 +11,7 @@
<header>
<copyright>
<year>2011</year>
-<year>2016</year>
+<year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -43,6 +43,354 @@ first.</p>
<!-- ===================================================================== -->
+<section><title>diameter 2.1.4</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix close of diameter_tcp/sctp listening socket at
+ diameter:remove_transport/2, that was broken in diameter
+ 2.1. A reconfigured transport could not listen on the
+ same endpoint as a result.</p>
+ <p>
+ Own Id: OTP-14839</p>
+ </item>
+ <item>
+ <p>
+ Fix handling of SUSPECT connections at service
+ termination. A connection with this watchdog state caused
+ diameter_service:terminate/2 to fail.</p>
+ <p>
+ Own Id: OTP-14947 Aux Id: ERIERL-124 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 2.1.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix documentation typo: peer_down/3 was written where
+ peer_down/3 was intended.</p>
+ <p>
+ Own Id: OTP-14805</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 2.1.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ A fault introduced in diameter 2.1 could cause decode
+ errors to be ignored in AVPs following the header of a
+ Grouped AVP.</p>
+ <p>
+ Own Id: OTP-14684 Aux Id: ERIERL-85 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 2.1.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ An inadvertently removed monitor in diameter 2.1 caused
+ the ets table diameter_reg to leak entries, and caused
+ service restart and more to fail.</p>
+ <p>
+ Own Id: OTP-14668 Aux Id: ERIERL-83 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 2.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix handling of Proxy-Info in answer messages setting the
+ E-bit.</p>
+ <p>
+ RFC 6733 requires that Proxy-Info AVPs in an incoming
+ request be echoed in an outgoing answer. This was not
+ done in answers formulated by diameter; for example, as a
+ result of a handle_request callback having returned an
+ 'answer-message' or protocol_error tuple.</p>
+ <p>
+ Own Id: OTP-9869</p>
+ </item>
+ <item>
+ <p>
+ React to nodeup/nodedown when sharing peer connections.</p>
+ <p>
+ Service configuration share_peers and use_shared_peers
+ did not respond to the coming and going of remote nodes.</p>
+ <p>
+ Own Id: OTP-14011</p>
+ </item>
+ <item>
+ <p>
+ Fix inappropriate message callbacks.</p>
+ <p>
+ An incoming CER or DPR was regarded as discarded,
+ resulting in a corresponding message callback (if
+ configured) in diameter_tcp/sctp.</p>
+ <p>
+ Own Id: OTP-14486</p>
+ </item>
+ <item>
+ <p>
+ Fix handling of 5009 errors (DIAMETER_AVP_OCCURS_TOO_MANY
+ TIMES).</p>
+ <p>
+ RFC 6733 says that the first AVP that exceeds the bound
+ should be reported, but the suggestions in the errors
+ field of a diameter_packet record counted AVPs from the
+ rear of the message, not the front. Additionally,
+ diameter 2.0 in OTP 20.0 broke the counting by accepting
+ one more AVP than the message grammar in question
+ allowed.</p>
+ <p>
+ Own Id: OTP-14512</p>
+ </item>
+ <item>
+ <p>
+ Match case insensitively in diameter_tcp/sctp accept
+ tuple.</p>
+ <p>
+ Matching of remote addresses when accepting connections
+ in a listening transport was case-sensitive, causing the
+ semantics to change as a consequence of (kernel)
+ OTP-13006.</p>
+ <p>
+ Own Id: OTP-14535 Aux Id: OTP-13006 </p>
+ </item>
+ <item>
+ <p>
+ Fix backwards incompatibility of remote send when sharing
+ transports.</p>
+ <p>
+ The sending of requests over a transport connection on a
+ remote node running an older version of diameter was
+ broken by diameter 2.0 in OTP 20.0.</p>
+ <p>
+ Own Id: OTP-14552</p>
+ </item>
+ <item>
+ <p>
+ Fix diameter_packet.avps decode of Grouped AVP errors in
+ Failed-AVP.</p>
+ <p>
+ Decode didn't produce a list of diameter_avp records, so
+ information about faulty component AVPs was lost.</p>
+ <p>
+ Own Id: OTP-14607</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Let unordered delivery be configured in diameter_sctp.</p>
+ <p>
+ With option {unordered, boolean() | pos_integer()}, with
+ false the default, and N equivalent to OS =&lt; N, where
+ OS is the number of outbound streams negotiated on the
+ association in question. If configured, unordered sending
+ commences upon reception of a second message, outgoing
+ messages being sent on stream 0 before this.</p>
+ <p>
+ The default false is for backwards compatibility, but
+ false or 1 should be set to follow RFC 6733's
+ recommendation on the use of unordered sending to avoid
+ head-of-line blocking. There is typically no meaningful
+ order to preserve, since the order in which outgoing
+ messages are received by a transport process isn't known
+ to the sender.</p>
+ <p>
+ Own Id: OTP-10889</p>
+ </item>
+ <item>
+ <p>
+ Complete/simplify Standards Compliance in User's Guide.</p>
+ <p>
+ Own Id: OTP-10927</p>
+ </item>
+ <item>
+ <p>
+ Add service option decode_format.</p>
+ <p>
+ To allow incoming messages to be decoded into maps or
+ lists instead of records. Messages can be presented in
+ any of the formats for encode.</p>
+ <p>
+ Decode performance has also been improved.</p>
+ <p>
+ Own Id: OTP-14511 Aux Id: OTP-14343 </p>
+ </item>
+ <item>
+ <p>
+ Add service option traffic_counters.</p>
+ <p>
+ To let message-related counters be disabled, which can be
+ a performance improvement in some usecases.</p>
+ <p>
+ Own Id: OTP-14521</p>
+ </item>
+ <item>
+ <p>
+ Allow loopback/any as local addresses in
+ diameter_tcp/sctp.</p>
+ <p>
+ The atoms were implied by documentation, but not handled
+ in code.</p>
+ <p>
+ Own Id: OTP-14544</p>
+ </item>
+ <item>
+ <p>
+ Add transport option strict_capx.</p>
+ <p>
+ To allow the RFC 6733 requirement that a transport
+ connection be closed if a message is received before
+ capabilities exchange to be relaxed.</p>
+ <p>
+ Own Id: OTP-14546</p>
+ </item>
+ <item>
+ <p>
+ Be consistent with service/transport configuration.</p>
+ <p>
+ For options for which it's meaningful, defaults values
+ for transport options can now be configured on a service.
+ This was previously the case only for an arbitrary subset
+ of options.</p>
+ <p>
+ Own Id: OTP-14555</p>
+ </item>
+ <item>
+ <p>
+ Add service/transport option avp_dictionaries.</p>
+ <p>
+ To provide better support for AVPs that are not defined
+ in the application dictionary: configuring additional
+ dictionaries in an avp_dictionaries tuple allows their
+ AVPs to be encoded/decoded in much the same fashion as
+ application AVPs.</p>
+ <p>
+ The motivation is RFC 7683 Diameter Overload, Indicator
+ Conveyance (DOIC), that defines AVPs intended to be
+ piggybacked onto arbitrary messages. A DOIC dictionary
+ has been included in the installation, in module
+ diameter_gen_doic_rfc7683.</p>
+ <p>
+ Own Id: OTP-14588</p>
+ </item>
+ <item>
+ <p>
+ Decode application AVPs in answers setting the E-bit.</p>
+ <p>
+ AVPs defined in the application of the message being sent
+ were previously not decoded, only those in the common
+ application that defines the answer-message grammar.</p>
+ <p>
+ Own Id: OTP-14596</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>diameter 2.0</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Let candidate peers be passed to diameter:call/4</p>
+ <p>
+ With call option peer, to allow a request to be sent to a
+ peer that hasn't advertised support for the application
+ in question.</p>
+ <p>
+ RFC 6733 2.4 requires a node to send the application
+ identifiers of all locally supported applications at
+ capabilities exchange, but not all nodes respect this for
+ the common application, and diameter itself will send
+ D[WP][RA] without the common application having been
+ explicitly advertised. Regarding the common application
+ as implicit renders Result-Code 5010
+ (DIAMETER_NO_COMMON_APPLICATION) meaningless however, so
+ allow any request to be sent as long as there is a
+ configured dictionary to support it.</p>
+ <p>
+ Own Id: OTP-14338</p>
+ </item>
+ <item>
+ <p>
+ Improve performance of message encode/decode and related
+ handling.</p>
+ <p>
+ Dictionaries using @custom_types or @codecs will need to
+ adapt the corresponding functions to accept an additional
+ argument that is now passed through encode/decode, which
+ was required to remove various process dictionary-based
+ workarounds that have been used to solve problems in the
+ past.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-14343</p>
+ </item>
+ <item>
+ <p>
+ Add transport options to avoid deadlock and allow for
+ load regulation.</p>
+ <p>
+ Both diameter_tcp and diameter_sctp now accept two new
+ configuration options: sender and message_cb. The former
+ causes outgoing sends to take place in a dedicated
+ process, to avoid the possibility of deadlock when both
+ the transport process and its peer block in send. The
+ latter allows a callback to control the reading of
+ messages on the socket, to allow for backpressure towards
+ peers when the rate of incoming traffic is greater than
+ can otherwise be handled.</p>
+ <p>
+ Neither of these options are yet documented, but are
+ unlikely to change unless problems are discovered. The
+ sender option is not the default since it should probably
+ always be used in combination with message_cb, to prevent
+ incoming requests from being read at a higher rate than a
+ peer allows outgoing answers to be sent.</p>
+ <p>
+ Own Id: OTP-14455 Aux Id: ERL-332 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>diameter 1.12.2</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent
index e5c284c6e8..72d74c103c 100644
--- a/lib/diameter/doc/src/seealso.ent
+++ b/lib/diameter/doc/src/seealso.ent
@@ -4,7 +4,7 @@
%CopyrightBegin%
-Copyright Ericsson AB 2012-2015. All Rights Reserved.
+Copyright Ericsson AB 2012-2017. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -53,7 +53,7 @@ significant.
<!ENTITY mod_application_opt '<seealso marker="diameter#application_opt">diameter:application_opt()</seealso>'>
<!ENTITY mod_call_opt '<seealso marker="diameter#call_opt">diameter:call_opt()</seealso>'>
<!ENTITY mod_capability '<seealso marker="diameter#capability">diameter:capability()</seealso>'>
-<!ENTITY mod_evaluable '<seealso marker="diameter#evaluable">diameter:evaluable()</seealso>'>
+<!ENTITY mod_eval '<seealso marker="diameter#eval">diameter:eval()</seealso>'>
<!ENTITY mod_peer_filter '<seealso marker="diameter#peer_filter">diameter:peer_filter()</seealso>'>
<!ENTITY mod_service_event '<seealso marker="diameter#service_event">diameter:service_event()</seealso>'>
<!ENTITY mod_service_event_info '<seealso marker="diameter#service_event_info">diameter:service_event_info()</seealso>'>
@@ -72,13 +72,14 @@ significant.
<!ENTITY watchdog_timer '<seealso marker="#watchdog_timer">watchdog_timer</seealso>'>
<!ENTITY mod_string_decode '<seealso marker="diameter#service_opt">diameter:service_opt()</seealso> <seealso marker="diameter#string_decode">string_decode</seealso>'>
+<!ENTITY mod_decode_format '<seealso marker="diameter#service_opt">diameter:service_opt()</seealso> <seealso marker="diameter#decode_format">decode_format</seealso>'>
<!-- diameter_app -->
<!ENTITY app_handle_answer '<seealso marker="diameter_app#Mod:handle_answer-4">handle_answer/4</seealso>'>
<!ENTITY app_handle_request '<seealso marker="diameter_app#Mod:handle_request-3">handle_request/3</seealso>'>
<!ENTITY app_handle_error '<seealso marker="diameter_app#Mod:handle_error-4">handle_error/4</seealso>'>
-<!ENTITY app_peer_down '<seealso marker="diameter_app#Mod:peer_down-3">peer_up/3</seealso>'>
+<!ENTITY app_peer_down '<seealso marker="diameter_app#Mod:peer_down-3">peer_down/3</seealso>'>
<!ENTITY app_peer_up '<seealso marker="diameter_app#Mod:peer_up-3">peer_up/3</seealso>'>
<!ENTITY app_pick_peer '<seealso marker="diameter_app#Mod:pick_peer-4">pick_peer/4</seealso>'>
<!ENTITY app_prepare_retransmit '<seealso marker="diameter_app#Mod:prepare_retransmit-3">prepare_retransmit/3</seealso>'>
diff --git a/lib/diameter/doc/standard/rfc7683.txt b/lib/diameter/doc/standard/rfc7683.txt
new file mode 100644
index 0000000000..ab2392c6c0
--- /dev/null
+++ b/lib/diameter/doc/standard/rfc7683.txt
@@ -0,0 +1,2355 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) J. Korhonen, Ed.
+Request for Comments: 7683 Broadcom Corporation
+Category: Standards Track S. Donovan, Ed.
+ISSN: 2070-1721 B. Campbell
+ Oracle
+ L. Morand
+ Orange Labs
+ October 2015
+
+
+ Diameter Overload Indication Conveyance
+
+Abstract
+
+ This specification defines a base solution for Diameter overload
+ control, referred to as Diameter Overload Indication Conveyance
+ (DOIC).
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7683.
+
+Copyright Notice
+
+ Copyright (c) 2015 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 1]
+
+RFC 7683 DOIC October 2015
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Terminology and Abbreviations . . . . . . . . . . . . . . . . 3
+ 3. Conventions Used in This Document . . . . . . . . . . . . . . 5
+ 4. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5
+ 4.1. Piggybacking . . . . . . . . . . . . . . . . . . . . . . 6
+ 4.2. DOIC Capability Announcement . . . . . . . . . . . . . . 7
+ 4.3. DOIC Overload Condition Reporting . . . . . . . . . . . . 9
+ 4.4. DOIC Extensibility . . . . . . . . . . . . . . . . . . . 11
+ 4.5. Simplified Example Architecture . . . . . . . . . . . . . 12
+ 5. Solution Procedures . . . . . . . . . . . . . . . . . . . . . 12
+ 5.1. Capability Announcement . . . . . . . . . . . . . . . . . 12
+ 5.1.1. Reacting Node Behavior . . . . . . . . . . . . . . . 13
+ 5.1.2. Reporting Node Behavior . . . . . . . . . . . . . . . 13
+ 5.1.3. Agent Behavior . . . . . . . . . . . . . . . . . . . 14
+ 5.2. Overload Report Processing . . . . . . . . . . . . . . . 15
+ 5.2.1. Overload Control State . . . . . . . . . . . . . . . 15
+ 5.2.2. Reacting Node Behavior . . . . . . . . . . . . . . . 19
+ 5.2.3. Reporting Node Behavior . . . . . . . . . . . . . . . 20
+ 5.3. Protocol Extensibility . . . . . . . . . . . . . . . . . 22
+ 6. Loss Algorithm . . . . . . . . . . . . . . . . . . . . . . . 23
+ 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 23
+ 6.2. Reporting Node Behavior . . . . . . . . . . . . . . . . . 24
+ 6.3. Reacting Node Behavior . . . . . . . . . . . . . . . . . 24
+ 7. Attribute Value Pairs . . . . . . . . . . . . . . . . . . . . 25
+ 7.1. OC-Supported-Features AVP . . . . . . . . . . . . . . . . 25
+ 7.2. OC-Feature-Vector AVP . . . . . . . . . . . . . . . . . . 25
+ 7.3. OC-OLR AVP . . . . . . . . . . . . . . . . . . . . . . . 26
+ 7.4. OC-Sequence-Number AVP . . . . . . . . . . . . . . . . . 26
+ 7.5. OC-Validity-Duration AVP . . . . . . . . . . . . . . . . 26
+ 7.6. OC-Report-Type AVP . . . . . . . . . . . . . . . . . . . 27
+ 7.7. OC-Reduction-Percentage AVP . . . . . . . . . . . . . . . 27
+ 7.8. AVP Flag Rules . . . . . . . . . . . . . . . . . . . . . 28
+ 8. Error Response Codes . . . . . . . . . . . . . . . . . . . . 28
+ 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
+ 9.1. AVP Codes . . . . . . . . . . . . . . . . . . . . . . . . 29
+ 9.2. New Registries . . . . . . . . . . . . . . . . . . . . . 29
+ 10. Security Considerations . . . . . . . . . . . . . . . . . . . 30
+ 10.1. Potential Threat Modes . . . . . . . . . . . . . . . . . 30
+ 10.2. Denial-of-Service Attacks . . . . . . . . . . . . . . . 31
+ 10.3. Noncompliant Nodes . . . . . . . . . . . . . . . . . . . 32
+ 10.4. End-to-End Security Issues . . . . . . . . . . . . . . . 32
+ 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
+ 11.1. Normative References . . . . . . . . . . . . . . . . . . 34
+ 11.2. Informative References . . . . . . . . . . . . . . . . . 34
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 2]
+
+RFC 7683 DOIC October 2015
+
+
+ Appendix A. Issues Left for Future Specifications . . . . . . . 35
+ A.1. Additional Traffic Abatement Algorithms . . . . . . . . . 35
+ A.2. Agent Overload . . . . . . . . . . . . . . . . . . . . . 35
+ A.3. New Error Diagnostic AVP . . . . . . . . . . . . . . . . 35
+ Appendix B. Deployment Considerations . . . . . . . . . . . . . 35
+ Appendix C. Considerations for Applications Integrating the DOIC
+ Solution . . . . . . . . . . . . . . . . . . . . . . 36
+ C.1. Application Classification . . . . . . . . . . . . . . . 36
+ C.2. Implications of Application Type Overload . . . . . . . . 37
+ C.3. Request Transaction Classification . . . . . . . . . . . 38
+ C.4. Request Type Overload Implications . . . . . . . . . . . 39
+ Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 41
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42
+
+1. Introduction
+
+ This specification defines a base solution for Diameter overload
+ control, referred to as Diameter Overload Indication Conveyance
+ (DOIC), based on the requirements identified in [RFC7068].
+
+ This specification addresses Diameter overload control between
+ Diameter nodes that support the DOIC solution. The solution, which
+ is designed to apply to existing and future Diameter applications,
+ requires no changes to the Diameter base protocol [RFC6733] and is
+ deployable in environments where some Diameter nodes do not implement
+ the Diameter overload control solution defined in this specification.
+
+ A new application specification can incorporate the overload control
+ mechanism specified in this document by making it mandatory to
+ implement for the application and referencing this specification
+ normatively. It is the responsibility of the Diameter application
+ designers to define how overload control mechanisms work on that
+ application.
+
+ Note that the overload control solution defined in this specification
+ does not address all the requirements listed in [RFC7068]. A number
+ of features related to overload control are left for future
+ specifications. See Appendix A for a list of extensions that are
+ currently being considered.
+
+2. Terminology and Abbreviations
+
+ Abatement
+
+ Reaction to receipt of an overload report resulting in a reduction
+ in traffic sent to the reporting node. Abatement actions include
+ diversion and throttling.
+
+
+
+
+Korhonen, et al. Standards Track [Page 3]
+
+RFC 7683 DOIC October 2015
+
+
+ Abatement Algorithm
+
+ An extensible method requested by reporting nodes and used by
+ reacting nodes to reduce the amount of traffic sent during an
+ occurrence of overload control.
+
+ Diversion
+
+ An overload abatement treatment where the reacting node selects
+ alternate destinations or paths for requests.
+
+ Host-Routed Requests
+
+ Requests that a reacting node knows will be served by a particular
+ host, either due to the presence of a Destination-Host Attribute
+ Value Pair (AVP) or by some other local knowledge on the part of
+ the reacting node.
+
+ Overload Control State (OCS)
+
+ Internal state maintained by a reporting or reacting node
+ describing occurrences of overload control.
+
+ Overload Report (OLR)
+
+ Overload control information for a particular overload occurrence
+ sent by a reporting node.
+
+ Reacting Node
+
+ A Diameter node that acts upon an overload report.
+
+ Realm-Routed Requests
+
+ Requests sent by a reacting node where the reacting node does not
+ know to which host the request will be routed.
+
+ Reporting Node
+
+ A Diameter node that generates an overload report. (This may or
+ may not be the overloaded node.)
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 4]
+
+RFC 7683 DOIC October 2015
+
+
+ Throttling
+
+ An abatement treatment that limits the number of requests sent by
+ the reacting node. Throttling can include a Diameter Client
+ choosing to not send requests, or a Diameter Agent or Server
+ rejecting requests with appropriate error responses. In both
+ cases, the result of the throttling is a permanent rejection of
+ the transaction.
+
+3. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+ The interpretation from RFC 2119 [RFC2119] does not apply for the
+ above listed words when they are not used in all caps.
+
+4. Solution Overview
+
+ The Diameter Overload Information Conveyance (DOIC) solution allows
+ Diameter nodes to request that other Diameter nodes perform overload
+ abatement actions, that is, actions to reduce the load offered to the
+ overloaded node or realm.
+
+ A Diameter node that supports DOIC is known as a "DOIC node". Any
+ Diameter node can act as a DOIC node, including Diameter Clients,
+ Diameter Servers, and Diameter Agents. DOIC nodes are further
+ divided into "Reporting Nodes" and "Reacting Nodes." A reporting
+ node requests overload abatement by sending Overload Reports (OLRs).
+
+ A reacting node acts upon OLRs and performs whatever actions are
+ needed to fulfill the abatement requests included in the OLRs. A
+ reporting node may report overload on its own behalf or on behalf of
+ other nodes. Likewise, a reacting node may perform overload
+ abatement on its own behalf or on behalf of other nodes.
+
+ A Diameter node's role as a DOIC node is independent of its Diameter
+ role. For example, Diameter Agents may act as DOIC nodes, even
+ though they are not endpoints in the Diameter sense. Since Diameter
+ enables bidirectional applications, where Diameter Servers can send
+ requests towards Diameter Clients, a given Diameter node can
+ simultaneously act as both a reporting node and a reacting node.
+
+ Likewise, a Diameter Agent may act as a reacting node from the
+ perspective of upstream nodes, and a reporting node from the
+ perspective of downstream nodes.
+
+
+
+
+Korhonen, et al. Standards Track [Page 5]
+
+RFC 7683 DOIC October 2015
+
+
+ DOIC nodes do not generate new messages to carry DOIC-related
+ information. Rather, they "piggyback" DOIC information over existing
+ Diameter messages by inserting new AVPs into existing Diameter
+ requests and responses. Nodes indicate support for DOIC, and any
+ needed DOIC parameters, by inserting an OC-Supported-Features AVP
+ (Section 7.1) into existing requests and responses. Reporting nodes
+ send OLRs by inserting OC-OLR AVPs (Section 7.3).
+
+ A given OLR applies to the Diameter realm and application of the
+ Diameter message that carries it. If a reporting node supports more
+ than one realm and/or application, it reports independently for each
+ combination of realm and application. Similarly, the OC-Supported-
+ Features AVP applies to the realm and application of the enclosing
+ message. This implies that a node may support DOIC for one
+ application and/or realm, but not another, and may indicate different
+ DOIC parameters for each application and realm for which it supports
+ DOIC.
+
+ Reacting nodes perform overload abatement according to an agreed-upon
+ abatement algorithm. An abatement algorithm defines the meaning of
+ some of the parameters of an OLR and the procedures required for
+ overload abatement. An overload abatement algorithm separates
+ Diameter requests into two sets. The first set contains the requests
+ that are to undergo overload abatement treatment of either throttling
+ or diversion. The second set contains the requests that are to be
+ given normal routing treatment. This document specifies a single
+ "must-support" algorithm, namely, the "loss" algorithm (Section 6).
+ Future specifications may introduce new algorithms.
+
+ Overload conditions may vary in scope. For example, a single
+ Diameter node may be overloaded, in which case, reacting nodes may
+ attempt to send requests to other destinations. On the other hand,
+ an entire Diameter realm may be overloaded, in which case, such
+ attempts would do harm. DOIC OLRs have a concept of "report type"
+ (Section 7.6), where the type defines such behaviors. Report types
+ are extensible. This document defines report types for overload of a
+ specific host and for overload of an entire realm.
+
+ DOIC works through non-supporting Diameter Agents that properly pass
+ unknown AVPs unchanged.
+
+4.1. Piggybacking
+
+ There is no new Diameter application defined to carry overload-
+ related AVPs. The overload control AVPs defined in this
+ specification have been designed to be piggybacked on top of existing
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 6]
+
+RFC 7683 DOIC October 2015
+
+
+ application messages. This is made possible by adding the optional
+ overload control AVPs OC-OLR and OC-Supported-Features into existing
+ commands.
+
+ Reacting nodes indicate support for DOIC by including the
+ OC-Supported-Features AVP in all request messages originated or
+ relayed by the reacting node.
+
+ Reporting nodes indicate support for DOIC by including the
+ OC-Supported-Features AVP in all answer messages that are originated
+ or relayed by the reporting node and that are in response to a
+ request that contained the OC-Supported-Features AVP. Reporting
+ nodes may include overload reports using the OC-OLR AVP in answer
+ messages.
+
+ Note that the overload control solution does not have fixed server
+ and client roles. The DOIC node role is determined based on the
+ message type: whether the message is a request (i.e., sent by a
+ "reacting node") or an answer (i.e., sent by a "reporting node").
+ Therefore, in a typical client-server deployment, the Diameter Client
+ may report its overload condition to the Diameter Server for any
+ Diameter-Server-initiated message exchange. An example of such is
+ the Diameter Server requesting a re-authentication from a Diameter
+ Client.
+
+4.2. DOIC Capability Announcement
+
+ The DOIC solution supports the ability for Diameter nodes to
+ determine if other nodes in the path of a request support the
+ solution. This capability is referred to as DOIC Capability
+ Announcement (DCA) and is separate from the Diameter Capability
+ Exchange.
+
+ The DCA mechanism uses the OC-Supported-Features AVPs to indicate the
+ Diameter overload features supported.
+
+ The first node in the path of a Diameter request that supports the
+ DOIC solution inserts the OC-Supported-Features AVP in the request
+ message.
+
+ The individual features supported by the DOIC nodes are indicated in
+ the OC-Feature-Vector AVP. Any semantics associated with the
+ features will be defined in extension specifications that introduce
+ the features.
+
+ Note: As discussed elsewhere in the document, agents in the path
+ of the request can modify the OC-Supported-Features AVP.
+
+
+
+
+Korhonen, et al. Standards Track [Page 7]
+
+RFC 7683 DOIC October 2015
+
+
+ Note: The DOIC solution must support deployments where Diameter
+ Clients and/or Diameter Servers do not support the DOIC solution.
+ In this scenario, Diameter Agents that support the DOIC solution
+ may handle overload abatement for the non-supporting Diameter
+ nodes. In this case, the DOIC agent will insert the OC-Supported-
+ Features AVP in requests that do not already contain one, telling
+ the reporting node that there is a DOIC node that will handle
+ overload abatement. For transactions where there was an
+ OC-Supporting-Features AVP in the request, the agent will insert
+ the OC-Supported-Features AVP in answers, telling the reacting
+ node that there is a reporting node.
+
+ The OC-Feature-Vector AVP will always contain an indication of
+ support for the loss overload abatement algorithm defined in this
+ specification (see Section 6). This ensures that a reporting node
+ always supports at least one of the advertised abatement algorithms
+ received in a request messages.
+
+ The reporting node inserts the OC-Supported-Features AVP in all
+ answer messages to requests that contained the OC-Supported-Features
+ AVP. The contents of the reporting node's OC-Supported-Features AVP
+ indicate the set of Diameter overload features supported by the
+ reporting node. This specification defines one exception -- the
+ reporting node only includes an indication of support for one
+ overload abatement algorithm, independent of the number of overload
+ abatement algorithms actually supported by the reacting node. The
+ overload abatement algorithm indicated is the algorithm that the
+ reporting node intends to use should it enter an overload condition.
+ Reacting nodes can use the indicated overload abatement algorithm to
+ prepare for possible overload reports and must use the indicated
+ overload abatement algorithm if traffic reduction is actually
+ requested.
+
+ Note that the loss algorithm defined in this document is a
+ stateless abatement algorithm. As a result, it does not require
+ any actions by reacting nodes prior to the receipt of an overload
+ report. Stateful abatement algorithms that base the abatement
+ logic on a history of request messages sent might require reacting
+ nodes to maintain state in advance of receiving an overload report
+ to ensure that the overload reports can be properly handled.
+
+ While it should only be done in exceptional circumstances and not
+ during an active occurrence of overload, a reacting node that wishes
+ to transition to a different abatement algorithm can stop advertising
+ support for the algorithm indicated by the reporting node, as long as
+ support for the loss algorithm is always advertised.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 8]
+
+RFC 7683 DOIC October 2015
+
+
+ The DCA mechanism must also allow the scenario where the set of
+ features supported by the sender of a request and by agents in the
+ path of a request differ. In this case, the agent can update the
+ OC-Supported-Features AVP to reflect the mixture of the two sets of
+ supported features.
+
+ Note: The logic to determine if the content of the OC-Supported-
+ Features AVP should be changed is out of scope for this document,
+ as is the logic to determine the content of a modified
+ OC-Supported-Features AVP. These are left to implementation
+ decisions. Care must be taken not to introduce interoperability
+ issues for downstream or upstream DOIC nodes. As such, the agent
+ must act as a fully compliant reporting node to the downstream
+ reacting node and as a fully compliant reacting node to the
+ upstream reporting node.
+
+4.3. DOIC Overload Condition Reporting
+
+ As with DOIC capability announcement, overload condition reporting
+ uses new AVPs (Section 7.3) to indicate an overload condition.
+
+ The OC-OLR AVP is referred to as an overload report. The OC-OLR AVP
+ includes the type of report, a sequence number, the length of time
+ that the report is valid, and AVPs specific to the abatement
+ algorithm.
+
+ Two types of overload reports are defined in this document: host
+ reports and realm reports.
+
+ A report of type "HOST_REPORT" is sent to indicate the overload of a
+ specific host, identified by the Origin-Host AVP of the message
+ containing the OLR, for the Application-ID indicated in the
+ transaction. When receiving an OLR of type "HOST_REPORT", a reacting
+ node applies overload abatement treatment to the host-routed requests
+ identified by the overload abatement algorithm (as defined in
+ Section 2) sent for this application to the overloaded host.
+
+ A report of type "REALM_REPORT" is sent to indicate the overload of a
+ realm for the Application-ID indicated in the transaction. The
+ overloaded realm is identified by the Destination-Realm AVP of the
+ message containing the OLR. When receiving an OLR of type
+ "REALM_REPORT", a reacting node applies overload abatement treatment
+ to realm-routed requests identified by the overload abatement
+ algorithm (as defined in Section 2) sent for this application to the
+ overloaded realm.
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 9]
+
+RFC 7683 DOIC October 2015
+
+
+ This document assumes that there is a single source for realm reports
+ for a given realm, or that if multiple nodes can send realm reports,
+ that each such node has full knowledge of the overload state of the
+ entire realm. A reacting node cannot distinguish between receiving
+ realm reports from a single node or from multiple nodes.
+
+ Note: Known issues exist if there are multiple sources for
+ overload reports that apply to the same Diameter entity. Reacting
+ nodes have no way of determining the source and, as such, will
+ treat them as coming from a single source. Variance in sequence
+ numbers between the two sources can then cause incorrect overload
+ abatement treatment to be applied for indeterminate periods of
+ time.
+
+ Reporting nodes are responsible for determining the need for a
+ reduction of traffic. The method for making this determination is
+ implementation specific and depends on the type of overload report
+ being generated. A host report might be generated by tracking use of
+ resources required by the host to handle transactions for the
+ Diameter application. A realm report generally impacts the traffic
+ sent to multiple hosts and, as such, requires tracking the capacity
+ of all servers able to handle realm-routed requests for the
+ application and realm.
+
+ Once a reporting node determines the need for a reduction in traffic,
+ it uses the DOIC-defined AVPs to report on the condition. These AVPs
+ are included in answer messages sent or relayed by the reporting
+ node. The reporting node indicates the overload abatement algorithm
+ that is to be used to handle the traffic reduction in the
+ OC-Supported-Features AVP. The OC-OLR AVP is used to communicate
+ information about the requested reduction.
+
+ Reacting nodes, upon receipt of an overload report, apply the
+ overload abatement algorithm to traffic impacted by the overload
+ report. The method used to determine the requests that are to
+ receive overload abatement treatment is dependent on the abatement
+ algorithm. The loss abatement algorithm is defined in this document
+ (Section 6). Other abatement algorithms can be defined in extensions
+ to the DOIC solution.
+
+ Two types of overload abatement treatment are defined, diversion and
+ throttling. Reacting nodes are responsible for determining which
+ treatment is appropriate for individual requests.
+
+ As the conditions that lead to the generation of the overload report
+ change, the reporting node can send new overload reports requesting
+ greater reduction if the condition gets worse or less reduction if
+ the condition improves. The reporting node sends an overload report
+
+
+
+Korhonen, et al. Standards Track [Page 10]
+
+RFC 7683 DOIC October 2015
+
+
+ with a duration of zero to indicate that the overload condition has
+ ended and abatement is no longer needed.
+
+ The reacting node also determines when the overload report expires
+ based on the OC-Validity-Duration AVP in the overload report and
+ stops applying the abatement algorithm when the report expires.
+
+ Note that erroneous overload reports can be used for DoS attacks.
+ This includes the ability to indicate that a significant reduction in
+ traffic, up to and including a request for no traffic, should be sent
+ to a reporting node. As such, care should be taken to verify the
+ sender of overload reports.
+
+4.4. DOIC Extensibility
+
+ The DOIC solution is designed to be extensible. This extensibility
+ is based on existing Diameter-based extensibility mechanisms, along
+ with the DOIC capability announcement mechanism.
+
+ There are multiple categories of extensions that are expected. This
+ includes the definition of new overload abatement algorithms, the
+ definition of new report types, and the definition of new scopes of
+ messages impacted by an overload report.
+
+ A DOIC node communicates supported features by including them in the
+ OC-Feature-Vector AVP, as a sub-AVP of OC-Supported-Features. Any
+ non-backwards-compatible DOIC extensions define new values for the
+ OC-Feature-Vector AVP. DOIC extensions also have the ability to add
+ new AVPs to the OC-Supported-Features AVP, if additional information
+ about the new feature is required.
+
+ Overload reports can also be extended by adding new sub-AVPs to the
+ OC-OLR AVP, allowing reporting nodes to communicate additional
+ information about handling an overload condition.
+
+ If necessary, new extensions can also define new AVPs that are not
+ part of the OC-Supported-Features and OC-OLR group AVPs. It is,
+ however, recommended that DOIC extensions use the OC-Supported-
+ Features AVP and OC-OLR AVP to carry all DOIC-related AVPs.
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 11]
+
+RFC 7683 DOIC October 2015
+
+
+4.5. Simplified Example Architecture
+
+ Figure 1 illustrates the simplified architecture for Diameter
+ overload information conveyance.
+
+ Realm X Same or other Realms
+ <--------------------------------------> <---------------------->
+
+
+ +--------+ : (optional) :
+ |Diameter| : :
+ |Server A|--+ .--. : +--------+ : .--.
+ +--------+ | _( `. : |Diameter| : _( `. +--------+
+ +--( )--:-| Agent |-:--( )--|Diameter|
+ +--------+ | ( ` . ) ) : +--------+ : ( ` . ) ) | Client |
+ |Diameter|--+ `--(___.-' : : `--(___.-' +--------+
+ |Server B| : :
+ +--------+ : :
+
+ End-to-end Overload Indication
+ 1) <----------------------------------------------->
+ Diameter Application Y
+
+ Overload Indication A Overload Indication A'
+ 2) <----------------------> <---------------------->
+ Diameter Application Y Diameter Application Y
+
+ Figure 1: Simplified Architecture Choices for Overload Indication
+ Delivery
+
+ In Figure 1, the Diameter overload indication can be conveyed (1)
+ end-to-end between servers and clients or (2) between servers and the
+ Diameter Agent inside the realm and then between the Diameter Agent
+ and the clients.
+
+5. Solution Procedures
+
+ This section outlines the normative behavior for the DOIC solution.
+
+5.1. Capability Announcement
+
+ This section defines DOIC Capability Announcement (DCA) behavior.
+
+ Note: This specification assumes that changes in DOIC node
+ capabilities are relatively rare events that occur as a result of
+ administrative action. Reacting nodes ought to minimize changes
+ that force the reporting node to change the features being used,
+ especially during active overload conditions. But even if
+
+
+
+Korhonen, et al. Standards Track [Page 12]
+
+RFC 7683 DOIC October 2015
+
+
+ reacting nodes avoid such changes, reporting nodes still have to
+ be prepared for them to occur. For example, differing
+ capabilities between multiple reacting nodes may still force a
+ reporting node to select different features on a per-transaction
+ basis.
+
+5.1.1. Reacting Node Behavior
+
+ A reacting node MUST include the OC-Supported-Features AVP in all
+ requests. It MAY include the OC-Feature-Vector AVP, as a sub-AVP of
+ OC-Supported-Features. If it does so, it MUST indicate support for
+ the "loss" algorithm. If the reacting node is configured to support
+ features (including other algorithms) in addition to the loss
+ algorithm, it MUST indicate such support in an OC-Feature-Vector AVP.
+
+ An OC-Supported-Features AVP in answer messages indicates there is a
+ reporting node for the transaction. The reacting node MAY take
+ action, for example, creating state for some stateful abatement
+ algorithm, based on the features indicated in the OC-Feature-Vector
+ AVP.
+
+ Note: The loss abatement algorithm does not require stateful
+ behavior when there is no active overload report.
+
+ Reacting nodes need to be prepared for the reporting node to change
+ selected algorithms. This can happen at any time, including when the
+ reporting node has sent an active overload report. The reacting node
+ can minimize the potential for changes by modifying the advertised
+ abatement algorithms sent to an overloaded reporting node to the
+ currently selected algorithm and loss (or just loss if it is the
+ currently selected algorithm). This has the effect of limiting the
+ potential change in abatement algorithm from the currently selected
+ algorithm to loss, avoiding changes to more complex abatement
+ algorithms that require state to operate properly.
+
+5.1.2. Reporting Node Behavior
+
+ Upon receipt of a request message, a reporting node determines if
+ there is a reacting node for the transaction based on the presence of
+ the OC-Supported-Features AVP in the request message.
+
+ If the request message contains an OC-Supported-Features AVP, then a
+ reporting node MUST include the OC-Supported-Features AVP in the
+ answer message for that transaction.
+
+ Note: Capability announcement is done on a per-transaction basis.
+ The reporting node cannot assume that the capabilities announced
+ by a reacting node will be the same between transactions.
+
+
+
+Korhonen, et al. Standards Track [Page 13]
+
+RFC 7683 DOIC October 2015
+
+
+ A reporting node MUST NOT include the OC-Supported-Features AVP,
+ OC-OLR AVP, or any other overload control AVPs defined in extension
+ documents in response messages for transactions where the request
+ message does not include the OC-Supported-Features AVP. Lack of the
+ OC-Supported-Features AVP in the request message indicates that there
+ is no reacting node for the transaction.
+
+ A reporting node knows what overload control functionality is
+ supported by the reacting node based on the content or absence of the
+ OC-Feature-Vector AVP within the OC-Supported-Features AVP in the
+ request message.
+
+ A reporting node MUST select a single abatement algorithm in the
+ OC-Feature-Vector AVP. The abatement algorithm selected MUST
+ indicate the abatement algorithm the reporting node wants the
+ reacting node to use when the reporting node enters an overload
+ condition.
+
+ The abatement algorithm selected MUST be from the set of abatement
+ algorithms contained in the request message's OC-Feature-Vector AVP.
+
+ A reporting node that selects the loss algorithm may do so by
+ including the OC-Feature-Vector AVP with an explicit indication of
+ the loss algorithm, or it MAY omit the OC-Feature-Vector AVP. If it
+ selects a different algorithm, it MUST include the OC-Feature-Vector
+ AVP with an explicit indication of the selected algorithm.
+
+ The reporting node SHOULD indicate support for other DOIC features
+ defined in extension documents that it supports and that apply to the
+ transaction. It does so using the OC-Feature-Vector AVP.
+
+ Note: Not all DOIC features will apply to all Diameter
+ applications or deployment scenarios. The features included in
+ the OC-Feature-Vector AVP are based on local policy of the
+ reporting node.
+
+5.1.3. Agent Behavior
+
+ Diameter Agents that support DOIC can ensure that all messages
+ relayed by the agent contain the OC-Supported-Features AVP.
+
+ A Diameter Agent MAY take on reacting node behavior for Diameter
+ endpoints that do not support the DOIC solution. A Diameter Agent
+ detects that a Diameter endpoint does not support DOIC reacting node
+ behavior when there is no OC-Supported-Features AVP in a request
+ message.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 14]
+
+RFC 7683 DOIC October 2015
+
+
+ For a Diameter Agent to be a reacting node for a non-supporting
+ Diameter endpoint, the Diameter Agent MUST include the OC-Supported-
+ Features AVP in request messages it relays that do not contain the
+ OC-Supported-Features AVP.
+
+ A Diameter Agent MAY take on reporting node behavior for Diameter
+ endpoints that do not support the DOIC solution. The Diameter Agent
+ MUST have visibility to all traffic destined for the non-supporting
+ host in order to become the reporting node for the Diameter endpoint.
+ A Diameter Agent detects that a Diameter endpoint does not support
+ DOIC reporting node behavior when there is no OC-Supported-Features
+ AVP in an answer message for a transaction that contained the
+ OC-Supported-Features AVP in the request message.
+
+ If a request already has the OC-Supported-Features AVP, a Diameter
+ Agent MAY modify it to reflect the features appropriate for the
+ transaction. Otherwise, the agent relays the OC-Supported-Features
+ AVP without change.
+
+ Example: If the agent supports a superset of the features reported
+ by the reacting node, then the agent might choose, based on local
+ policy, to advertise that superset of features to the reporting
+ node.
+
+ If the Diameter Agent changes the OC-Supported-Features AVP in a
+ request message, then it is likely it will also need to modify the
+ OC-Supported-Features AVP in the answer message for the transaction.
+ A Diameter Agent MAY modify the OC-Supported-Features AVP carried in
+ answer messages.
+
+ When making changes to the OC-Supported-Features or OC-OLR AVPs, the
+ Diameter Agent needs to ensure consistency in its behavior with both
+ upstream and downstream DOIC nodes.
+
+5.2. Overload Report Processing
+
+5.2.1. Overload Control State
+
+ Both reacting and reporting nodes maintain Overload Control State
+ (OCS) for active overload conditions. The following sections define
+ behavior associated with that OCS.
+
+ The contents of the OCS in the reporting node and in the reacting
+ node represent logical constructs. The actual internal physical
+ structure of the state included in the OCS is an implementation
+ decision.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 15]
+
+RFC 7683 DOIC October 2015
+
+
+5.2.1.1. Overload Control State for Reacting Nodes
+
+ A reacting node maintains the following OCS per supported Diameter
+ application:
+
+ o a host-type OCS entry for each Destination-Host to which it sends
+ host-type requests and
+
+ o a realm-type OCS entry for each Destination-Realm to which it
+ sends realm-type requests.
+
+ A host-type OCS entry is identified by the pair of Application-ID and
+ the node's DiameterIdentity.
+
+ A realm-type OCS entry is identified by the pair of Application-ID
+ and realm.
+
+ The host-type and realm-type OCS entries include the following
+ information (the actual information stored is an implementation
+ decision):
+
+ o Sequence number (as received in OC-OLR; see Section 7.3)
+
+ o Time of expiry (derived from OC-Validity-Duration AVP received in
+ the OC-OLR AVP and time of reception of the message carrying
+ OC-OLR AVP)
+
+ o Selected abatement algorithm (as received in the OC-Supported-
+ Features AVP)
+
+ o Input data that is abatement algorithm specific (as received in
+ the OC-OLR AVP -- for example, OC-Reduction-Percentage for the
+ loss abatement algorithm)
+
+5.2.1.2. Overload Control State for Reporting Nodes
+
+ A reporting node maintains OCS entries per supported Diameter
+ application, per supported (and eventually selected) abatement
+ algorithm, and per report type.
+
+ An OCS entry is identified by the tuple of Application-ID, report
+ type, and abatement algorithm, and it includes the following
+ information (the actual information stored is an implementation
+ decision):
+
+ o Sequence number
+
+ o Validity duration
+
+
+
+Korhonen, et al. Standards Track [Page 16]
+
+RFC 7683 DOIC October 2015
+
+
+ o Expiration time
+
+ o Input data that is algorithm specific (for example, the reduction
+ percentage for the loss abatement algorithm)
+
+5.2.1.3. Reacting Node's Maintenance of Overload Control State
+
+ When a reacting node receives an OC-OLR AVP, it MUST determine if it
+ is for an existing or new overload condition.
+
+ Note: For the remainder of this section, the term "OLR" refers to
+ the combination of the contents of the received OC-OLR AVP and the
+ abatement algorithm indicated in the received OC-Supported-
+ Features AVP.
+
+ When receiving an answer message with multiple OLRs of different
+ supported report types, a reacting node MUST process each received
+ OLR.
+
+ The OLR is for an existing overload condition if a reacting node has
+ an OCS that matches the received OLR.
+
+ For a host report, this means it matches the Application-ID and the
+ host's DiameterIdentity in an existing host OCS entry.
+
+ For a realm report, this means it matches the Application-ID and the
+ realm in an existing realm OCS entry.
+
+ If the OLR is for an existing overload condition, then a reacting
+ node MUST determine if the OLR is a retransmission or an update to
+ the existing OLR.
+
+ If the sequence number for the received OLR is greater than the
+ sequence number stored in the matching OCS entry, then a reacting
+ node MUST update the matching OCS entry.
+
+ If the sequence number for the received OLR is less than or equal to
+ the sequence number in the matching OCS entry, then a reacting node
+ MUST silently ignore the received OLR. The matching OCS MUST NOT be
+ updated in this case.
+
+ If the reacting node determines that the sequence number has rolled
+ over, then the reacting node MUST update the matching OCS entry.
+ This can be determined by recognizing that the number has changed
+ from a value within 1% of the maximum value in the OC-Sequence-Number
+ AVP to a value within 1% of the minimum value in the OC-Sequence-
+ Number AVP.
+
+
+
+
+Korhonen, et al. Standards Track [Page 17]
+
+RFC 7683 DOIC October 2015
+
+
+ If the received OLR is for a new overload condition, then a reacting
+ node MUST generate a new OCS entry for the overload condition.
+
+ For a host report, this means a reacting node creates an OCS entry
+ with the Application-ID in the received message and DiameterIdentity
+ of the Origin-Host in the received message.
+
+ Note: This solution assumes that the Origin-Host AVP in the answer
+ message included by the reporting node is not changed along the
+ path to the reacting node.
+
+ For a realm report, this means a reacting node creates an OCS entry
+ with the Application-ID in the received message and realm of the
+ Origin-Realm in the received message.
+
+ If the received OLR contains a validity duration of zero ("0"), then
+ a reacting node MUST update the OCS entry as being expired.
+
+ Note: It is not necessarily appropriate to delete the OCS entry,
+ as the recommended behavior is that the reacting node slowly
+ returns to full traffic when ending an overload abatement period.
+
+ The reacting node does not delete an OCS when receiving an answer
+ message that does not contain an OC-OLR AVP (i.e., absence of OLR
+ means "no change").
+
+5.2.1.4. Reporting Node's Maintenance of Overload Control State
+
+ A reporting node SHOULD create a new OCS entry when entering an
+ overload condition.
+
+ Note: If a reporting node knows through absence of the
+ OC-Supported-Features AVP in received messages that there are no
+ reacting nodes supporting DOIC, then the reporting node can choose
+ to not create OCS entries.
+
+ When generating a new OCS entry, the sequence number SHOULD be set to
+ zero ("0").
+
+ When generating sequence numbers for new overload conditions, the new
+ sequence number MUST be greater than any sequence number in an active
+ (unexpired) overload report for the same application and report type
+ previously sent by the reporting node. This property MUST hold over
+ a reboot of the reporting node.
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 18]
+
+RFC 7683 DOIC October 2015
+
+
+ Note: One way of addressing this over a reboot of a reporting node
+ is to use a timestamp for the first overload condition that occurs
+ after the report and to start using sequences beginning with zero
+ for subsequent overload conditions.
+
+ A reporting node MUST update an OCS entry when it needs to adjust the
+ validity duration of the overload condition at reacting nodes.
+
+ Example: If a reporting node wishes to instruct reacting nodes to
+ continue overload abatement for a longer period of time than
+ originally communicated. This also applies if the reporting node
+ wishes to shorten the period of time that overload abatement is to
+ continue.
+
+ A reporting node MUST update an OCS entry when it wishes to adjust
+ any parameters specific to the abatement algorithm, including, for
+ example, the reduction percentage used for the loss abatement
+ algorithm.
+
+ Example: If a reporting node wishes to change the reduction
+ percentage either higher (if the overload condition has worsened)
+ or lower (if the overload condition has improved), then the
+ reporting node would update the appropriate OCS entry.
+
+ A reporting node MUST increment the sequence number associated with
+ the OCS entry anytime the contents of the OCS entry are changed.
+ This will result in a new sequence number being sent to reacting
+ nodes, instructing them to process the OC-OLR AVP.
+
+ A reporting node SHOULD update an OCS entry with a validity duration
+ of zero ("0") when the overload condition ends.
+
+ Note: If a reporting node knows that the OCS entries in the
+ reacting nodes are near expiration, then the reporting node might
+ decide not to send an OLR with a validity duration of zero.
+
+ A reporting node MUST keep an OCS entry with a validity duration of
+ zero ("0") for a period of time long enough to ensure that any
+ unexpired reacting node's OCS entry created as a result of the
+ overload condition in the reporting node is deleted.
+
+5.2.2. Reacting Node Behavior
+
+ When a reacting node sends a request, it MUST determine if that
+ request matches an active OCS.
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 19]
+
+RFC 7683 DOIC October 2015
+
+
+ If the request matches an active OCS, then the reacting node MUST use
+ the overload abatement algorithm indicated in the OCS to determine if
+ the request is to receive overload abatement treatment.
+
+ For the loss abatement algorithm defined in this specification, see
+ Section 6 for the overload abatement algorithm logic applied.
+
+ If the overload abatement algorithm selects the request for overload
+ abatement treatment, then the reacting node MUST apply overload
+ abatement treatment on the request. The abatement treatment applied
+ depends on the context of the request.
+
+ If diversion abatement treatment is possible (i.e., a different path
+ for the request can be selected where the overloaded node is not part
+ of the different path), then the reacting node SHOULD apply diversion
+ abatement treatment to the request. The reacting node MUST apply
+ throttling abatement treatment to requests identified for abatement
+ treatment when diversion treatment is not possible or was not
+ applied.
+
+ Note: This only addresses the case where there are two defined
+ abatement treatments, diversion and throttling. Any extension
+ that defines a new abatement treatment must also define its
+ interaction with existing treatments.
+
+ If the overload abatement treatment results in throttling of the
+ request and if the reacting node is an agent, then the agent MUST
+ send an appropriate error as defined in Section 8.
+
+ Diameter endpoints that throttle requests need to do so according to
+ the rules of the client application. Those rules will vary by
+ application and are beyond the scope of this document.
+
+ In the case that the OCS entry indicated no traffic was to be sent to
+ the overloaded entity and the validity duration expires, then
+ overload abatement associated with the overload report MUST be ended
+ in a controlled fashion.
+
+5.2.3. Reporting Node Behavior
+
+ If there is an active OCS entry, then a reporting node SHOULD include
+ the OC-OLR AVP in all answers to requests that contain the
+ OC-Supported-Features AVP and that match the active OCS entry.
+
+ Note: A request matches 1) if the Application-ID in the request
+ matches the Application-ID in any active OCS entry and 2) if the
+ report type in the OCS entry matches a report type supported by
+ the reporting node as indicated in the OC-Supported-Features AVP.
+
+
+
+Korhonen, et al. Standards Track [Page 20]
+
+RFC 7683 DOIC October 2015
+
+
+ The contents of the OC-OLR AVP depend on the selected algorithm.
+
+ A reporting node MAY choose to not resend an overload report to a
+ reacting node if it can guarantee that this overload report is
+ already active in the reacting node.
+
+ Note: In some cases (e.g., when there are one or more agents in
+ the path between reporting and reacting nodes, or when overload
+ reports are discarded by reacting nodes), a reporting node may not
+ be able to guarantee that the reacting node has received the
+ report.
+
+ A reporting node MUST NOT send overload reports of a type that has
+ not been advertised as supported by the reacting node.
+
+ Note: A reacting node implicitly advertises support for the host
+ and realm report types by including the OC-Supported-Features AVP
+ in the request. Support for other report types will be explicitly
+ indicated by new feature bits in the OC-Feature-Vector AVP.
+
+ A reporting node SHOULD explicitly indicate the end of an overload
+ occurrence by sending a new OLR with OC-Validity-Duration set to a
+ value of zero ("0"). The reporting node SHOULD ensure that all
+ reacting nodes receive the updated overload report.
+
+ A reporting node MAY rely on the OC-Validity-Duration AVP values for
+ the implicit cleanup of overload control state on the reacting node.
+
+ Note: All OLRs sent have an expiration time calculated by adding
+ the validity duration contained in the OLR to the time the message
+ was sent. Transit time for the OLR can be safely ignored. The
+ reporting node can ensure that all reacting nodes have received
+ the OLR by continuing to send it in answer messages until the
+ expiration time for all OLRs sent for that overload condition have
+ expired.
+
+ When a reporting node sends an OLR, it effectively delegates any
+ necessary throttling to downstream nodes. If the reporting node also
+ locally throttles the same set of messages, the overall number of
+ throttled requests may be higher than intended. Therefore, before
+ applying local message throttling, a reporting node needs to check if
+ these messages match existing OCS entries, indicating that these
+ messages have survived throttling applied by downstream nodes that
+ have received the related OLR.
+
+ However, even if the set of messages match existing OCS entries, the
+ reporting node can still apply other abatement methods such as
+ diversion. The reporting node might also need to throttle requests
+
+
+
+Korhonen, et al. Standards Track [Page 21]
+
+RFC 7683 DOIC October 2015
+
+
+ for reasons other than overload. For example, an agent or server
+ might have a configured rate limit for each client and might throttle
+ requests that exceed that limit, even if such requests had already
+ been candidates for throttling by downstream nodes. The reporting
+ node also has the option to send new OLRs requesting greater
+ reductions in traffic, reducing the need for local throttling.
+
+ A reporting node SHOULD decrease requested overload abatement
+ treatment in a controlled fashion to avoid oscillations in traffic.
+
+ Example: A reporting node might wait some period of time after
+ overload ends before terminating the OLR, or it might send a
+ series of OLRs indicating progressively less overload severity.
+
+5.3. Protocol Extensibility
+
+ The DOIC solution can be extended. Types of potential extensions
+ include new traffic abatement algorithms, new report types, or other
+ new functionality.
+
+ When defining a new extension that requires new normative behavior,
+ the specification must define a new feature for the OC-Feature-Vector
+ AVP. This feature bit is used to communicate support for the new
+ feature.
+
+ The extension may define new AVPs for use in the DOIC Capability
+ Announcement and for use in DOIC overload reporting. These new AVPs
+ SHOULD be defined to be extensions to the OC-Supported-Features or
+ OC-OLR AVPs defined in this document.
+
+ The Grouped AVP extension mechanisms defined in [RFC6733] apply.
+ This allows, for example, defining a new feature that is mandatory to
+ be understood even when piggybacked on an existing application.
+
+ When defining new report type values, the corresponding specification
+ must define the semantics of the new report types and how they affect
+ the OC-OLR AVP handling.
+
+ The OC-Supported-Feature and OC-OLR AVPs can be expanded with
+ optional sub-AVPs only if a legacy DOIC implementation can safely
+ ignore them without breaking backward compatibility for the given
+ OC-Report-Type AVP value. Any new sub-AVPs must not require that the
+ M-bit be set.
+
+ Documents that introduce new report types must describe any
+ limitations on their use across non-supporting agents.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 22]
+
+RFC 7683 DOIC October 2015
+
+
+ As with any Diameter specification, RFC 6733 requires all new AVPs to
+ be registered with IANA. See Section 9 for the required procedures.
+ New features (feature bits in the OC-Feature-Vector AVP) and report
+ types (in the OC-Report-Type AVP) MUST be registered with IANA.
+
+6. Loss Algorithm
+
+ This section documents the Diameter overload loss abatement
+ algorithm.
+
+6.1. Overview
+
+ The DOIC specification supports the ability for multiple overload
+ abatement algorithms to be specified. The abatement algorithm used
+ for any instance of overload is determined by the DOIC Capability
+ Announcement process documented in Section 5.1.
+
+ The loss algorithm described in this section is the default algorithm
+ that must be supported by all Diameter nodes that support DOIC.
+
+ The loss algorithm is designed to be a straightforward and stateless
+ overload abatement algorithm. It is used by reporting nodes to
+ request a percentage reduction in the amount of traffic sent. The
+ traffic impacted by the requested reduction depends on the type of
+ overload report.
+
+ Reporting nodes request the stateless reduction of the number of
+ requests by an indicated percentage. This percentage reduction is in
+ comparison to the number of messages the node otherwise would send,
+ regardless of how many requests the node might have sent in the past.
+
+ From a conceptual level, the logic at the reacting node could be
+ outlined as follows.
+
+ 1. An overload report is received, and the associated OCS is either
+ saved or updated (if required) by the reacting node.
+
+ 2. A new Diameter request is generated by the application running on
+ the reacting node.
+
+ 3. The reacting node determines that an active overload report
+ applies to the request, as indicated by the corresponding OCS
+ entry.
+
+ 4. The reacting node determines if overload abatement treatment
+ should be applied to the request. One approach that could be
+ taken for each request is to select a uniformly selected random
+ number between 1 and 100. If the random number is less than or
+
+
+
+Korhonen, et al. Standards Track [Page 23]
+
+RFC 7683 DOIC October 2015
+
+
+ equal to the indicated reduction percentage, then the request is
+ given abatement treatment; otherwise, the request is given normal
+ routing treatment.
+
+6.2. Reporting Node Behavior
+
+ The method a reporting node uses to determine the amount of traffic
+ reduction required to address an overload condition is an
+ implementation decision.
+
+ When a reporting node that has selected the loss abatement algorithm
+ determines the need to request a reduction in traffic, it includes an
+ OC-OLR AVP in answer messages as described in Section 5.2.3.
+
+ When sending the OC-OLR AVP, the reporting node MUST indicate a
+ percentage reduction in the OC-Reduction-Percentage AVP.
+
+ The reporting node MAY change the reduction percentage in subsequent
+ overload reports. When doing so, the reporting node must conform to
+ overload report handling specified in Section 5.2.3.
+
+6.3. Reacting Node Behavior
+
+ The method a reacting node uses to determine which request messages
+ are given abatement treatment is an implementation decision.
+
+ When receiving an OC-OLR in an answer message where the algorithm
+ indicated in the OC-Supported-Features AVP is the loss algorithm, the
+ reacting node MUST apply abatement treatment to the requested
+ percentage of request messages sent.
+
+ Note: The loss algorithm is a stateless algorithm. As a result,
+ the reacting node does not guarantee that there will be an
+ absolute reduction in traffic sent. Rather, it guarantees that
+ the requested percentage of new requests will be given abatement
+ treatment.
+
+ If the reacting node comes out of the 100% traffic reduction
+ (meaning, it has received an OLR indicating that no traffic should be
+ sent, as a result of the overload report timing out), the reacting
+ node sending the traffic SHOULD be conservative and, for example,
+ first send "probe" messages to learn the overload condition of the
+ overloaded node before converging to any traffic amount/rate decided
+ by the sender. Similar concerns apply in all cases when the overload
+ report times out, unless the previous overload report stated 0%
+ reduction.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 24]
+
+RFC 7683 DOIC October 2015
+
+
+ Note: The goal of this behavior is to reduce the probability of
+ overload condition thrashing where an immediate transition from
+ 100% reduction to 0% reduction results in the reporting node
+ moving quickly back into an overload condition.
+
+7. Attribute Value Pairs
+
+ This section describes the encoding and semantics of the Diameter
+ Overload Indication Attribute Value Pairs (AVPs) defined in this
+ document.
+
+ Refer to Section 4 of [RFC6733] for more information on AVPs and AVP
+ data types.
+
+7.1. OC-Supported-Features AVP
+
+ The OC-Supported-Features AVP (AVP Code 621) is of type Grouped and
+ serves two purposes. First, it announces a node's support for the
+ DOIC solution in general. Second, it contains the description of the
+ supported DOIC features of the sending node. The OC-Supported-
+ Features AVP MUST be included in every Diameter request message a
+ DOIC supporting node sends.
+
+ OC-Supported-Features ::= < AVP Header: 621 >
+ [ OC-Feature-Vector ]
+ * [ AVP ]
+
+7.2. OC-Feature-Vector AVP
+
+ The OC-Feature-Vector AVP (AVP Code 622) is of type Unsigned64 and
+ contains a 64-bit flags field of announced capabilities of a DOIC
+ node. The value of zero (0) is reserved.
+
+ The OC-Feature-Vector sub-AVP is used to announce the DOIC features
+ supported by the DOIC node, in the form of a flag-bits field in which
+ each bit announces one feature or capability supported by the node.
+ The absence of the OC-Feature-Vector AVP in request messages
+ indicates that only the default traffic abatement algorithm described
+ in this specification is supported. The absence of the OC-Feature-
+ Vector AVP in answer messages indicates that the default traffic
+ abatement algorithm described in this specification is selected
+ (while other traffic abatement algorithms may be supported), and no
+ features other than abatement algorithms are supported.
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 25]
+
+RFC 7683 DOIC October 2015
+
+
+ The following capability is defined in this document:
+
+ OLR_DEFAULT_ALGO (0x0000000000000001)
+
+ When this flag is set by the a DOIC reacting node, it means that
+ the default traffic abatement (loss) algorithm is supported. When
+ this flag is set by a DOIC reporting node, it means that the loss
+ algorithm will be used for requested overload abatement.
+
+7.3. OC-OLR AVP
+
+ The OC-OLR AVP (AVP Code 623) is of type Grouped and contains the
+ information necessary to convey an overload report on an overload
+ condition at the reporting node. The application the OC-OLR AVP
+ applies to is identified by the Application-ID found in the Diameter
+ message header. The host or realm the OC-OLR AVP concerns is
+ determined from the Origin-Host AVP and/or Origin-Realm AVP found in
+ the encapsulating Diameter command. The OC-OLR AVP is intended to be
+ sent only by a reporting node.
+
+ OC-OLR ::= < AVP Header: 623 >
+ < OC-Sequence-Number >
+ < OC-Report-Type >
+ [ OC-Reduction-Percentage ]
+ [ OC-Validity-Duration ]
+ * [ AVP ]
+
+7.4. OC-Sequence-Number AVP
+
+ The OC-Sequence-Number AVP (AVP Code 624) is of type Unsigned64. Its
+ usage in the context of overload control is described in Section 5.2.
+
+ From the functionality point of view, the OC-Sequence-Number AVP is
+ used as a nonvolatile increasing counter for a sequence of overload
+ reports between two DOIC nodes for the same overload occurrence.
+ Sequence numbers are treated in a unidirectional manner, i.e., two
+ sequence numbers in each direction between two DOIC nodes are not
+ related or correlated.
+
+7.5. OC-Validity-Duration AVP
+
+ The OC-Validity-Duration AVP (AVP Code 625) is of type Unsigned32 and
+ indicates in seconds the validity time of the overload report. The
+ number of seconds is measured after reception of the first OC-OLR AVP
+ with a given value of OC-Sequence-Number AVP. The default value for
+ the OC-Validity-Duration AVP is 30 seconds. When the OC-Validity-
+ Duration AVP is not present in the OC-OLR AVP, the default value
+ applies. The maximum value for the OC-Validity-Duration AVP is
+
+
+
+Korhonen, et al. Standards Track [Page 26]
+
+RFC 7683 DOIC October 2015
+
+
+ 86,400 seconds (24 hours). If the value received in the OC-Validity-
+ Duration is greater than the maximum value, then the default value
+ applies.
+
+7.6. OC-Report-Type AVP
+
+ The OC-Report-Type AVP (AVP Code 626) is of type Enumerated. The
+ value of the AVP describes what the overload report concerns. The
+ following values are initially defined:
+
+ HOST_REPORT 0
+ The overload report is for a host. Overload abatement treatment
+ applies to host-routed requests.
+
+ REALM_REPORT 1
+ The overload report is for a realm. Overload abatement treatment
+ applies to realm-routed requests.
+
+ The values 2-4294967295 are unassigned.
+
+7.7. OC-Reduction-Percentage AVP
+
+ The OC-Reduction-Percentage AVP (AVP Code 627) is of type Unsigned32
+ and describes the percentage of the traffic that the sender is
+ requested to reduce, compared to what it otherwise would send. The
+ OC-Reduction-Percentage AVP applies to the default (loss) algorithm
+ specified in this specification. However, the AVP can be reused for
+ future abatement algorithms, if its semantics fit into the new
+ algorithm.
+
+ The value of the Reduction-Percentage AVP is between zero (0) and one
+ hundred (100). Values greater than 100 are ignored. The value of
+ 100 means that all traffic is to be throttled, i.e., the reporting
+ node is under a severe load and ceases to process any new messages.
+ The value of 0 means that the reporting node is in a stable state and
+ has no need for the reacting node to apply any traffic abatement.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 27]
+
+RFC 7683 DOIC October 2015
+
+
+7.8. AVP Flag Rules
+
+ +---------+
+ |AVP flag |
+ |rules |
+ +----+----+
+ AVP Section | |MUST|
+ Attribute Name Code Defined Value Type |MUST| NOT|
+ +--------------------------------------------------+----+----+
+ |OC-Supported-Features 621 7.1 Grouped | | V |
+ +--------------------------------------------------+----+----+
+ |OC-Feature-Vector 622 7.2 Unsigned64 | | V |
+ +--------------------------------------------------+----+----+
+ |OC-OLR 623 7.3 Grouped | | V |
+ +--------------------------------------------------+----+----+
+ |OC-Sequence-Number 624 7.4 Unsigned64 | | V |
+ +--------------------------------------------------+----+----+
+ |OC-Validity-Duration 625 7.5 Unsigned32 | | V |
+ +--------------------------------------------------+----+----+
+ |OC-Report-Type 626 7.6 Enumerated | | V |
+ +--------------------------------------------------+----+----+
+ |OC-Reduction | | |
+ | -Percentage 627 7.7 Unsigned32 | | V |
+ +--------------------------------------------------+----+----+
+
+ As described in the Diameter base protocol [RFC6733], the M-bit usage
+ for a given AVP in a given command may be defined by the application.
+
+8. Error Response Codes
+
+ When a DOIC node rejects a Diameter request due to overload, the DOIC
+ node MUST select an appropriate error response code. This
+ determination is made based on the probability of the request
+ succeeding if retried on a different path.
+
+ Note: This only applies for DOIC nodes that are not the originator
+ of the request.
+
+ A reporting node rejecting a Diameter request due to an overload
+ condition SHOULD send a DIAMETER_TOO_BUSY error response, if it can
+ assume that the same request may succeed on a different path.
+
+ If a reporting node knows or assumes that the same request will not
+ succeed on a different path, the DIAMETER_UNABLE_TO_COMPLY error
+ response SHOULD be used. Retrying would consume valuable resources
+ during an occurrence of overload.
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 28]
+
+RFC 7683 DOIC October 2015
+
+
+ For instance, if the request arrived at the reporting node without
+ a Destination-Host AVP, then the reporting node might determine
+ that there is an alternative Diameter node that could successfully
+ process the request and that retrying the transaction would not
+ negatively impact the reporting node. DIAMETER_TOO_BUSY would be
+ sent in this case.
+
+ If the request arrived at the reporting node with a Destination-
+ Host AVP populated with its own Diameter identity, then the
+ reporting node can assume that retrying the request would result
+ in it coming to the same reporting node.
+ DIAMETER_UNABLE_TO_COMPLY would be sent in this case.
+
+ A second example is when an agent that supports the DOIC solution
+ is performing the role of a reacting node for a non-supporting
+ client. Requests that are rejected as a result of DOIC throttling
+ by the agent in this scenario would generally be rejected with a
+ DIAMETER_UNABLE_TO_COMPLY response code.
+
+9. IANA Considerations
+
+9.1. AVP Codes
+
+ New AVPs defined by this specification are listed in Section 7. All
+ AVP codes are allocated from the "AVP Codes" sub-registry under the
+ "Authentication, Authorization, and Accounting (AAA) Parameters"
+ registry.
+
+9.2. New Registries
+
+ Two new registries have been created in the "AVP Specific Values"
+ sub-registry under the "Authentication, Authorization, and Accounting
+ (AAA) Parameters" registry.
+
+ A new "OC-Feature-Vector AVP Values (code 622)" registry has been
+ created. This registry contains the following:
+
+ Feature Vector Value Name
+
+ Feature Vector Value
+
+ Specification defining the new value
+
+ See Section 7.2 for the initial Feature Vector Value in the registry.
+ This specification defines the value. New values can be added to the
+ registry using the Specification Required policy [RFC5226].
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 29]
+
+RFC 7683 DOIC October 2015
+
+
+ A new "OC-Report-Type AVP Values (code 626)" registry has been
+ created. This registry contains the following:
+
+ Report Type Value Name
+
+ Report Type Value
+
+ Specification defining the new value
+
+ See Section 7.6 for the initial assignment in the registry. New
+ types can be added using the Specification Required policy [RFC5226].
+
+10. Security Considerations
+
+ DOIC gives Diameter nodes the ability to request that downstream
+ nodes send fewer Diameter requests. Nodes do this by exchanging
+ overload reports that directly effect this reduction. This exchange
+ is potentially subject to multiple methods of attack and has the
+ potential to be used as a denial-of-service (DoS) attack vector. For
+ instance, a series of injected realm OLRs with a requested reduction
+ percentage of 100% could be used to completely eliminate any traffic
+ from being sent to that realm.
+
+ Overload reports may contain information about the topology and
+ current status of a Diameter network. This information is
+ potentially sensitive. Network operators may wish to control
+ disclosure of overload reports to unauthorized parties to avoid their
+ use for competitive intelligence or to target attacks.
+
+ Diameter does not include features to provide end-to-end
+ authentication, integrity protection, or confidentiality. This may
+ cause complications when sending overload reports between non-
+ adjacent nodes.
+
+10.1. Potential Threat Modes
+
+ The Diameter protocol involves transactions in the form of requests
+ and answers exchanged between clients and servers. These clients and
+ servers may be peers, that is, they may share a direct transport
+ (e.g., TCP or SCTP) connection, or the messages may traverse one or
+ more intermediaries, known as Diameter Agents. Diameter nodes use
+ TLS, DTLS, or IPsec to authenticate peers and to provide
+ confidentiality and integrity protection of traffic between peers.
+ Nodes can make authorization decisions based on the peer identities
+ authenticated at the transport layer.
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 30]
+
+RFC 7683 DOIC October 2015
+
+
+ When agents are involved, this presents an effectively transitive
+ trust model. That is, a Diameter client or server can authorize an
+ agent for certain actions, but it must trust that agent to make
+ appropriate authorization decisions about its peers, and so on.
+ Since confidentiality and integrity protection occur at the transport
+ layer, agents can read, and perhaps modify, any part of a Diameter
+ message, including an overload report.
+
+ There are several ways an attacker might attempt to exploit the
+ overload control mechanism. An unauthorized third party might inject
+ an overload report into the network. If this third party is upstream
+ of an agent, and that agent fails to apply proper authorization
+ policies, downstream nodes may mistakenly trust the report. This
+ attack is at least partially mitigated by the assumption that nodes
+ include overload reports in Diameter answers but not in requests.
+ This requires an attacker to have knowledge of the original request
+ in order to construct an answer. Such an answer would also need to
+ arrive at a Diameter node via a protected transport connection.
+ Therefore, implementations MUST validate that an answer containing an
+ overload report is a properly constructed response to a pending
+ request prior to acting on the overload report, and that the answer
+ was received via an appropriate transport connection.
+
+ A similar attack involves a compromised but otherwise authorized node
+ that sends an inappropriate overload report. For example, a server
+ for the realm "example.com" might send an overload report indicating
+ that a competitor's realm "example.net" is overloaded. If other
+ nodes act on the report, they may falsely believe that "example.net"
+ is overloaded, effectively reducing that realm's capacity.
+ Therefore, it's critical that nodes validate that an overload report
+ received from a peer actually falls within that peer's responsibility
+ before acting on the report or forwarding the report to other peers.
+ For example, an overload report from a peer that applies to a realm
+ not handled by that peer is suspect. This may require out-of-band,
+ non-Diameter agreements and/or mechanisms.
+
+ This attack is partially mitigated by the fact that the
+ application, as well as host and realm, for a given OLR is
+ determined implicitly by respective AVPs in the enclosing answer.
+ If a reporting node modifies any of those AVPs, the enclosing
+ transaction will also be affected.
+
+10.2. Denial-of-Service Attacks
+
+ Diameter overload reports, especially realm reports, can cause a node
+ to cease sending some or all Diameter requests for an extended
+ period. This makes them a tempting vector for DoS attacks.
+ Furthermore, since Diameter is almost always used in support of other
+
+
+
+Korhonen, et al. Standards Track [Page 31]
+
+RFC 7683 DOIC October 2015
+
+
+ protocols, a DoS attack on Diameter is likely to impact those
+ protocols as well. In the worst case, where the Diameter application
+ is being used for access control into an IP network, a coordinated
+ DoS attack could result in the blockage of all traffic into that
+ network. Therefore, Diameter nodes MUST NOT honor or forward OLRs
+ received from peers that are not trusted to send them.
+
+ An attacker might use the information in an OLR to assist in DoS
+ attacks. For example, an attacker could use information about
+ current overload conditions to time an attack for maximum effect, or
+ use subsequent overload reports as a feedback mechanism to learn the
+ results of a previous or ongoing attack. Operators need the ability
+ to ensure that OLRs are not leaked to untrusted parties.
+
+10.3. Noncompliant Nodes
+
+ In the absence of an overload control mechanism, Diameter nodes need
+ to implement strategies to protect themselves from floods of
+ requests, and to make sure that a disproportionate load from one
+ source does not prevent other sources from receiving service. For
+ example, a Diameter server might throttle a certain percentage of
+ requests from sources that exceed certain limits. Overload control
+ can be thought of as an optimization for such strategies, where
+ downstream nodes never send the excess requests in the first place.
+ However, the presence of an overload control mechanism does not
+ remove the need for these other protection strategies.
+
+ When a Diameter node sends an overload report, it cannot assume that
+ all nodes will comply, even if they indicate support for DOIC. A
+ noncompliant node might continue to send requests with no reduction
+ in load. Such noncompliance could be done accidentally or
+ maliciously to gain an unfair advantage over compliant nodes.
+ Requirement 28 in [RFC7068] indicates that the overload control
+ solution cannot assume that all Diameter nodes in a network are
+ trusted. It also requires that malicious nodes not be allowed to
+ take advantage of the overload control mechanism to get more than
+ their fair share of service.
+
+10.4. End-to-End Security Issues
+
+ The lack of end-to-end integrity features makes it difficult to
+ establish trust in overload reports received from non-adjacent nodes.
+ Any agents in the message path may insert or modify overload reports.
+ Nodes must trust that their adjacent peers perform proper checks on
+ overload reports from their peers, and so on, creating a transitive-
+ trust requirement extending for potentially long chains of nodes.
+ Network operators must determine if this transitive trust requirement
+ is acceptable for their deployments. Nodes supporting Diameter
+
+
+
+Korhonen, et al. Standards Track [Page 32]
+
+RFC 7683 DOIC October 2015
+
+
+ overload control MUST give operators the ability to select which
+ peers are trusted to deliver overload reports and whether they are
+ trusted to forward overload reports from non-adjacent nodes. DOIC
+ nodes MUST strip DOIC AVPs from messages received from peers that are
+ not trusted for DOIC purposes.
+
+ The lack of end-to-end confidentiality protection means that any
+ Diameter Agent in the path of an overload report can view the
+ contents of that report. In addition to the requirement to select
+ which peers are trusted to send overload reports, operators MUST be
+ able to select which peers are authorized to receive reports. A node
+ MUST NOT send an overload report to a peer not authorized to receive
+ it. Furthermore, an agent MUST remove any overload reports that
+ might have been inserted by other nodes before forwarding a Diameter
+ message to a peer that is not authorized to receive overload reports.
+
+ A DOIC node cannot always automatically detect that a peer also
+ supports DOIC. For example, a node might have a peer that is a
+ non-supporting agent. If nodes on the other side of that agent
+ send OC-Supported-Features AVPs, the agent is likely to forward
+ them as unknown AVPs. Messages received across the non-supporting
+ agent may be indistinguishable from messages received across a
+ DOIC supporting agent, giving the false impression that the non-
+ supporting agent actually supports DOIC. This complicates the
+ transitive-trust nature of DOIC. Operators need to be careful to
+ avoid situations where a non-supporting agent is mistakenly
+ trusted to enforce DOIC-related authorization policies.
+
+ It is expected that work on end-to-end Diameter security might make
+ it easier to establish trust in non-adjacent nodes for overload
+ control purposes. Readers should be reminded, however, that the
+ overload control mechanism allows Diameter Agents to modify AVPs in,
+ or insert additional AVPs into, existing messages that are originated
+ by other nodes. If end-to-end security is enabled, there is a risk
+ that such modification could violate integrity protection. The
+ details of using any future Diameter end-to-end security mechanism
+ with overload control will require careful consideration, and are
+ beyond the scope of this document.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 33]
+
+RFC 7683 DOIC October 2015
+
+
+11. References
+
+11.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
+ IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+ DOI 10.17487/RFC5226, May 2008,
+ <http://www.rfc-editor.org/info/rfc5226>.
+
+ [RFC6733] Fajardo, V., Ed., Arkko, J., Loughney, J., and G. Zorn,
+ Ed., "Diameter Base Protocol", RFC 6733,
+ DOI 10.17487/RFC6733, October 2012,
+ <http://www.rfc-editor.org/info/rfc6733>.
+
+11.2. Informative References
+
+ [Cx] 3GPP, "Cx and Dx interfaces based on the Diameter
+ protocol; Protocol details", 3GPP TS 29.229 12.7.0,
+ September 2015.
+
+ [PCC] 3GPP, "Policy and charging control architecture", 3GPP
+ TS 23.203 12.10.0, September 2015.
+
+ [RFC4006] Hakala, H., Mattila, L., Koskinen, J-P., Stura, M., and J.
+ Loughney, "Diameter Credit-Control Application", RFC 4006,
+ DOI 10.17487/RFC4006, August 2005,
+ <http://www.rfc-editor.org/info/rfc4006>.
+
+ [RFC7068] McMurry, E. and B. Campbell, "Diameter Overload Control
+ Requirements", RFC 7068, DOI 10.17487/RFC7068, November
+ 2013, <http://www.rfc-editor.org/info/rfc7068>.
+
+ [S13] 3GPP, "Evolved Packet System (EPS); Mobility Management
+ Entity (MME) and Serving GPRS Support Node (SGSN) related
+ interfaces based on Diameter protocol", 3GPP TS 29.272
+ 12.8.0, September 2015.
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 34]
+
+RFC 7683 DOIC October 2015
+
+
+Appendix A. Issues Left for Future Specifications
+
+ The base solution for overload control does not cover all possible
+ use cases. A number of solution aspects were intentionally left for
+ future specification and protocol work. The following subsections
+ define some of the potential extensions to the DOIC solution.
+
+A.1. Additional Traffic Abatement Algorithms
+
+ This specification describes only means for a simple loss-based
+ algorithm. Future algorithms can be added using the designed
+ solution extension mechanism. The new algorithms need to be
+ registered with IANA. See Sections 7.2 and 9 for the required IANA
+ steps.
+
+A.2. Agent Overload
+
+ This specification focuses on Diameter endpoint (server or client)
+ overload. A separate extension will be required to outline the
+ handling of the case of agent overload.
+
+A.3. New Error Diagnostic AVP
+
+ This specification indicates the use of existing error messages when
+ nodes reject requests due to overload. There is an expectation that
+ additional error codes or AVPs will be defined in a separate
+ specification to indicate that overload was the reason for the
+ rejection of the message.
+
+Appendix B. Deployment Considerations
+
+ Non-supporting Agents
+
+ Due to the way that realm-routed requests are handled in Diameter
+ networks with the server selection for the request done by an
+ agent, network operators should enable DOIC at agents that perform
+ server selection first.
+
+ Topology-Hiding Interactions
+
+ There exist proxies that implement what is referred to as Topology
+ Hiding. This can include cases where the agent modifies the
+ Origin-Host in answer messages. The behavior of the DOIC solution
+ is not well understood when this happens. As such, the DOIC
+ solution does not address this scenario.
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 35]
+
+RFC 7683 DOIC October 2015
+
+
+ Inter-Realm/Administrative Domain Considerations
+
+ There are likely to be special considerations for handling DOIC
+ signaling across administrative boundaries. This includes
+ considerations for whether or not information included in the DOIC
+ signaling should be sent across those boundaries. In addition,
+ consideration should be taken as to whether or not a reacting node
+ in one realm can be trusted to implement the requested overload
+ abatement handling for overload reports received from a separately
+ administered realm.
+
+Appendix C. Considerations for Applications Integrating the DOIC
+ Solution
+
+ This section outlines considerations to be taken into account when
+ integrating the DOIC solution into Diameter applications.
+
+C.1. Application Classification
+
+ The following is a classification of Diameter applications and
+ request types. This discussion is meant to document factors that
+ play into decisions made by the Diameter entity responsible for
+ handling overload reports.
+
+ Section 8.1 of [RFC6733] defines two state machines that imply two
+ types of applications, session-less and session-based applications.
+ The primary difference between these types of applications is the
+ lifetime of Session-Ids.
+
+ For session-based applications, the Session-Id is used to tie
+ multiple requests into a single session.
+
+ The Credit-Control application defined in [RFC4006] is an example of
+ a Diameter session-based application.
+
+ In session-less applications, the lifetime of the Session-Id is a
+ single Diameter transaction, i.e., the session is implicitly
+ terminated after a single Diameter transaction and a new Session-Id
+ is generated for each Diameter request.
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 36]
+
+RFC 7683 DOIC October 2015
+
+
+ For the purposes of this discussion, session-less applications are
+ further divided into two types of applications:
+
+ Stateless Applications:
+
+ Requests within a stateless application have no relationship to
+ each other. The 3GPP-defined S13 application is an example of a
+ stateless application [S13], where only a Diameter command is
+ defined between a client and a server and no state is maintained
+ between two consecutive transactions.
+
+ Pseudo-Session Applications:
+
+ Applications that do not rely on the Session-Id AVP for
+ correlation of application messages related to the same session
+ but use other session-related information in the Diameter requests
+ for this purpose. The 3GPP-defined Cx application [Cx] is an
+ example of a pseudo-session application.
+
+ The handling of overload reports must take the type of application
+ into consideration, as discussed in Appendix C.2.
+
+C.2. Implications of Application Type Overload
+
+ This section discusses considerations for mitigating overload
+ reported by a Diameter entity. This discussion focuses on the type
+ of application. Appendix C.3 discusses considerations for handling
+ various request types when the target server is known to be in an
+ overloaded state.
+
+ These discussions assume that the strategy for mitigating the
+ reported overload is to reduce the overall workload sent to the
+ overloaded entity. The concept of applying overload treatment to
+ requests targeted for an overloaded Diameter entity is inherent to
+ this discussion. The method used to reduce offered load is not
+ specified here, but it could include routing requests to another
+ Diameter entity known to be able to handle them, or it could mean
+ rejecting certain requests. For a Diameter Agent, rejecting requests
+ will usually mean generating appropriate Diameter error responses.
+ For a Diameter client, rejecting requests will depend upon the
+ application. For example, it could mean giving an indication to the
+ entity requesting the Diameter service that the network is busy and
+ to try again later.
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 37]
+
+RFC 7683 DOIC October 2015
+
+
+ Stateless Applications:
+
+ By definition, there is no relationship between individual
+ requests in a stateless application. As a result, when a request
+ is sent or relayed to an overloaded Diameter entity -- either a
+ Diameter Server or a Diameter Agent -- the sending or relaying
+ entity can choose to apply the overload treatment to any request
+ targeted for the overloaded entity.
+
+ Pseudo-session Applications:
+
+ For pseudo-session applications, there is an implied ordering of
+ requests. As a result, decisions about which requests towards an
+ overloaded entity to reject could take the command code of the
+ request into consideration. This generally means that
+ transactions later in the sequence of transactions should be given
+ more favorable treatment than messages earlier in the sequence.
+ This is because more work has already been done by the Diameter
+ network for those transactions that occur later in the sequence.
+ Rejecting them could result in increasing the load on the network
+ as the transactions earlier in the sequence might also need to be
+ repeated.
+
+ Session-Based Applications:
+
+ Overload handling for session-based applications must take into
+ consideration the work load associated with setting up and
+ maintaining a session. As such, the entity sending requests
+ towards an overloaded Diameter entity for a session-based
+ application might tend to reject new session requests prior to
+ rejecting intra-session requests. In addition, session-ending
+ requests might be given a lower probability of being rejected, as
+ rejecting session-ending requests could result in session status
+ being out of sync between the Diameter clients and servers.
+ Application designers that would decide to reject mid-session
+ requests will need to consider whether the rejection invalidates
+ the session and any resulting session cleanup procedures.
+
+C.3. Request Transaction Classification
+
+ Independent Request:
+
+ An independent request is not correlated to any other requests,
+ and, as such, the lifetime of the Session-Id is constrained to an
+ individual transaction.
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 38]
+
+RFC 7683 DOIC October 2015
+
+
+ Session-Initiating Request:
+
+ A session-initiating request is the initial message that
+ establishes a Diameter session. The ACR message defined in
+ [RFC6733] is an example of a session-initiating request.
+
+ Correlated Session-Initiating Request:
+
+ There are cases when multiple session-initiated requests must be
+ correlated and managed by the same Diameter server. It is notably
+ the case in the 3GPP Policy and Charging Control (PCC)
+ architecture [PCC], where multiple apparently independent Diameter
+ application sessions are actually correlated and must be handled
+ by the same Diameter server.
+
+ Intra-session Request:
+
+ An intra-session request is a request that uses the same Session-
+ Id as the one used in a previous request. An intra-session
+ request generally needs to be delivered to the server that handled
+ the session-creating request for the session. The STR message
+ defined in [RFC6733] is an example of an intra-session request.
+
+ Pseudo-session Requests:
+
+ Pseudo-session requests are independent requests and do not use
+ the same Session-Id but are correlated by other session-related
+ information contained in the request. There exist Diameter
+ applications that define an expected ordering of transactions.
+ This sequencing of independent transactions results in a pseudo-
+ session. The AIR, MAR, and SAR requests in the 3GPP-defined Cx
+ [Cx] application are examples of pseudo-session requests.
+
+C.4. Request Type Overload Implications
+
+ The request classes identified in Appendix C.3 have implications on
+ decisions about which requests should be throttled first. The
+ following list of request treatments regarding throttling is provided
+ as guidelines for application designers when implementing the
+ Diameter overload control mechanism described in this document. The
+ exact behavior regarding throttling is a matter of local policy,
+ unless specifically defined for the application.
+
+ Independent Requests:
+
+ Independent requests can generally be given equal treatment when
+ making throttling decisions, unless otherwise indicated by
+ application requirements or local policy.
+
+
+
+Korhonen, et al. Standards Track [Page 39]
+
+RFC 7683 DOIC October 2015
+
+
+ Session-Initiating Requests:
+
+ Session-initiating requests often represent more work than
+ independent or intra-session requests. Moreover, session-
+ initiating requests are typically followed by other session-
+ related requests. Since the main objective of overload control is
+ to reduce the total number of requests sent to the overloaded
+ entity, throttling decisions might favor allowing intra-session
+ requests over session-initiating requests. In the absence of
+ local policies or application-specific requirements to the
+ contrary, individual session-initiating requests can be given
+ equal treatment when making throttling decisions.
+
+ Correlated Session-Initiating Requests:
+
+ A request that results in a new binding; where the binding is used
+ for routing of subsequent session-initiating requests to the same
+ server, it represents more work load than other requests. As
+ such, these requests might be throttled more frequently than other
+ request types.
+
+ Pseudo-session Requests:
+
+ Throttling decisions for pseudo-session requests can take into
+ consideration where individual requests fit into the overall
+ sequence of requests within the pseudo-session. Requests that are
+ earlier in the sequence might be throttled more aggressively than
+ requests that occur later in the sequence.
+
+ Intra-session Requests:
+
+ There are two types of intra-sessions requests, requests that
+ terminate a session and the remainder of intra-session requests.
+ Implementers and operators may choose to throttle session-
+ terminating requests less aggressively in order to gracefully
+ terminate sessions, allow cleanup of the related resources (e.g.,
+ session state), and avoid the need for additional intra-session
+ requests. Favoring session termination requests may reduce the
+ session management impact on the overloaded entity. The default
+ handling of other intra-session requests might be to treat them
+ equally when making throttling decisions. There might also be
+ application-level considerations whether some request types are
+ favored over others.
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 40]
+
+RFC 7683 DOIC October 2015
+
+
+Contributors
+
+ The following people contributed substantial ideas, feedback, and
+ discussion to this document:
+
+ o Eric McMurry
+
+ o Hannes Tschofenig
+
+ o Ulrich Wiehe
+
+ o Jean-Jacques Trottin
+
+ o Maria Cruz Bartolome
+
+ o Martin Dolly
+
+ o Nirav Salot
+
+ o Susan Shishufeng
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 41]
+
+RFC 7683 DOIC October 2015
+
+
+Authors' Addresses
+
+ Jouni Korhonen (editor)
+ Broadcom Corporation
+ 3151 Zanker Road
+ San Jose, CA 95134
+ United States
+
+
+
+ Steve Donovan (editor)
+ Oracle
+ 7460 Warren Parkway
+ Frisco, Texas 75034
+ United States
+
+
+
+ Ben Campbell
+ Oracle
+ 7460 Warren Parkway
+ Frisco, Texas 75034
+ United States
+
+
+
+ Lionel Morand
+ Orange Labs
+ 38/40 rue du General Leclerc
+ Issy-Les-Moulineaux Cedex 9 92794
+ France
+
+ Phone: +33145296257
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Korhonen, et al. Standards Track [Page 42]
+