1.\" Copyright (c) 2006, Randall Stewart. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 3. Neither the name of the University nor the names of its contributors 12.\" may be used to endorse or promote products derived from this software 13.\" without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd December 15, 2006 30.Dt SCTP 4 31.Os 32.Sh NAME 33.Nm sctp 34.Nd Internet Stream Control Transmission Protocol 35.Sh SYNOPSIS 36.In sys/types.h 37.In sys/socket.h 38.In netinet/sctp.h 39.Ft int 40.Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP 41.Ft int 42.Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP 43.Sh DESCRIPTION 44The 45.Tn SCTP 46protocol provides reliable, flow-controlled, two-way 47transmission of data. 48It is a message oriented protocol and can 49support the 50.Dv SOCK_STREAM 51and 52.Dv SOCK_SEQPACKET 53abstractions. 54.Tn SCTP 55uses the standard 56Internet address format and, in addition, provides a per-host 57collection of 58.Dq "port addresses" . 59Thus, each address is composed of an Internet address specifying 60the host and network, with a specific 61.Tn SCTP 62port on the host identifying the peer entity. 63.Pp 64There are two models of programming in SCTP. 65The first uses the 66.Dv SOCK_STREAM 67abstraction. 68In this abstraction sockets utilizing the 69.Tn SCTP 70protocol are either 71.Dq active 72or 73.Dq passive . 74Active sockets initiate connections to passive 75sockets. 76By default, 77.Tn SCTP 78sockets are created active; to create a 79passive socket, the 80.Xr listen 2 81system call must be used after binding the socket with the 82.Xr bind 2 83or 84.Xr sctp_bindx 3 85system calls. 86Only passive sockets may use the 87.Xr accept 2 88call to accept incoming connections. 89Only active sockets may use the 90.Xr connect 2 91call to initiate connections. 92.Pp 93The other abstraction 94.Dv SOCK_SEQPACKET 95provides a 96.Dq connectionless 97mode of operation in that the user may send to an address 98(using any of the valid send calls that carry a 99socket address) and an association will be setup 100implicitly by the underlying 101.Tn SCTP 102transport stack. 103This abstraction is the only one capable of sending data on the 104third leg of the four-way handshake. 105A user must still call 106.Xr listen 2 107to allow the socket to accept connections. 108Calling 109.Xr listen 2 110however does not restrict the user from still initiating 111implicit connections to other peers. 112.Pp 113The 114.Tn SCTP 115protocol directly supports multi-homing. 116So when binding a socket with the 117.Dq wildcard 118address 119.Dv INADDR_ANY , 120the 121.Tn SCTP 122stack will inform the peer about all of the local addresses 123that are deemed in scope of the peer. 124The peer will then possibly have multiple paths to reach the local host. 125.Pp 126The 127.Tn SCTP 128transport protocol is also multi-streamed. 129Multi-streaming refers to the ability to send sub-ordered flows of 130messages. 131A user performs this by specifying a specific stream in one of the 132extended send calls such as the 133.Xr sctp_send 3 134function call. 135Sending messages on different streams will allow parallel delivery 136of data i.e., a message loss in stream 1 will not block the delivery 137of messages sent in stream 2. 138.Pp 139The 140.Tn SCTP 141transport protocol also provides a unordered service as well. 142The unordered service allows a message to be sent and delivered 143with no regard to the ordering of any other message. 144.Ss Extensions 145The FreeBSD implementation of 146.Tn SCTP 147also supports the following extensions: 148.Bl -hang -width indent 149.It "sctp partial reliability" 150This extension allows one to have message be skipped and 151not delivered based on some user specified parameters. 152.It "sctp dynamic addressing" 153This extension allows addresses to be added and deleted 154dynamically from an existing association. 155.It "sctp authentication" 156This extension allows the user to authenticate specific 157peer chunks (including data) to validate that the peer 158who sent the message is in fact the peer who setup the 159association. 160A shared key option is also provided for 161so that two stacks can pre-share keys. 162.It "packet drop" 163Some routers support a special satellite protocol that 164will report losses due to corruption. 165This allows retransmissions without subsequent loss in bandwidth 166utilization. 167.It "stream reset" 168This extension allows a user on either side to reset the 169stream sequence numbers used by any or all streams. 170.El 171.Pp 172.Tn SCTP 173supports a number of socket options which can be set with 174.Xr setsockopt 2 175and tested with 176.Xr getsockopt 2 177or 178.Xr sctp_opt_info 3 : 179.Bl -tag -width ".Dv SCTP_SET_PEER_PRIMARY_ADDR" 180.It Dv SCTP_NODELAY 181Under most circumstances, 182.Tn SCTP 183sends data when it is presented; when outstanding data has not 184yet been acknowledged, it gathers small amounts of output to be 185sent in a single packet once an acknowledgement is received. 186For some clients, such as window systems that send a stream of 187mouse events which receive no replies, this packetization may 188cause significant delays. 189The boolean option 190.Dv SCTP_NODELAY 191defeats this algorithm. 192.It Dv SCTP_RTOINFO 193This option returns specific information about an associations 194.Dq "Retransmission Time Out" . 195It can also be used to change the default values. 196.It Dv SCTP_ASSOCINFO 197This option returns specific information about the requested 198association. 199.It Dv SCTP_INITMSG 200This option allows you to get or set the default sending 201parameters when an association is implicitly setup. 202It allows you to change such things as the maximum number of 203streams allowed inbound and the number of streams requested 204of the peer. 205.It Dv SCTP_AUTOCLOSE 206For the one-to-many model 207.Dv ( SOCK_SEQPACKET ) 208associations are setup implicitly. 209This option allows the user to specify a default number of idle 210seconds to allow the association be maintained. 211After the idle timer (where no user message have been sent or have 212been received from the peer) the association will be gracefully 213closed. 214The default for this value is 0, or unlimited (i.e., no automatic 215close). 216.It Dv SCTP_SET_PEER_PRIMARY_ADDR 217The dynamic address extension allows a peer to also request a 218particular address of its be made into the primary address. 219This option allows the caller to make such a request to a peer. 220Note that if the peer does not also support the dynamic address 221extension, this call will fail. 222Note the caller must provide a valid local address that the peer has 223been told about during association setup or dynamically. 224.It Dv SCTP_PRIMARY_ADDR 225This option allows the setting of the primary address 226that the caller wishes to send to. 227The caller provides the address of a peer that is to be made primary. 228.It Dv SCTP_ADAPTATION_LAYER 229The dynamic address extension also allows a user to 230pass a 32 bit opaque value upon association setup. 231This option allows a user to set or get this value. 232.It Dv SCTP_DISABLE_FRAGMENTS 233By default 234.Tn SCTP 235will fragment user messages into multiple pieces that 236will fit on the network and then later, upon reception, reassemble 237the pieces into a single user message. 238If this option is enabled instead, any send that exceeds the path 239maximum transfer unit (P-MTU) will fail and the message will NOT be 240sent. 241.It Dv SCTP_PEER_ADDR_PARAMS 242This option will allow a user to set or get specific 243peer address parameters. 244.It Dv SCTP_DEFAULT_SEND_PARAM 245When a user does not use one of the extended send 246calls (e.g., 247.Xr sctp_sendmsg 3 ) 248a set of default values apply to each send. 249These values include things like the stream number to send 250to as well as the per-protocol id. 251This option lets a caller both get and set these values. 252If the user changes these default values, then these new values will 253be used as the default whenever no information is provided by the 254sender (i.e., the non-extended API is used). 255.It Dv SCTP_EVENTS 256.Tn SCTP 257has non-data events that it can communicate 258to its application. 259By default these are all disabled since they arrive in the data path 260with a special flag 261.Dv MSG_NOTIFICATION 262set upon the received message. 263This option lets a caller 264both get what events are current being received 265as well as set different events that they may be interested 266in receiving. 267.It Dv SCTP_I_WANT_MAPPED_V4_ADDR 268.Tn SCTP 269supports both IPV4 and IPV6. 270An association may span both IPV4 and IPV6 addresses since 271.Tn SCTP 272is multi-homed. 273By default, when opening an IPV6 socket, when 274data arrives on the socket from a peer's 275V4 address the V4 address will be presented with an address family 276of AF_INET. 277If this is undesirable, then this option 278can be enabled which will then convert all V4 addresses 279into mapped V6 representations. 280.It Dv SCTP_MAXSEG 281By default 282.Tn SCTP 283chooses its message fragmentation point 284based upon the smallest P-MTU of the peer. 285This option lets the caller set it to a smaller value. 286Note that while the user can change this value, if the P-MTU 287is smaller than the value set by the user, then the P-MTU 288value will override any user setting. 289.It Dv SCTP_DELAYED_ACK_TIME 290This option lets the user both set and get the 291delayed ack time (in milliseconds) that 292.Tn SCTP 293is using. 294The default is 200 milliseconds. 295.It Dv SCTP_PARTIAL_DELIVERY_POINT 296.Tn SCTP 297at times may need to start delivery of a 298very large message before the entire message has 299arrived. 300By default SCTP waits until the incoming 301message is larger than one fourth of the receive 302buffer. 303This option allows the stacks value 304to be overridden with a smaller value. 305.It Dv SCTP_FRAGMENT_INTERLEAVE 306.Tn SCTP 307at times will start partial delivery (as mentioned above). 308In the normal case successive reads will continue to return 309the rest of the message, blocking if needed, until all of 310that message is read. 311However this means other messages may have arrived and be ready 312for delivery and be blocked behind the message being partially 313delivered. 314If this option is enabled, when a partial delivery 315message has no more data to be received, then a subsequent 316read may return a different message that is ready for delivery. 317By default this option is off since the user must be using the 318extended API's to be able to tell the difference between 319messages (via the stream and stream sequence number). 320.It Dv SCTP_AUTH_CHUNK 321By default only the dynamic addressing chunks are 322authenticated. 323This option lets a user request an 324additional chunk be authenticated as well. 325Note that successive calls to this option will work and continue 326to add more chunks that require authentication. 327Note that this option only effects future associations and 328not existing ones. 329.It Dv SCTP_AUTH_KEY 330This option allows a user to specify a shared 331key that can be later used to authenticate 332a peer. 333.It Dv SCTP_HMAC_IDENT 334This option will let you get or set the list of 335HMAC algorithms used to authenticate peers. 336Note that the HMAC values are in priority order where 337the first HMAC identifier is the most preferred 338and the last is the least preferred. 339.It Dv SCTP_AUTH_ACTIVE_KEY 340This option allows you to make a key active for 341the generation of authentication information. 342Note that the peer must have the same key or else the 343data will be discarded. 344.It Dv SCTP_AUTH_DELETE_KEY 345This option allows you to delete an old key. 346.It Dv SCTP_USE_EXT_RECVINFO 347The sockets api document allows an extended 348send/receive information structure to be used. 349The extended structure includes additional fields 350related to the next message to be received (after the 351current receive completes) if such information is known. 352By default the system will not pass this information. 353This option allows the user to request this information. 354.It Dv SCTP_AUTO_ASCONF 355By default when bound to all address and the system administrator has 356enables automatic dynamic addresses, the 357.Tn SCTP 358stack will automatically generate address changes into add and 359delete requests to any peers by setting this option to 360true. 361This option allows an endpoint to disable that behavior. 362.It Dv SCTP_MAXBURST 363By default 364.Tn SCTP 365implements micro-burst control so that as the congestion window 366opens up no large burst of packets can be generated. 367The default burst limit is four. 368This option lets the user change this value. 369.It Dv SCTP_CONTEXT 370Many sctp extended calls have a context field. 371The context field is a 32 bit opaque value that will be returned in 372send failures. 373This option lets the caller set the default 374context value to use when none is provided by the user. 375.It Dv SCTP_EXPLICIT_EOR 376By default, a single send is a complete message. 377.Tn SCTP 378generates an implied record boundary. 379If this option is enabled, then all sends are part of the same message 380until the user indicates an end of record with the 381special flag 382.Dv SCTP_EOR 383passed in the sctp_sndrcvinfo flags field. 384This effectively makes all sends part of the same message 385until the user specifies differently. 386This means that a caller must NOT change the stream number until 387after the 388.Dv SCTP_EOR 389is passed to 390.Tn SCTP 391else an error will be returned. 392.It Dv SCTP_STATUS 393This option is a read only option that returns 394various status information about the specified association. 395.It Dv SCTP_GET_PEER_ADDR_INFO 396This read only option returns information about a peer 397address. 398.It Dv SCTP_PEER_AUTH_CHUNKS 399This read only option returns a list of the chunks 400the peer requires to be authenticated. 401.It Dv SCTP_LOCAL_AUTH_CHUNKS 402This read only option returns a list of the locally 403required chunks that must be authenticated. 404.It Dv SCTP_RESET_STREAMS 405This socket option is used to cause a stream sequence 406number or all stream sequence numbers to be reset. 407Note that the peer 408.Tn SCTP 409endpoint must also support the stream reset extension 410as well. 411.El 412.Sh SEE ALSO 413.Xr accept 2 , 414.Xr bind 2 , 415.Xr connect 2 , 416.Xr listen 2 , 417.Xr sctp_bindx 3 , 418.Xr sctp_connectx 3 , 419.Xr sctp_opt_info 3 , 420.Xr sctp_recvmsg 3 , 421.Xr sctp_sendmsg 3 422