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>. 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