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