1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE erlref SYSTEM "erlref.dtd" [
3  <!ENTITY message '<seealso marker="#message">message()</seealso>'>
4  <!ENTITY MESSAGES '<seealso marker="#MESSAGES">MESSAGES</seealso>'>
5  <!ENTITY start '<seealso marker="#Mod:start-3">start/3</seealso>'>
6  <!ENTITY ip_address
7  '<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>'>
8  <!ENTITY % also SYSTEM "seealso.ent" >
9  <!ENTITY % here SYSTEM "seehere.ent" >
10  %also;
11  %here;
12]>
13
14<erlref>
15<header>
16<copyright>
17<year>2011</year>
18<year>2019</year>
19<holder>Ericsson AB. All Rights Reserved.</holder>
20</copyright>
21<legalnotice>
22Licensed under the Apache License, Version 2.0 (the "License");
23you may not use this file except in compliance with the License.
24You may obtain a copy of the License at
25
26    http://www.apache.org/licenses/LICENSE-2.0
27
28Unless required by applicable law or agreed to in writing, software
29distributed under the License is distributed on an "AS IS" BASIS,
30WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
31See the License for the specific language governing permissions and
32limitations under the License.
33
34</legalnotice>
35
36<title>diameter_transport(3)</title>
37<prepared>Anders Svensson</prepared>
38<responsible></responsible>
39<docno></docno>
40<approved></approved>
41<checked></checked>
42<date></date>
43<rev></rev>
44<file>diameter_transport.xml</file>
45</header>
46
47<module since="OTP R14B03">diameter_transport</module>
48<modulesummary>Diameter transport interface.</modulesummary>
49
50<description>
51
52<p>
53A module specified as a <c>transport_module</c> to &mod_add_transport;
54must implement the interface documented here.
55The interface consists of a function with which
56diameter starts a transport process and a message interface with which
57the transport process communicates with the process that starts it (aka its
58parent).</p>
59
60</description>
61
62<!-- ===================================================================== -->
63
64<section>
65<title>DATA TYPES</title>
66
67<taglist>
68
69<tag>
70<marker id="message"/><c>message() = binary() | &codec_packet;</c></tag>
71<item>
72<p>
73A Diameter message as passed over the transport interface.</p>
74
75<p>
76For an inbound message from a transport process, a &codec_packet; must
77contain the received message in its <c>bin</c> field.
78In the case of an inbound request, any value set in the
79<c>transport_data</c> field will passed back to the transport module
80in the corresponding answer message, unless the sender supplies
81another value.</p>
82
83<p>
84For an outbound message to a transport process, a &codec_packet; has a
85value other than <c>undefined</c> in its <c>transport_data</c> field
86and has the binary() to send in its <c>bin</c> field.</p>
87</item>
88
89</taglist>
90
91</section>
92
93<!-- ===================================================================== -->
94
95<funcs>
96
97<func>
98<name since="OTP R14B03">Mod:start({Type, Ref}, Svc, Config)
99         -> {ok, Pid}
100          | {ok, Pid, LAddrs}
101          | {error, Reason}</name>
102<fsummary>Start a transport process.</fsummary>
103<type>
104<v>Type = connect | accept</v>
105<v>Ref = &mod_transport_ref;</v>
106<v>Svc = #diameter_service{}</v>
107<v>Config = term()</v>
108<v>Pid = pid()</v>
109<v>LAddrs = [&ip_address;]</v>
110<v>Reason = term()</v>
111</type>
112<desc>
113<p>
114Start a transport process.
115Called by diameter as a consequence of a call to &mod_add_transport; in
116order to establish or accept a transport connection respectively.
117A transport process maintains a connection with a single remote peer.</p>
118
119<p>
120<c>Type</c> indicates whether the transport process in question
121is being started for a connecting (<c>Type=connect</c>) or listening
122(<c>Type=accept</c>) transport.
123In the latter case, transport processes are started as required to
124accept connections from multiple peers.</p>
125
126<p>
127Ref is the value that was returned from the call to &mod_add_transport;
128that has lead to starting of a transport process.</p>
129
130<p>
131<c>Svc</c> contains capabilities passed to &mod_start_service; and
132&mod_add_transport;, values passed to the latter overriding those
133passed to the former.</p>
134
135<p>
136<c>Config</c> is as passed in <c>transport_config</c> tuple in the
137&mod_transport_opt; list passed to &mod_add_transport;.</p>
138
139<p>
140The start function should use the <c>Host-IP-Address</c> list in
141<c>Svc</c> and/or <c>Config</c> to select and return an appropriate
142list of local IP addresses.
143In the connecting case, the local address list can instead be
144communicated in a <c>connected</c> message (see &MESSAGES; below)
145following connection establishment.
146In either case, the local address list is used to populate
147<c>Host-IP-Address</c> AVPs in outgoing capabilities exchange
148messages if <c>Host-IP-Address</c> is unspecified.</p>
149
150<p>
151A transport process must implement the message interface documented below.
152It should retain the pid of its parent, monitor the parent and terminate if
153it dies.
154It should not link to the parent.
155It should exit if its transport connection with its peer is lost.</p>
156
157</desc>
158</func>
159
160</funcs>
161
162<!-- ===================================================================== -->
163
164<section>
165<marker id="MESSAGES"/>
166<title>MESSAGES</title>
167
168<p>
169All messages sent over the transport interface are of the
170form <c>{diameter, term()}</c>.</p>
171
172<p>
173A transport process can expect messages of the following types from
174its parent.</p>
175
176<taglist>
177
178<tag><c>{diameter, {send, &message; | false}}</c></tag>
179<item>
180<p>
181An outbound Diameter message.
182The atom <c>false</c> can only be received when request
183acknowledgements have been requests: see the <c>ack</c> message
184below.</p>
185</item>
186
187<tag><c>{diameter, {close, Pid}}</c></tag>
188<item>
189<p>
190A request to terminate the transport process after having received DPA
191in response to DPR.
192The transport process should exit.
193<c>Pid</c> is the pid() of the parent process.</p>
194</item>
195
196<tag><c>{diameter, {tls, Ref, Type, Bool}}</c></tag>
197<item>
198<p>
199Indication of whether or not capabilities exchange has selected
200inband security using TLS.
201<c>Ref</c> is a reference() that must be included in the
202<c>{diameter, {tls, Ref}}</c> reply message to the transport's
203parent process (see below).
204<c>Type</c> is either <c>connect</c> or <c>accept</c> depending on
205whether the process has been started for a connecting or listening
206transport respectively.
207<c>Bool</c> is a boolean() indicating whether or not the transport
208connection should be upgraded to TLS.</p>
209
210<p>
211If TLS is requested (<c>Bool=true</c>) then a connecting process should
212initiate a TLS handshake with the peer and an accepting process should
213prepare to accept a handshake.
214A successful handshake should be followed by a <c>{diameter, {tls, Ref}}</c>
215message to the parent process.
216A failed handshake should cause the process to exit.</p>
217
218<p>
219This message is only sent to a transport process over whose
220<c>Inband-Security-Id</c> configuration has indicated support for
221TLS.</p>
222</item>
223
224</taglist>
225
226<p>
227A transport process should send messages of the following types
228to its parent.</p>
229
230<taglist>
231
232<tag><c>{diameter, {self(), connected}}</c></tag>
233<item>
234<p>
235Inform the parent that the transport process with <c>Type=accept</c> has
236established a connection with the peer.
237Not sent if the transport process has <c>Type=connect</c>.</p>
238</item>
239
240<tag><c>{diameter, {self(), connected, Remote}}</c></tag><item/>
241<tag><c>{diameter, {self(), connected, Remote, [LocalAddr]}}</c></tag>
242<item>
243<p>
244Inform the parent that the transport process with <c>Type=connect</c>
245has established a connection with a peer.
246Not sent if the transport process has <c>Type=accept</c>.&nbsp;
247<c>Remote</c> is an arbitrary term that uniquely identifies the remote
248endpoint to which the transport has connected.
249A <c>LocalAddr</c> list has the same semantics as one returned from
250&start;.</p>
251</item>
252
253<tag><c>{diameter, ack}</c></tag>
254<item>
255<p>
256Request acknowledgements of unanswered requests.
257A transport process should send this once before passing incoming
258Diameter messages into diameter.
259As a result, every Diameter request passed into diameter with a
260<c>recv</c> message (below) will be answered with a
261<c>send</c> message (above), either a &message; for the transport
262process to send or the atom <c>false</c> if the request has been
263discarded or otherwise not answered.</p>
264
265<p>
266This is to allow a transport process to keep count of the number
267of incoming request messages that have not yet been answered or
268discarded, to allow it to regulate the amount of incoming traffic.
269Both diameter_tcp and diameter_sctp request acknowledgements when a
270<c>message_cb</c> is configured, turning send/recv message into
271callbacks that can be used to regulate traffic.</p>
272</item>
273
274<tag><c>{diameter, {recv, &message;}}</c></tag>
275<item>
276<p>
277An inbound Diameter message.</p>
278</item>
279
280<tag><c>{diameter, {tls, Ref}}</c></tag>
281<item>
282<p>
283Acknowledgment of a successful TLS handshake.
284<c>Ref</c> is the reference() received in the
285<c>{diameter, {tls, Ref, Type, Bool}}</c> message in response
286to which the reply is sent.
287A transport must exit if a handshake is not successful.</p>
288</item>
289
290</taglist>
291
292</section>
293
294<!-- ===================================================================== -->
295<!-- ===================================================================== -->
296
297<section>
298<title>SEE ALSO</title>
299
300<p>
301&man_tcp;, &man_sctp;</p>
302
303</section>
304
305</erlref>
306