<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
  <!ENTITY % also SYSTEM "seealso.ent" >
  <!ENTITY % here SYSTEM "seehere.ent" >
  %also;
  %here;
]>

<erlref>
<header>
<copyright>
<year>2011</year><year>2012</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.

Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.

</legalnotice>

<title>diameter_tcp(3)</title>
<prepared>Anders Svensson</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev></rev>
<file>diameter_tcp.xml</file>
</header>

<module>diameter_tcp</module>
<modulesummary>Diameter transport over TCP.</modulesummary>

<description>

<p>
This module implements diameter transport over TCP using <seealso
marker="kernel:gen_tcp">gen_tcp</seealso>.
It can be specified as the value of a <c>transport_module</c> option to
&mod_add_transport;
and implements the behaviour documented in
&man_transport;.
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>

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

<funcs>

<func>
<name>start({Type, Ref}, Svc, [Opt])
         -> {ok, Pid, [LAddr]} | {error, Reason}</name>
<fsummary>Start a transport process.</fsummary>
<type>
<v>Type = connect | accept</v>
<v>Ref = &mod_transport_ref;</v>
<v>Svc = #diameter_service{}</v>
<v>Opt = OwnOpt | SslOpt | TcpOpt</v>
<v>Pid = pid()</v>
<v>LAddr = <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso></v>
<v>Reason = term()</v>
<v>OwnOpt = {raddr, <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>}
          | {rport, integer()}
          | {port, integer()}</v>
<v>SslOpt = {ssl_options, true | list()}</v>
<v>TcpOpt = term()</v>
</type>
<desc>

<p>
The start function required by &man_transport;.</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 are not valid for a listening
transport.
Option <c>ssl_options</c> must be specified for a transport
that should support TLS: a value of <c>true</c> results in a
TLS handshake immediately upon connection establishment while
<c>list()</c> specifies options to be passed to <seealso
marker="ssl:ssl#connect-2">ssl:connect/2</seealso> or
<seealso marker="ssl:ssl#ssl_accept-2">ssl:ssl_accept/2</seealso>
after capabilities exchange if TLS is negotiated.
Remaining options are any accepted by <seealso
marker="ssl:ssl#connect-3">ssl:connect/3</seealso> or <seealso
marker="kernel:gen_tcp#connect-3">gen_tcp:connect/3</seealso> for
a connecting transport, or <seealso
marker="ssl:ssl#listen-2">ssl:listen/2</seealso> or <seealso
marker="kernel:gen_tcp#listen-2">gen_tcp:listen/2</seealso> 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 the 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 set <c>Inband-Security-Id</c> to
1 (<c>TLS</c>), as
specified to either &mod_start_service; or
&mod_add_transport;,
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 <c>#diameter_service{}</c> record has more than one
<c>Host-IP-Address</c> and option <c>ip</c> is unspecified then the
first of the these addresses is used as the local address.</p>

<p>
The returned local address list has length one.</p>

</desc>
</func>

</funcs>

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

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

<p>
&man_main;,
&man_transport;,
<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>,
<seealso marker="kernel:inet">inet(3)</seealso>,
<seealso marker="ssl:ssl">ssl(3)</seealso></p>

</section>

</erlref>