aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r--lib/diameter/doc/src/Makefile6
-rw-r--r--lib/diameter/doc/src/depend.sed12
-rw-r--r--lib/diameter/doc/src/diameter.xml156
-rw-r--r--lib/diameter/doc/src/diameter_compile.xml32
-rw-r--r--lib/diameter/doc/src/diameter_dict.xml157
-rw-r--r--lib/diameter/doc/src/diameter_soc.xml10
-rw-r--r--lib/diameter/doc/src/diameter_tcp.xml50
-rw-r--r--lib/diameter/doc/src/diameter_transport.xml38
-rw-r--r--lib/diameter/doc/src/notes.xml114
9 files changed, 483 insertions, 92 deletions
diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile
index 1453138cb6..bc3e649e6b 100644
--- a/lib/diameter/doc/src/Makefile
+++ b/lib/diameter/doc/src/Makefile
@@ -126,8 +126,6 @@ debug opt:
info:
@echo "->Makefile<-"
@echo ""
- @echo "DOCSUPPORT = $(DOCSUPPORT)"
- @echo ""
@echo "INDEX_FILE = $(INDEX_FILE)"
@echo "INDEX_SRC = $(INDEX_SRC)"
@echo "INDEX_TARGET = $(INDEX_TARGET)"
@@ -141,10 +139,6 @@ info:
@echo ""
@echo "GIF_FILES = $(GIF_FILES)"
@echo ""
- @echo "TEX_FILES_USERS_GUIDE = $(TEX_FILES_USERS_GUIDE)"
- @echo "TEX_FILES_REF_MAN = $(TEX_FILES_REF_MAN)"
- @echo "TEX_FILES_BOOK = $(TEX_FILES_BOOK)"
- @echo ""
@echo "MAN1_FILES = $(MAN1_FILES)"
@echo "MAN3_FILES = $(MAN3_FILES)"
@echo "MAN4_FILES = $(MAN4_FILES)"
diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed
index 5973c4586e..42de597f15 100644
--- a/lib/diameter/doc/src/depend.sed
+++ b/lib/diameter/doc/src/depend.sed
@@ -21,14 +21,18 @@
# massaged in Makefile.
#
-/^<com>\([^<]*\)<\/com>/b rf
-/^<module>\([^<]*\)<\/module>/b rf
+/^<com>/b c
+/^<module>/b c
/^<chapter>/!d
+# Chapter: html basename is same as xml.
s@@$(HTMLDIR)/%FILE%.html: %FILE%.xml@
q
-:rf
-s@@$(HTMLDIR)/\1.html: %FILE%.xml@
+# Reference: html basename is from contents of com/module element.
+:c
+s@^[^>]*>@@
+s@<.*@@
+s@.*@$(HTMLDIR)/&.html: %FILE%.xml@
q
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 2cad70e3bc..93e2603c10 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -107,7 +107,9 @@ belonging to the application.</p>
<marker id="application_module"/>
</item>
-<tag><c>application_module() = Mod | [Mod | ExtraArgs]</c></tag>
+<tag><c>application_module() = Mod
+ | [Mod | ExtraArgs]
+ | #diameter_callback{}</c></tag>
<item>
<code>
Mod = atom()
@@ -125,6 +127,14 @@ specified to <seealso marker="#call">call/4</seealso>, in which case
the call-specific arguments are appended to any specified with the
callback module.</p>
+<p>
+Specifying a <c>#diameter_callback{}</c> record allows individual
+functions to be configured in place of the usual <seealso
+marker="diameter_app">diameter_app(3)</seealso> callbacks, with
+default implementations provided by module <c>diameter_callback</c>
+unless otherwise specified.
+See that module for details.</p>
+
<marker id="application_opt"/>
</item>
@@ -367,6 +377,19 @@ capabilities exchange message.
Optional, defaults to the empty list.</p>
</item>
+<tag><c>{'Inband-Security-Id', [Unsigned32()]}</c></tag>
+<item>
+<p>
+Values of Inband-Security-Id AVPs sent in an outgoing
+capabilities exchange message.
+Optional, defaults to the empty list, which is equivalent to a
+list containing only 0 (= NO_INBAND_SECURITY).</p>
+
+<p>
+If 1 (= TLS) is specified then TLS is selected if the CER/CEA received
+from the peer offers it.</p>
+</item>
+
<tag><c>{'Acct-Application-Id', [Unsigned32()]}</c></tag>
<item>
<p>
@@ -418,7 +441,7 @@ eval(F) ->
</code>
<p>
-Evaluating an evaluable() <c>E</c> on an argument list <c>A</c>
+Applying an evaluable() <c>E</c> to an argument list <c>A</c>
is meant in the sense of <c>eval([E|A])</c>.</p>
<p>
@@ -552,7 +575,7 @@ Pkt = #diameter_packet{}
</code>
<p>
-Reports that the RFC 3539 watchdog state machine has
+The RFC 3539 watchdog state machine has
transitioned into (<c>up</c>) or out of (<c>down</c>) the open
state.
If a <c>diameter_packet</c> record is present in an <c>up</c> tuple
@@ -563,9 +586,9 @@ connectivity.</p>
<p>
Note that a single up/down event for a given peer corresponds to
-as many peer_up/down callbacks as there are Diameter
-applications shared by the peer, as determined during capablilities
-exchange.
+as many <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso>
+callbacks as there are Diameter applications shared by the peer,
+as determined during capablilities exchange.
That is, the event communicates connectivity with the
peer as a whole while the callbacks communicate connectivity with
respect to individual Diameter applications.</p>
@@ -584,12 +607,96 @@ transport connection with a peer following <c>reconnect_timer</c> or
<c>watchdog_timer</c> expiry.</p>
</item>
+<tag><c>{closed, Ref, Reason, Config}</c></tag>
+<item>
+<code>
+Ref = transport_ref()
+Config = {connect|listen, [transport_opt()]}
+</code>
+
+<p>
+Capabilities exchange has failed. <c>Reason</c> can be one of
+the following.</p>
+
+<taglist>
+
+<tag><c>{'CER', Result, Caps, Pkt}</c></tag>
+<item>
+<code>
+Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
+Caps = #diameter_caps{}
+Pkt = #diameter_packet{}
+ResultCode = integer()
+CB = evaluable()
+</code>
+
+<p>
+An incoming CER has been answered with the indicated result code or
+discarded.
+The capabilities record contains pairs of values for the the local
+node and remote peer.
+The packet record contains the CER in question.
+In the case of rejection by a capabilities callback, the tuple
+indicates the rejecting callback.</p>
+</item>
+
+<tag><c>{'CER', Caps, {ResultCode, Pkt}}</c></tag>
+<item>
+<code>
+ResultCode = integer()
+Caps = #diameter_caps{}
+Pkt = #diameter_packet{}
+</code>
+
+<p>
+An incoming CER contained errors and has been answered with the
+indicated result code.
+The capabilities record contains only values for the the local
+node.
+The packet record contains the CER in question.</p>
+</item>
+
+<tag><c>{'CEA', Result, Caps, Pkt}</c></tag>
+<item>
+<code>
+Result = integer() | atom() | {capabilities_cb, CB, ResultCode|discard}
+Caps = #diameter_caps{}
+Pkt = #diameter_packet{}
+ResultCode = integer()
+</code>
+
+<p>
+An incoming CEA has been rejected for the indicated reason.
+An integer-valued <c>Result</c> indicates the result code sent
+by the peer.
+The capabilities record contains pairs of values for the the local
+node and remote peer.
+The packet record contains the CEA in question.
+In the case of rejection by a capabilities callback, the tuple
+indicates the rejecting callback.</p>
+</item>
+
+<tag><c>{'CEA', Caps, Pkt}</c></tag>
+<item>
+<code>
+Caps = #diameter_caps{}
+Pkt = #diameter_packet{}
+</code>
+
+<p>
+An incoming CER contained errors and has been rejected.
+The capabilities record contains only values for the the local node.
+The packet record contains the CEA in question.</p>
+</item>
+
+</taglist>
+</item>
+
</taglist>
<p>
For forward compatibility, a subscriber should be prepared to receive
-<c>diameter_event.info</c> of forms other than those documented
-above.</p>
+info fields of forms other than the above.</p>
<marker id="service_name"/>
</item>
@@ -683,6 +790,39 @@ in question.</p>
AVP's used to construct outgoing CER/CEA messages.
Any AVP specified takes precedence over a corresponding value specified
for the service in question.</p>
+
+<p>
+Specifying a capability as a transport option
+may be particularly appropriate for Inband-Security-Id in case
+TLS is desired over TCP as implemented by
+<seealso marker="diameter_tcp">diameter_tcp(3)</seealso> but
+not over SCTP as implemented by
+<seealso marker="diameter_sctp">diameter_sctp(3)</seealso>.</p>
+</item>
+
+<tag><c>{capabilities_cb, evaluable()}</c></tag>
+<item>
+<p>
+A callback invoked upon reception of CER/CEA during capabilities
+exchange in order to ask whether or not the connection should
+be accepted.
+Applied to the transport reference (as returned by <seealso
+marker="#add_transport">add_transport/2</seealso>) and
+<c>diameter_caps</c> record of the connection.
+Returning <c>ok</c> accepts the connection.
+Returning <c>integer()</c> causes an incoming
+CER to be answered with the specified Result-Code.
+Returning <c>discard</c> causes an incoming CER to
+be discarded.
+Returning <c>unknown</c> is equivalent to returning <c>3010</c>,
+DIAMETER_UNKNOWN_PEER.
+Returning anything but <c>ok</c> or a 2xxx series result
+code causes the transport connection to be broken.</p>
+
+<p>
+Multiple <c>capabilities_cb</c> options can be specified, in which
+case the corresponding callbacks are applied until either all return
+<c>ok</c> or one does not.</p>
</item>
<tag><c>{watchdog_timer, TwInit}</c></tag>
diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml
index 72bac30709..60e08d41da 100644
--- a/lib/diameter/doc/src/diameter_compile.xml
+++ b/lib/diameter/doc/src/diameter_compile.xml
@@ -64,9 +64,10 @@ Defaults to the current working directory.</p>
<item>
<p>
Specifies a directory to add to the code path.
-Typically used to point at beam files corresponding to dictionaries
-included by the one being compiled (using the <c>@includes</c> directive):
-inclusion is a beam dependency, not an erl/hrl dependency.</p>
+Use to point at beam files corresponding to dictionaries
+inherited by the one being compiled using <c>@inherits</c> or
+<c>--inherits</c>.
+Inheritance is a beam dependency, not an erl/hrl dependency.</p>
<p>
Multiple <c>-i</c> options can be specified.</p>
@@ -84,6 +85,31 @@ Supresses erl generation.</p>
Supresses hrl generation.</p>
</item>
+<tag><![CDATA[--name <name>]]></tag>
+<item>
+<p>
+Set <c>@name</c> in the dictionary file.
+Overrides any setting in the file itself.</p>
+</item>
+
+<tag><![CDATA[--prefix <prefix>]]></tag>
+<item>
+<p>
+Set <c>@prefix</c> in the dictionary file.
+Overrides any setting in the file itself.</p>
+</item>
+
+<tag><![CDATA[--inherits <dict>]]></tag>
+<item>
+<p>
+Append an <c>@inherits</c> to the dictionary file.
+Specifying <c>'-'</c> as the dictionary has the effect of clearing
+any previous inherits, effectively ignoring previous inherits.</p>
+
+<p>
+Multiple <c>--inherits</c> options can be specified.</p>
+</item>
+
</taglist>
</item>
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index e7c530f1b8..cc638dbc18 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -36,7 +36,7 @@ under the License.
<!-- ===================================================================== -->
<file>diameter_dict</file>
-<filesummary>Dictionary inteface of the diameter application.</filesummary>
+<filesummary>Dictionary interface of the diameter application.</filesummary>
<description>
<p>
@@ -44,9 +44,9 @@ A diameter service as configured with <seealso
marker="diameter#start_service">diameter:start_service/2</seealso>
specifies one or more supported Diameter applications.
Each Diameter application specifies a dictionary module that knows how
-to encode and decode its messages and AVP's.
+to encode and decode its messages and AVPs.
The dictionary module is in turn generated from a file that defines
-these messages and AVP's.
+these messages and AVPs.
The format of such a file is defined in
<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below.
Users add support for their specific applications by creating
@@ -56,7 +56,7 @@ resulting dictionaries modules on a service.</p>
<p>
The codec generation also results in a hrl file that defines records
-for the messages and grouped AVP's defined for the application, these
+for the messages and grouped AVPs defined for the application, these
records being what a user of the diameter application sends and receives.
(Modulo other available formats as discussed in <seealso
marker="diameter_app">diameter_app(3)</seealso>.)
@@ -74,14 +74,14 @@ corresponding to applications defined in section 2.4 of RFC 3588:
application with application identifier 0,
<c>diameter_gen_accounting</c> for the Diameter Base Accounting
application with application identifier 3 and
-<c>diameter_gen_relay</c>the Relay application with application
+<c>diameter_gen_relay</c> the Relay application with application
identifier 0xFFFFFFFF.
The Common Message and Relay applications are the only applications
that diameter itself has any specific knowledge of.
The Common Message application is used for messages that diameter
itself handles: CER/CEA, DWR/DWA and DPR/DPA.
The Relay application is given special treatment with regard to
-encode/decode since the messages and AVP's it handles are not specifically
+encode/decode since the messages and AVPs it handles are not specifically
defined.</p>
<marker id="FILE_FORMAT"/>
@@ -94,18 +94,16 @@ defined.</p>
<p>
A dictionary file consists of distinct sections.
-Each section starts with a line consisting of a tag
-followed by zero or more arguments.
-Each section ends at the the start of the next section or end of file.
+Each section starts with a tag followed by zero or more arguments
+and ends at the the start of the next section or end of file.
Tags consist of an ampersand character followed by a keyword and are
separated from their arguments by whitespace.
-Whitespace within a section separates individual tokens but its
-quantity is insignificant.</p>
+Whitespace separates individual tokens but is otherwise insignificant.</p>
<p>
The tags, their arguments and the contents of each corresponding
section are as follows.
-Each section can occur at most once unless otherwise specified.
+Each section can occur multiple times unless otherwise specified.
The order in which sections are specified is unimportant.</p>
<taglist>
@@ -115,7 +113,8 @@ The order in which sections are specified is unimportant.</p>
<p>
Defines the integer Number as the Diameter Application Id of the
application in question.
-Required if the dictionary defines <c>@messages</c>.
+Can occur at most once and is required if the dictionary defines
+<c>@messages</c>.
The section has empty content.</p>
<p>
@@ -136,16 +135,13 @@ Example:</p>
<item>
<p>
Defines the name of the generated dictionary module.
-The section has empty content.
-Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$';
-that is, contains only alphanumerics, hyphens and underscores begin with an
-alphanumeric.</p>
+Can occur at most once and defaults to the name of the dictionary file
+minus any extension if unspecified.
+The section has empty content.</p>
<p>
-A name is optional and defaults to the name of the dictionary file
-minus any extension.
-Note that a generated module must have a unique name an not colide
-with another module in the system.</p>
+Note that a dictionary module should have a unique name so as not collide
+with existing modules in the system.</p>
<p>
Example:</p>
@@ -159,22 +155,22 @@ Example:</p>
<tag><c>@prefix Name</c></tag>
<item>
<p>
-Defines Name as the prefix to be added to record and constant names in
-the generated dictionary module and hrl.
-The section has empty content.
-Name must be of the same form as a @name.</p>
+Defines Name as the prefix to be added to record and constant names
+(followed by a <c>'_'</c> character) in the generated dictionary
+module and hrl.
+Can occur at most once.
+The section has empty content.</p>
<p>
-A prefix is optional but can
-be used to disambiguate record and constant names
-resulting from similarly named messages and AVP's in different
-Diameter applications.</p>
+A prefix is optional but can be be used to disambiguate between record
+and constant names resulting from similarly named messages and AVPs in
+different Diameter applications.</p>
<p>
Example:</p>
<code>
-@prefix etsi_e2_
+@prefix etsi_e2
</code>
</item>
@@ -182,10 +178,12 @@ Example:</p>
<tag><c>@vendor Number Name</c></tag>
<item>
<p>
-Defines the integer Number as the the default Vendor-ID of AVP's for
+Defines the integer Number as the the default Vendor-Id of AVPs for
which the V flag is set.
Name documents the owner of the application
but is otherwise unused.
+Can occur at most once and is required if an AVP sets the V flag and
+is not otherwise assigned a Vendor-Id.
The section has empty content.</p>
<p>
@@ -200,10 +198,9 @@ Example:</p>
<tag><c>@avp_vendor_id Number</c></tag>
<item>
<p>
-Defines the integer Number as the Vendor-ID of the AVP's listed in the
+Defines the integer Number as the Vendor-Id of the AVPs listed in the
section content, overriding the <c>@vendor</c> default.
-The section content consists of AVP names.
-Can occur zero or more times (with different values of Number).</p>
+The section content consists of AVP names.</p>
<p>
Example:</p>
@@ -221,13 +218,27 @@ Region-Set
<tag><c>@inherits Mod</c></tag>
<item>
<p>
-Defines the name of a generated dictionary module containing AVP
-definitions referenced by the dictionary but not defined by it.
-The section content is empty.</p>
+Defines the name of a dictionary module containing AVP
+definitions that should be imported into the current dictionary.
+The section content consists of the names of those AVPs whose
+definitions should be imported from the dictionary, an empty list
+causing all to be imported.
+Any listed AVPs must not be defined in the current dictionary and
+it is an error to inherit the same AVP from more than one
+dictionary.</p>
<p>
-Can occur 0 or more times (with different values of Mod) but all
-dictionaries should typically inherit RFC3588 AVPs from
+Note that an inherited AVP that sets the V flag takes its Vendor-Id
+from either <c>@avp_vendor_id</c> in the inheriting dictionary or
+<c>@vendor</c> in the inherited dictionary.
+In particular, <c>@avp_vendor_id</c> in the inherited dictionary is
+ignored.
+Inheriting from a dictionary that specifies the required <c>@vendor</c>
+is equivalent to using <c>@avp_vendor_id</c> with a copy of the
+dictionary's definitions but the former makes for easier reuse.</p>
+
+<p>
+All dictionaries should typically inherit RFC3588 AVPs from
<c>diameter_gen_base_rfc3588</c>.</p>
<p>
@@ -248,13 +259,11 @@ The section consists of definitions of the form</p>
<p><c>Name Code Type Flags</c></p>
<p>
-where Code is the integer AVP code, Flags is a string of V,
-M and P characters indicating the flags to be
-set on an outgoing AVP or a single - (minus) character if none are to
-be set.
-Type identifies either an AVP Data Format as defined in <seealso
-marker="#DATA_TYPES">DATA TYPES</seealso> below or a
-type as defined by a <c>@custom_types</c> tag.</p>
+where Code is the integer AVP code, Type identifies an AVP Data Format
+as defined in <seealso marker="#DATA_TYPES">DATA TYPES</seealso> below,
+and Flags is a string of V, M and P characters indicating the flags to be
+set on an outgoing AVP or a single <c>'-'</c> (minus) character if
+none are to be set.</p>
<p>
Example:</p>
@@ -262,8 +271,8 @@ Example:</p>
<code>
@avp_types
-Location-Information 350 Grouped VM
-Requested-Information 353 Enumerated V
+Location-Information 350 Grouped MV
+Requested-Information 353 Enumerated V
</code>
<p>
@@ -276,21 +285,36 @@ to 0 as mandated by the current draft standard.</p>
<tag><c>@custom_types Mod</c></tag>
<item>
<p>
-Defines AVPs for which module Mod provides encode/decode.
-The section contents consists of type names.
-For each AVP Name defined with custom type Type, Mod should export the
-function Name/3 with arguments encode|decode, Type and Data,
-the latter being the term to be encoded/decoded.
-The function returns the encoded/decoded value.</p>
+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
+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>
+
+<p>
+Example:</p>
+
+<code>
+@custom_types rfc4005_avps
+
+Framed-IP-Address
+</code>
+</item>
+<tag><c>@codecs Mod</c></tag>
+<item>
<p>
-Can occur 0 or more times (with different values of Mod).</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>
<p>
Example:</p>
<code>
-@custom_types rfc4005_types
+@codecs rfc4005_avps
Framed-IP-Address
</code>
@@ -360,6 +384,10 @@ SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
[ SIP-Reason-Info ]
* [ AVP ]
</code>
+
+<p>
+Specifying a Vendor-Id in the definition of a grouped AVP is
+equivalent to specifying it with <c>@avp_vendor_id</c>.</p>
</item>
<tag><c>@enum Name</c></tag>
@@ -371,11 +399,9 @@ Integer values can be prefixed with 0x to be interpreted as
hexidecimal.</p>
<p>
-Can occur 0 or more times (with different values of Name).
-The AVP in question can be defined in an inherited dictionary in order
-to introduce additional values.
-An AVP so extended must be referenced by in a <c>@messages</c> or
-<c>@grouped</c> section.</p>
+Note that the AVP in question can be defined in an inherited
+dictionary in order to introduce additional values to an enumeration
+otherwise defined in another dictionary.</p>
<p>
Example:</p>
@@ -390,11 +416,18 @@ REMOVE_SIP_SERVER 3
</code>
</item>
+<tag><c>@end</c></tag>
+<item>
+<p>
+Causes parsing of the dictionary to terminate:
+any remaining content is ignored.</p>
+</item>
+
</taglist>
<p>
Comments can be included in a dictionary file using semicolon:
-text from a semicolon to end of line is ignored.</p>
+characters from a semicolon to end of line are ignored.</p>
<marker id="MESSAGE_RECORDS"/>
</section>
diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml
index 4f8581a904..6b9ef9f756 100644
--- a/lib/diameter/doc/src/diameter_soc.xml
+++ b/lib/diameter/doc/src/diameter_soc.xml
@@ -57,9 +57,13 @@ including the P Flag in the AVP header.</p>
<item>
<p>
-There is no TLS support.
-It's unclear (aka uninvestigated) how TLS would impact
-diameter but IPsec can be used without it needing to know.</p>
+There is no TLS support over SCTP.
+RFC 3588 requires that a Diameter server support TLS but in
+practise this seems to mean TLS over SCTP since there are limitations
+with running over SCTP: see RFC 6083 (DTLS over SCTP), which is a
+response to RFC 3436 (TLS over SCTP).
+The current RFC 3588 draft acknowledges this by equating
+TLS with TLS/TCP and DTLS/SCTP but we do not yet support DTLS.</p>
</item>
<item>
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index a502e53972..e6b53383c0 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -43,7 +43,14 @@ It can be specified as the value of a transport_module option to
<seealso
marker="diameter#add_transport">diameter:add_transport/2</seealso>
and implements the behaviour documented in
-<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>.
+TLS security is supported, both as an upgrade following
+capabilities exchange as specified by RFC 3588 and
+at connection establishment as in the current draft standard.</p>
+
+<p>
+Note that the ssl application is required for TLS and must be started
+before configuring TLS capability on diameter transports.</p>
<marker id="start"/>
</description>
@@ -60,10 +67,15 @@ and implements the behaviour documented in
<v>Type = connect | accept</v>
<v>Ref = reference()</v>
<v>Svc = #diameter_service{}</v>
-<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v>
+<v>Opt = OwnOpt | SslOpt | OtherOpt</v>
<v>Pid = pid()</v>
<v>LAddr = ip_address()</v>
<v>Reason = term()</v>
+<v>OwnOpt = {raddr, ip_address()}
+ | {rport, integer()}
+ | {port, integer()}</v>
+<v>SslOpt = {ssl_options, true | list()}</v>
+<v>OtherOpt = term()</v>
</type>
<desc>
@@ -74,17 +86,42 @@ marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
<p>
The only diameter_tcp-specific argument is the options list.
Options <c>raddr</c> and <c>rport</c> specify the remote address
-and port for a connecting transport and not valid for a listening
+and port for a connecting transport and are not valid for a listening
transport.
-Remaining options are any accepted by gen_tcp:connect/3 for
-a connecting transport, or gen_tcp:listen/2 for a listening transport,
-with the exception of <c>binary</c>, <c>packet</c> and <c>active</c>.
+Option <c>ssl_options</c> must be specified for a transport
+that must be able to support TLS: a value of <c>true</c> results in a
+TLS handshake immediately upon connection establishment while
+list() specifies options to be passed to ssl:connect/2 of ssl:ssl_accept/2
+after capabilities exchange if TLS is negotiated.
+Remaining options are any accepted by ssl:connect/3 or gen_tcp:connect/3 for
+a connecting transport, or ssl:listen/3 or gen_tcp:listen/2 for
+a listening transport, depending on whether or not <c>{ssl_options, true}</c>
+has been specified.
+Options <c>binary</c>, <c>packet</c> and <c>active</c> cannot be specified.
Also, option <c>port</c> can be specified for a listening transport
to specify the local listening port, the default being the standardized
3868 if unspecified.
Note that option <c>ip</c> specifies the local address.</p>
<p>
+An <c>ssl_options</c> list must be specified if and only if
+the transport in question has specified an Inband-Security-Id
+AVP with value TLS on the relevant call to
+<seealso
+marker="diameter#start_service">start_service/2</seealso> or
+<seealso
+marker="diameter#add_transport">add_transport/2</seealso>,
+so that the transport process will receive notification of
+whether or not to commence with a TLS handshake following capabilities
+exchange.
+Failing to specify an options list on a TLS-capable transport
+for which TLS is negotiated will cause TLS handshake to fail.
+Failing to specify TLS capability when <c>ssl_options</c> has been
+specified will cause the transport process to wait for a notification
+that will not be forthcoming, which will eventually cause the RFC 3539
+watchdog to take down the connection.</p>
+
+<p>
If the service specifies more than one Host-IP-Address and
option <c>ip</c> is unspecified then then the
first of the service's addresses is used as the local address.</p>
@@ -104,6 +141,7 @@ The returned local address list has length one.</p>
<title>SEE ALSO</title>
<p>
+<seealso marker="diameter">diameter(3)</seealso>,
<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
</section>
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 37cc871e75..087a90b099 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -143,6 +143,34 @@ connection.
Pid is the pid() of the parent process.</p>
</item>
+<tag><c>{diameter, {tls, Ref, Type, Bool}}</c></tag>
+<item>
+<p>
+Indication of whether or not capabilities exchange has selected
+inband security using TLS.
+Ref is a reference() that must be included in the
+<c>{diameter, {tls, Ref}}</c> reply message to the transport's
+parent process (see below).
+Type is either <c>connect</c> or <c>accept</c> depending on
+whether the process has been started for a connecting or listening
+transport respectively.
+Bool is a boolean() indicating whether or not the transport connection
+should be upgraded to TLS.</p>
+
+<p>
+If TLS is requested (Bool = true) then a connecting process should
+initiate a TLS handshake with the peer and an accepting process should
+prepare to accept a handshake.
+A successful handshake should be followed by a <c>{diameter, {tls, Ref}}</c>
+message to the parent process.
+A failed handshake should cause the process to exit.</p>
+
+<p>
+This message is only sent to a transport process over whose
+<c>Inband-Security-Id</c> configuration has indicated support for
+TLS.</p>
+</item>
+
</taglist>
<p>
@@ -184,6 +212,16 @@ How the <c>transport_data</c> is used/interpreted is up to the
transport module.</p>
</item>
+<tag><c>{diameter, {tls, Ref}}</c></tag>
+<item>
+<p>
+Acknowledgment of a successful TLS handshake.
+Ref is the reference() received in the
+<c>{diameter, {tls, Ref, Type, Bool}}</c> message in response
+to which the reply is sent.
+A transport must exit if a handshake is not successful.</p>
+</item>
+
</taglist>
</section>
diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml
index e2723f3e99..6e364a3200 100644
--- a/lib/diameter/doc/src/notes.xml
+++ b/lib/diameter/doc/src/notes.xml
@@ -36,6 +36,120 @@ first.</p>
<!-- ===================================================================== -->
+<section><title>Diameter 1.0</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Fix faulty cleanup after diameter:remove_transport/2.</p>
+ <p>
+ Removing a transport removed the configuration but did
+ not prevent the transport process from being restarted.</p>
+ <p>
+ Own Id: OTP-9756</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Add support for TLS over TCP.</p>
+ <p>
+ RFC 3588 requires that a Diameter server support TLS. In
+ practice this seems to mean TLS over SCTP since there are
+ limitations with running over SCTP: see RFC 6083 (DTLS
+ over SCTP), which is a response to RFC 3436 (TLS over
+ SCTP). The current RFC 3588 draft acknowledges this by
+ equating TLS with TLS/TCP and DTLS/SCTP.</p>
+ <p>
+ TLS handshaking can take place either following a CER/CEA
+ that negotiates TLS using the Inband-Security-Id AVP (the
+ method documented in RFC 3588) or immediately following
+ connection establishment (the method added to the current
+ draft).</p>
+ <p>
+ Own Id: OTP-9605</p>
+ </item>
+ <item>
+ <p>
+ Improvements to the dictionary parser.</p>
+ <p>
+ The dictionary parser now emits useful error messages in
+ case of faults in the input file, also identifying the
+ line number at which the fault was detected. There are
+ semantic checks that were missing in the previous parser,
+ a fault in the interpretation of vendor id's in
+ combination with @inherits has been fixed and @end can be
+ used to terminate parsing explicitly instead of always
+ parsing to end of file.</p>
+ <p>
+ Own Id: OTP-9639</p>
+ </item>
+ <item>
+ <p>
+ Improve dictionary reusability.</p>
+ <p>
+ Reusing a dictionary just to get a different generated
+ module name or prefix previously required taking a copy
+ of the source, which may consist of several files if
+ inheritance is used, just to edit a couple of lines which
+ don't affect the semantics of the Diameter application
+ being defined. Options --name, --prefix and --inherits
+ have been added to diameterc to allow corresponding
+ values to be set at compile time.</p>
+ <p>
+ Own Id: OTP-9641</p>
+ </item>
+ <item>
+ <p>
+ Add capabilities_cb transport option.</p>
+ <p>
+ Its value is a function that's applied to the transport
+ reference and capabilities record after capabilities
+ exchange. If a callback returns anything but 'ok' then
+ the connection is closed. In the case of an incoming CER,
+ the callback can return a result code with which to
+ answer. Multiple callbacks can be specified and are
+ applied until either all return 'ok' or one doesn't.</p>
+ <p>
+ This provides a way to reject a peer connection.</p>
+ <p>
+ Own Id: OTP-9654</p>
+ </item>
+ <item>
+ <p>
+ Add @codecs to dictionary format.</p>
+ <p>
+ The semantics are similar to @custom_types but results in
+ codec functions of the form TypeName(encode|decode,
+ AvpName, Data) rather than AvpName(encode|decode,
+ TypeName, Data). That is, the role of the AVP name and
+ Diameter type name are reversed. This eliminates the need
+ for exporting one function for each AVP sharing a common
+ specialized encode/decode.</p>
+ <p>
+ Own Id: OTP-9708 Aux Id: OTP-9639 </p>
+ </item>
+ <item>
+ <p>
+ Add #diameter_callback{} for more flexible callback
+ configuration.</p>
+ <p>
+ The record allows individual functions to be configured
+ for each of the diameter_app(3) callbacks, as well as a
+ default callback.</p>
+ <p>
+ Own Id: OTP-9777</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Diameter 0.10</title>
<section><title>Fixed Bugs and Malfunctions</title>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-17 11:44:33 +0000