NAME
sctp - Internet Stream Control Transmission Protocol
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/sctp.h>
int
socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP);
int
socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
DESCRIPTION
The SCTP protocol provides reliable, flow-controlled, two-way
transmission of data. It is a message oriented protocol and can support
the SOCK_STREAM and SOCK_SEQPACKET abstractions. SCTP uses the standard
Internet address format and, in addition, provides a per-host collection
of “port addresses”. Thus, each address is composed of an Internet
address specifying the host and network, with a specific SCTP port on the
host identifying the peer entity.
There are two models of programming in SCTP. The first uses the
SOCK_STREAM abstraction. In this abstraction sockets utilizing the SCTP
protocol are either “active” or “passive”. Active sockets initiate
connections to passive sockets. By default, SCTP sockets are created
active; to create a passive socket, the listen(2) system call must be
used after binding the socket with the bind(2) or sctp_bindx(3) system
calls. Only passive sockets may use the accept(2) call to accept
incoming connections. Only active sockets may use the connect(2) call to
initiate connections.
The other abstraction SOCK_SEQPACKET provides a “connectionless” mode of
operation in that the user may send to an address (using any of the valid
send calls that carry a socket address) and an association will be setup
implicitly by the underlying SCTP transport stack. This abstraction is
the only one capable of sending data on the third leg of the four-way
handshake. A user must still call listen(2) to allow the socket to
accept connections. Calling listen(2) however does not restrict the user
from still initiating implicit connections to other peers.
The SCTP protocol directly supports multi-homing. So when binding a
socket with the “wildcard” address INADDR_ANY, the SCTP stack will inform
the peer about all of the local addresses that are deemed in scope of the
peer. The peer will then possibly have multiple paths to reach the local
host.
The SCTP transport protocol is also multi-streamed. Multi-streaming
refers to the ability to send sub-ordered flows of messages. A user
performs this by specifying a specific stream in one of the extended send
calls such as the sctp_send(3) function call. Sending messages on
different streams will allow parallel delivery of data i.e., a message
loss in stream 1 will not block the delivery of messages sent in stream
2.
The SCTP transport protocol also provides a unordered service as well.
The unordered service allows a message to be sent and delivered with no
regard to the ordering of any other message.
Extensions
The FreeBSD implementation of SCTP also supports the following
extensions:
sctp partial reliability This extension allows one to have message be
skipped and not delivered based on some user specified
parameters.
sctp dynamic addressing
This extension allows addresses to be added and deleted
dynammically from an existing association.
sctp authentication This extension allows the user to authenticate
specific peer chunks (including data) to validate that the peer
who sent the message is in fact the peer who setup the
association. A shared key option is also provided for so that
two stacks can pre-share keys.
packet drop
Some routers support a special satellite protocol that will
report losses due to corruption. This allows retransmissions
without subsequent loss in bandwidth utilization.
stream reset This extension allows a user on either side to reset the
stream sequence numbers used by any or all streams.
SCTP supports a number of socket options which can be set with
setsockopt(2) and tested with getsockopt(2) or sctp_opt_info(2):
SCTP_NODELAY Under most circumstances, SCTP sends data
when it is presented; when outstanding data
has not yet been acknowledged, it gathers
small amounts of output to be sent in a
single packet once an acknowledgement is
received. For some clients, such as window
systems that send a stream of mouse events
which receive no replies, this packetization
may cause significant delays. The boolean
option SCTP_NODELAY defeats this algorithm.
SCTP_RTOINFO This option returns specific information
about an associations “Retransmission Time
Out”. It can also be used to change the
default values.
SCTP_ASSOCINFO This option returns specific information
about the requested association.
SCTP_INITMSG This option allows you to get or set the
default sending parameters when an
association is implicitly setup. It allows
you to change such things as the maxium
number of streams allowed inbound and the
number of streams requested of the peer.
SCTP_AUTOCLOSE For the one-to-many model (SOCK_SEQPACKET)
associations are setup implicitly. This
option allows the user to specify a default
number of idle seconds to allow the
association be maintained. After the idle
timer (where no user message have been sent
or have been received from the peer) the
association will be gracefully closed. The
default for this value is 0, or unlimited
(i.e., no automatic close).
SCTP_SET_PEER_PRIMARY_ADDR The dynamic address extension allows a peer
to also request a particular address of its
be made into the primary address. This
option allows the caller to make such a
request to a peer. Note that if the peer
does not also support the dynamic address
extension, this call will fail. Note the
caller must provide a valid local address
that the peer has been told about during
association setup or dynamically.
SCTP_PRIMARY_ADDR This option allows the setting of the primary
address that the caller wishes to send to.
The caller provides the address of a peer
that is to be made primary.
SCTP_ADAPTATION_LAYER The dynamic address extension also allows a
user to pass a 32 bit opaque value upon
association setup. This option allows a user
to set or get this value.
SCTP_DISABLE_FRAGMENTS By default SCTP will fragment user messages
into multiple pieces that will fit on the
network and then later, upon reception,
reassemble the pieces into a single user
message. If this option is enabled instead,
any send that exceeds the path maximum
transfer unit (P-MTU) will fail and the
message will NOT be sent.
SCTP_PEER_ADDR_PARAMS This option will allow a user to set or get
specific peer address parameters.
SCTP_DEFAULT_SEND_PARAM When a user does not use one of the extended
send calls (e.g., sctp_sendmsg(3)) a set of
default values apply to each send. These
values include things like the stream number
to send to as well as the per-protocol id.
This option lets a caller both get and set
these values. If the user changes these
default values, then these new values will be
used as the default whenever no information
is provided by the sender (i.e., the non-
extended API is used).
SCTP_EVENTS SCTP has non-data events that it can
communicate to its application. By default
these are all disabled since they arrive in
the data path with a special flag
MSG_NOTIFICATION set upon the received
message. This option lets a caller both get
what events are current being received as
well as set different events that they may be
interested in receiving.
SCTP_I_WANT_MAPPED_V4_ADDR SCTP supports both IPV4 and IPV6. An
association may span both IPV4 and IPV6
addresses since SCTP is multi-homed. By
default, when opening an IPV6 socket, when
data arrives on the socket from a peer’s V4
address the V4 address will be presented
with an address family of AF_INET. If this
is undesireable, then this option can be
enabled which will then convert all V4
addresses into mapped V6 representations.
SCTP_MAXSEG By default SCTP chooses its message
fragmentation point based upon the smallest
P-MTU of the peer. This option lets the
caller set it to a smaller value. Note that
while the user can change this value, if the
P-MTU is smaller than the value set by the
user, then the P-MTU value will override any
user setting.
SCTP_DELAYED_ACK_TIME This option lets the user both set and get
the delayed ack time (in milliseconds) that
SCTP is using. The default is 200
milliseconds.
SCTP_PARTIAL_DELIVERY_POINT
SCTP at times may need to start delivery of a
very large message before the entire message
has arrived. By default SCTP waits until the
incoming message is larger than one fourth of
the receive buffer. This option allows the
stacks value to be overridden with a smaller
value.
SCTP_FRAGMENT_INTERLEAVE SCTP at times will start partial delivery (as
mentioned above). In the normal case
successive reads will continue to return the
rest of the message, blocking if needed,
until all of that message is read. However
this means other messages may have arrived
and be ready for delivery and be blocked
behind the message being partially delivered.
If this option is enabled, when a partial
delivery message has no more data to be
received, then a subsequent read may return a
different message that is ready for delivery.
By default this option is off since the user
must be using the extended API’s to be able
to tell the difference between messages (via
the stream and stream sequence number).
SCTP_AUTH_CHUNK By default only the dynamic addressing chunks
are authenticated. This option lets a user
request an additional chunk be authenticated
as well. Note that successive calls to this
option will work and continue to add more
chunks that require authentication. Note
that this option only effects future
associations and not existing ones.
SCTP_AUTH_KEY This option allows a user to specify a shared
key that can be later used to authenticate a
peer.
SCTP_HMAC_IDENT This option will let you get or set the list
of HMAC algorithms used to authenticate
peers. Note that the HMAC values are in
priority order where the first HMAC
identifier is the most prefered and the last
is the least prefered.
SCTP_AUTH_ACTIVE_KEY This option allows you to make a key active
for the generation of authentication
information. Note that the peer must have
the same key or else the data will be
discarded.
SCTP_AUTH_DELETE_KEY This option allows you to delete an old key.
SCTP_USE_EXT_RECVINFO The sockets api document allows an extended
send/receive information structure to be
used. The extended structure includes
additional fields related to the next message
to be received (after the current receive
completes) if such information is known. By
default the system will not pass this
information. This option allows the user to
request this information.
SCTP_AUTO_ASCONF By default when bound to all address and the
system administrator has enables automatic
dynamic addresses, the SCTP stack will
automatically generate address changes into
add and delete requests to any peers by
setting this option to true. This option
allows an endpoint to disable that behavior.
SCTP_MAXBURST By default SCTP implements micro-burst
control so that as the congestion window
opens up no large burst of packets can be
generated. The default burst limit is four.
This option lets the user change this value.
SCTP_CONTEXT Many sctp extended calls have a context
field. The context field is a 32 bit opaque
value that will be returned in send failures.
This option lets the caller set the default
context value to use when none is provided by
the user.
SCTP_EXPLICIT_EOR By default, a single send is a complete
message. SCTP generates an implied record
boundary. If this option is enabled, then
all sends are part of the same message until
the user indicates an end of record with the
special flag SCTP_EOR passed in the
sctp_sndrcvinfo flags field. This
effectively makes all sends part of the same
message until the user specifices
differently. This means that a caller must
NOT change the stream number until after the
SCTP_EOR is passed to SCTP else an error will
be returned.
SCTP_STATUS This option is a read only option that
returns various status information about the
specified association.
SCTP_GET_PEER_ADDR_INFO This read only option returns information
about a peer address.
SCTP_PEER_AUTH_CHUNKS This read only option returns a list of the
chunks the peer requires to be authenticated.
SCTP_LOCAL_AUTH_CHUNKS This read only option returns a list of the
locally required chunks that must be
authenticated.
SCTP_RESET_STREAMS This socket option is used to cause a stream
sequence number or all stream sequence
numbers to be reset. Note that the peer SCTP
endpoint must also support the stream reset
extension as well.
SEE ALSO
accept(2), bind(2), connect(2), listen(2), sctp_bindx(3),
sctp_connectx(3), sctp_opt_info(3), sctp_recvmsg(3), sctp_sendmsg(3)