From 30a7d3935e57bd4c6b7e64f8b25eb0a11c0e7c80 Mon Sep 17 00:00:00 2001
From: Anders Svensson
Date: Mon, 3 Oct 2011 15:31:27 +0200
Subject: Documentation updates
---
lib/diameter/doc/src/diameter.xml | 21 ++++++++++++++++
lib/diameter/doc/src/diameter_soc.xml | 10 +++++---
lib/diameter/doc/src/diameter_tcp.xml | 34 +++++++++++++++++++++++---
lib/diameter/doc/src/diameter_transport.xml | 38 +++++++++++++++++++++++++++++
4 files changed, 97 insertions(+), 6 deletions(-)
(limited to 'lib/diameter/doc')
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 2cad70e3bc..43c497f50a 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -367,6 +367,19 @@ capabilities exchange message.
Optional, defaults to the empty list.
+{'Inband-Security-Id', [Unsigned32()]}
+-
+
+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).
+
+
+If 1 (= TLS) is specified then TLS is selected if the CER/CEA received
+from the peer offers it.
+
+
{'Acct-Application-Id', [Unsigned32()]}
-
@@ -683,6 +696,14 @@ in question.
AVP's used to construct outgoing CER/CEA messages.
Any AVP specified takes precedence over a corresponding value specified
for the service in question.
+
+
+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
+diameter_tcp(3) but
+not over SCTP as implemented by
+diameter_sctp(3).
{watchdog_timer, TwInit}
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.
-
-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.
+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.
-
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index a502e53972..916700927f 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -43,7 +43,9 @@ It can be specified as the value of a transport_module option to
diameter:add_transport/2
and implements the behaviour documented in
-diameter_transport(3).
+diameter_transport(3).
+TLS security is supported, a connection being upgraded if
+TLS is negotiated during capabilities exchange.
@@ -60,10 +62,14 @@ and implements the behaviour documented in
Type = connect | accept
Ref = reference()
Svc = #diameter_service{}
-Opt = {raddr, ip_address()} | {rport, integer()} | term()
+Opt = OwnOpt | TlsOpt | TcpOpt
Pid = pid()
LAddr = ip_address()
Reason = term()
+OwnOpt = {raddr, ip_address()}
+ | {rport, integer()}
+TlsOpt = {ssl_options, list()}
+TcpOpt = term()
@@ -74,8 +80,11 @@ marker="diameter_transport#start">diameter_transport(3).
The only diameter_tcp-specific argument is the options list.
Options raddr and rport 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.
+Option ssl_options specifies options to be passed
+to ssl:connect/2 of ssl:ssl_accept/2 in case capabilities exchange
+results in TLS being chosen for inband security.
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 binary, packet and active.
@@ -84,6 +93,24 @@ to specify the local listening port, the default being the standardized
3868 if unspecified.
Note that option ip specifies the local address.
+
+The ssl_options option 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
+start_service/2 or
+add_transport/2,
+so that the transport process will receive notification of
+whether or not to commence with a TLS handshake following capabilities
+exchange.
+Failing to specify ssl_options on a TLS-capable transport
+for which TLS is negotiated will cause TLS handshake to fail.
+Failing to specify TLS capability when ssl_options 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.
+
If the service specifies more than one Host-IP-Address and
option ip is unspecified then then the
@@ -104,6 +131,7 @@ The returned local address list has length one.
SEE ALSO
+diameter(3),
diameter_transport(3)
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.
+{diameter, {tls, Ref, Type, Bool}}
+-
+
+Indication of whether or not capabilities exchange has selected
+inband security using TLS.
+Ref is a reference() that must be included in the
+{diameter, {tls, Ref}} reply message to the transport's
+parent process (see below).
+Type is either connect or accept 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.
+
+
+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 {diameter, {tls, Ref}}
+message to the parent process.
+A failed handshake should cause the process to exit.
+
+
+This message is only sent to a transport process over whose
+Inband-Security-Id configuration has indicated support for
+TLS.
+
+
@@ -184,6 +212,16 @@ How the transport_data is used/interpreted is up to the
transport module.
+{diameter, {tls, Ref}}
+-
+
+Acknowledgment of a successful TLS handshake.
+Ref is the reference() received in the
+{diameter, {tls, Ref, Type, Bool}} message in response
+to which the reply is sent.
+A transport must exit if a handshake is not successful.
+
+
--
cgit v1.2.3