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