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