share/man/man4/sctp.4

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