draft-ietf-tsvwg-sctpsocket-12.txt   draft-ietf-tsvwg-sctpsocket-13.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Expires: August 21, 2006 Q. Xie Expires: December 11, 2006 Q. Xie
Motorola, Inc. Motorola, Inc.
L. Yarroll L. Yarroll
TimeSys Corp TimeSys Corp
K. Poon K. Poon
Sun Microsystems, Inc. Sun Microsystems, Inc.
M. Tuexen M. Tuexen
Univ. of Applied Sciences Muenster Univ. of Applied Sciences Muenster
February 17, 2006 June 9, 2006
Sockets API Extensions for Stream Control Transmission Protocol (SCTP) Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
draft-ietf-tsvwg-sctpsocket-12.txt draft-ietf-tsvwg-sctpsocket-13.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 41 skipping to change at page 1, line 41
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 21, 2006. This Internet-Draft will expire on December 11, 2006.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2006). Copyright (C) The Internet Society (2006).
Abstract Abstract
This document describes a mapping of the Stream Control Transmission This document describes a mapping of the Stream Control Transmission
Protocol SCTP RFC2960 [RFC2960] into a sockets API. The benefits of Protocol SCTP RFC2960 [RFC2960] into a sockets API. The benefits of
this mapping include compatibility for TCP applications, access to this mapping include compatibility for TCP applications, access to
skipping to change at page 2, line 41 skipping to change at page 2, line 41
4.1.5. connect() - one-to-one style socket . . . . . . . . . 18 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18
4.1.6. close() - one-to-one style socket . . . . . . . . . . 19 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19
4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19
4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20
4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20
5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21
5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21
5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22
5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23
5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24
5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 27 5.2.3. Extended SCTP Header Information Structure
5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 27 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27
5.4. Ancillary Data Considerations and Semantics . . . . . . . 38 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 31
5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 38 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 31
5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 38 5.4. Ancillary Data Considerations and Semantics . . . . . . . 41
5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 39 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 41
6. Common Operations for Both Styles . . . . . . . . . . . . . . 40 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 42
6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 40 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 42
6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 41 6. Common Operations for Both Styles . . . . . . . . . . . . . . 43
6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 42 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43
6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 42 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44
7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 42 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 45
7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 44 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 45
7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 44 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 46
7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 45 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 48
7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 46 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 48
7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 47 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 48
7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 47 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 50
7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 47 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 50
7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 47 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 50
7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 48 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 51
7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 51
7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 51
7.1.9. Set Peer Primary Address 7.1.9. Set Peer Primary Address
(SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 48 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 51
7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 48 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 52
7.1.11. Set Adaptation Layer Indicator 7.1.11. Set Adaptation Layer Indicator
(SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 49 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 52
7.1.12. Enable/Disable message fragmentation 7.1.12. Enable/Disable message fragmentation
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 49 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 52
7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 49 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 53
7.1.14. Set default send parameters 7.1.14. Set default send parameters
(SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 52 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 55
7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 52 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 56
7.1.16. Set/clear IPv4 mapped addresses 7.1.16. Set/clear IPv4 mapped addresses
(SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 53 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 56
7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) . . . 53 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) . . . 56
7.1.18. Add a chunk that must be authenticated 7.1.18. Add a chunk that must be authenticated
(SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 53 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 56
7.1.19. Set the endpoint pair shared key (SCTP_AUTH_KEY) . . . 54 7.1.19. Get or set the list of supported HMAC Identifiers
7.1.20. Get the list of chunks the peer requires to be (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 57
authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 54 7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 57
7.1.21. Get the list of chunks the local endpoint requires 7.1.21. Get or set the active shared key
to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 55 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 58
7.1.22. Set the list of supported HMAC Identifiers 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 58
(SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 55 7.1.23. Get or set delayed ack timer
7.1.23. Get or set the active key (SCTP_DELAYED_ACK_TIME) . . . . . . . . . . . . . . . 59
(SCTP_AUTH_SETKEY_ACTIVE) . . . . . . . . . . . . . . 55 7.1.24. Get or set fragmented interleave
7.1.24. Get or set delayed ack timer (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 59
(SCTP_DELAYED_ACK_TIME) . . . . . . . . . . . . . . . 56 7.1.25. Set or Get the sctp partial delivery point
7.1.25. Get or set fragmented interleave (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 60
(SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 57 7.1.26. Set or Get the use of extended receive info
7.1.26. Set or Get the sctp partial delivery point (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 60
(SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 57 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 60
7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 58 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 61
7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 58 7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 61
7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 59 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 61
7.3. Ancillary Data and Notification Interest Options . . . . . 60 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 61
8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 62 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 62
8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 62 7.2.3. Get the list of chunks the peer requires to be
8.2. Branched-off Association . . . . . . . . . . . . . . . . . 63 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 63
8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 64 7.2.4. Get the list of chunks the local endpoint requires
8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 64 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 64
8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 65 7.2.5. Get the list of current associations
8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 65 (SCTP_GET_ASOC_ID_LIST) . . . . . . . . . . . . . . . 64
8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 66 7.3. Ancillary Data and Notification Interest Options . . . . . 65
8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 66 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 67
8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 67 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 67
8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 67 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 69
8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 68 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 69
8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 69 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 70
9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 69 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 70
10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 70 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 71
11. Security Considerations . . . . . . . . . . . . . . . . . . . 70 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 71
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 70 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 71
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 71 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 72
13.1. Normative references . . . . . . . . . . . . . . . . . . . 71 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 73
13.2. Informational References . . . . . . . . . . . . . . . . . 71 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 73
Appendix A. one-to-one style Code Example . . . . . . . . . . . . 71 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 74
Appendix B. one-to-many style Code Example . . . . . . . . . . . 76 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 75
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 79 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 75
Intellectual Property and Copyright Statements . . . . . . . . . . 81 11. Security Considerations . . . . . . . . . . . . . . . . . . . 75
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 76
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 76
13.1. Normative references . . . . . . . . . . . . . . . . . . . 76
13.2. Informational References . . . . . . . . . . . . . . . . . 77
Appendix A. one-to-one style Code Example . . . . . . . . . . . . 77
Appendix B. one-to-many style Code Example . . . . . . . . . . . 82
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 84
Intellectual Property and Copyright Statements . . . . . . . . . . 86
1. Introduction 1. Introduction
The sockets API has provided a standard mapping of the Internet The sockets API has provided a standard mapping of the Internet
Protocol suite to many operating systems. Both TCP RFC793 [RFC0793] Protocol suite to many operating systems. Both TCP RFC793 [RFC0793]
and UDP RFC768 [RFC0768] have benefited from this standard and UDP RFC768 [RFC0768] have benefited from this standard
representation and access method across many diverse platforms. SCTP representation and access method across many diverse platforms. SCTP
is a new protocol that provides many of the characteristics of TCP is a new protocol that provides many of the characteristics of TCP
but also incorporates semantics more akin to UDP. This document but also incorporates semantics more akin to UDP. This document
defines a method to map the existing sockets API for use with SCTP, defines a method to map the existing sockets API for use with SCTP,
skipping to change at page 7, line 14 skipping to change at page 7, line 14
1. socket() 1. socket()
2. sendmsg() 2. sendmsg()
3. recvmsg() 3. recvmsg()
4. close() 4. close()
In this style, by default, all the associations connected to the In this style, by default, all the associations connected to the
endpoint are represented with a single socket. Each associations is endpoint are represented with a single socket. Each associations is
assigned an association ID (type is sctp_assoc_t) so that an assigned an association ID (type is sctp_assoc_t) so that an
application can use it to differentiate between them. In some application can use it to differentiate between them. In some
implementations, the peer end point's addresses can also be used for implementations, the peer endpoints addresses can also be used for
this purpose. But this is not required for performance reasons. If this purpose. But this is not required for performance reasons. If
an implementation does not support using addresses to differentiate an implementation does not support using addresses to differentiate
between different associations, the sendto() call can only be used to between different associations, the sendto() call can only be used to
setup an association implicitly. It cannot be used to send data to setup an association implicitly. It cannot be used to send data to
an established association as the association ID cannot be specified. an established association as the association ID cannot be specified.
Once as association ID is assigned to an SCTP association, that ID Once as association ID is assigned to an SCTP association, that ID
will not be reused until the application explicitly terminates the will not be reused until the application explicitly terminates the
association. The resources belonged to that association will not be association. The resources belonged to that association will not be
freed until that happens. This is similar to the close() operation freed until that happens. This is similar to the close() operation
skipping to change at page 13, line 44 skipping to change at page 13, line 44
that one of the associations represented by the one-to-many socket is that one of the associations represented by the one-to-many socket is
writable. An application that writes after the select return may writable. An application that writes after the select return may
still block since the association that was writeable is not the still block since the association that was writeable is not the
destination association of the write call. Likewise select (or destination association of the write call. Likewise select (or
poll()) for reading from a one-to-many socket will only return an poll()) for reading from a one-to-many socket will only return an
indication that one of the associations represented by the socket has indication that one of the associations represented by the socket has
data to be read. data to be read.
An application that wishes to know that a particular association is An application that wishes to know that a particular association is
ready for reading or writing should either use the one-to-one style ready for reading or writing should either use the one-to-one style
or use the sctp_peelloff() (see Section 8.2) function to seperate the or use the sctp_peeloff() (see Section 8.2) function to separate the
association of interest from the one-to-many socket. association of interest from the one-to-many socket.
3.4. Special considerations 3.4. Special considerations
The fact that a one-to-many style socket can provide access to many The fact that a one-to-many style socket can provide access to many
SCTP associations through a single socket descriptor has important SCTP associations through a single socket descriptor has important
implications for both application programmers and system programmers implications for both application programmers and system programmers
implementing this API. A key issue is how buffer space inside the implementing this API. A key issue is how buffer space inside the
sockets layer is managed. Because this implementation detail sockets layer is managed. Because this implementation detail
directly affects how application programmers must write their code to directly affects how application programmers must write their code to
skipping to change at page 15, line 15 skipping to change at page 15, line 15
(a) demand that the underlying implementation dedicates independent (a) demand that the underlying implementation dedicates independent
buffer space allotments to each association (as suggested above), buffer space allotments to each association (as suggested above),
or or
(b) verify that their application layer protocol does not permit (b) verify that their application layer protocol does not permit
large amounts of unread data at the receiver (this is true of some large amounts of unread data at the receiver (this is true of some
request-response protocols, for example), or request-response protocols, for example), or
(c) use one-to-one style sockets for association which may (c) use one-to-one style sockets for association which may
potentially stall (either from the beginning, or by using potentially stall (either from the beginning, or by using
sctp_peeloff before sending large amounts of data that may cause a sctp_peeloff before sending large amounts of data that may cause a
stalled condition). stalled condition).
An implemenation which dedicates independent buffer space for each An implementation which dedicates independent buffer space for
association should define HAVE_SCTP_MULTIBUF to 1. each association should define HAVE_SCTP_MULTIBUF to 1.
4. one-to-one style Interface 4. one-to-one style Interface
The goal of this style is to follow as closely as possible the The goal of this style is to follow as closely as possible the
current practice of using the sockets interface for a connection current practice of using the sockets interface for a connection
oriented protocol, such as TCP. This style enables existing oriented protocol, such as TCP. This style enables existing
applications using connection oriented protocols to be ported to SCTP applications using connection oriented protocols to be ported to SCTP
with very little effort. with very little effort.
Note that some new SCTP features and some new SCTP socket options can Note that some new SCTP features and some new SCTP socket options can
skipping to change at page 19, line 15 skipping to change at page 19, line 15
capability of SCTP. capability of SCTP.
Note that SCTP allows data exchange, similar to T/TCP RFC1644 Note that SCTP allows data exchange, similar to T/TCP RFC1644
[RFC1644], during the association set up phase. If an application [RFC1644], during the association set up phase. If an application
wants to do this, it cannot use connect() call. Instead, it should wants to do this, it cannot use connect() call. Instead, it should
use sendto() or sendmsg() to initiate an association. If it uses use sendto() or sendmsg() to initiate an association. If it uses
sendto() and it wants to change initialization behavior, it needs to sendto() and it wants to change initialization behavior, it needs to
use the SCTP_INITMSG socket option before calling sendto(). Or it use the SCTP_INITMSG socket option before calling sendto(). Or it
can use SCTP_INIT type sendmsg() to initiate an association without can use SCTP_INIT type sendmsg() to initiate an association without
doing the setsockopt(). Note that some sockets implementations may doing the setsockopt(). Note that some sockets implementations may
not support the sending of data to initiate an assocation with the not support the sending of data to initiate an association with the
one-to-one style (implementations that do not support T/TCP normally one-to-one style (implementations that do not support T/TCP normally
have this restriction). Implementations which allow sending of data have this restriction). Implementations which allow sending of data
to initiate an association without calling connect() define the to initiate an association without calling connect() define the
preprocessor constant HAVE_SCTP_NOCONNECT to 1. preprocessor constant HAVE_SCTP_NOCONNECT to 1.
SCTP does not support half close semantics. This means that unlike SCTP does not support half close semantics. This means that unlike
T/TCP, MSG_EOF should not be set in the flags parameter when calling T/TCP, MSG_EOF should not be set in the flags parameter when calling
sendto() or sendmsg() when the call is used to initiate a connection. sendto() or sendmsg() when the call is used to initiate a connection.
MSG_EOF is not an acceptable flag with SCTP socket. MSG_EOF is not an acceptable flag with SCTP socket.
skipping to change at page 24, line 9 skipping to change at page 24, line 9
in the SCTP_COMM_UP notification and must be verified since it is a in the SCTP_COMM_UP notification and must be verified since it is a
negotiated number with the remote endpoint. The default value of 0 negotiated number with the remote endpoint. The default value of 0
indicates to use the endpoint default value. indicates to use the endpoint default value.
sinit_max_instreams: 16 bits (unsigned integer) sinit_max_instreams: 16 bits (unsigned integer)
This value represents the maximum number of inbound streams the This value represents the maximum number of inbound streams the
application is prepared to support. This value is bounded by the application is prepared to support. This value is bounded by the
actual implementation. In other words the user MAY be able to actual implementation. In other words the user MAY be able to
support more streams than the Operating System. In such a case, the support more streams than the Operating System. In such a case, the
Operating System limit overrides the value requested by the user. Operating System limit overrides the value requested by the user.
The default value of 0 indicates to use the endpoint's default value. The default value of 0 indicates to use the endpoints default value.
sinit_max_attempts: 16 bits (unsigned integer) sinit_max_attempts: 16 bits (unsigned integer)
This integer specifies how many attempts the SCTP endpoint should This integer specifies how many attempts the SCTP endpoint should
make at resending the INIT. This value overrides the system SCTP make at resending the INIT. This value overrides the system SCTP
'Max.Init.Retransmits' value. The default value of 0 indicates to 'Max.Init.Retransmits' value. The default value of 0 indicates to
use the endpoint's default value. This is normally set to the use the endpoints default value. This is normally set to the
system's default 'Max.Init.Retransmit' value. system's default 'Max.Init.Retransmit' value.
sinit_max_init_timeo: 16 bits (unsigned integer) sinit_max_init_timeo: 16 bits (unsigned integer)
This value represents the largest Time-Out or RTO value (in This value represents the largest Time-Out or RTO value (in
milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is milliseconds) to use in attempting an INIT. Normally the 'RTO.Max'
used to limit the doubling of the RTO upon timeout. For the INIT is used to limit the doubling of the RTO upon timeout. For the INIT
message this value MAY override 'RTO.Max'. This value MUST NOT message this value MAY override 'RTO.Max'. This value MUST NOT
influence 'RTO.Max' during data transmission and is only used to influence 'RTO.Max' during data transmission and is only used to
bound the initial setup time. A default value of 0 indicates to use bound the initial setup time. A default value of 0 indicates to use
the endpoint's default value. This is normally set to the system's the endpoints default value. This is normally set to the system's
'RTO.Max' value (60 seconds). 'RTO.Max' value (60 seconds).
5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV)
This cmsghdr structure specifies SCTP options for sendmsg() and This cmsghdr structure specifies SCTP options for sendmsg() and
describes SCTP header information about a received message through describes SCTP header information about a received message through
recvmsg(). recvmsg().
cmsg_level cmsg_type cmsg_data[] cmsg_level cmsg_type cmsg_data[]
------------ ------------ ---------------------- ------------ ------------ ----------------------
skipping to change at page 26, line 12 skipping to change at page 26, line 12
recvmsg() flags: recvmsg() flags:
SCTP_UNORDERED - This flag is present when the message was sent non- SCTP_UNORDERED - This flag is present when the message was sent non-
ordered. ordered.
sendmsg() flags: sendmsg() flags:
SCTP_UNORDERED - This flag requests the un-ordered delivery of the SCTP_UNORDERED - This flag requests the un-ordered delivery of the
message. If this flag is clear the datagram is considered an message. If this flag is clear the datagram is considered an
ordered send. ordered send.
SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the
SCTP stack to override the primary destination address with the
address found with the sendto/sendmsg call.
SCTP_ABORT - Setting this flag causes the specified association to
abort by sending an ABORT message to the peer (one-to-many style
only). The ABORT chunk will contain an error cause 'User
Initiated Abort' with cause code 12. The cause specific
information of this error cause is provided in msg_iov.
SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown
procedures on the specified association. Graceful shutdown
assures that all data enqueued by both endpoints is successfully
transmitted before closing the association (one-to-many style
only).
SCTP_SENDALL - This flag, if set, will cause a one-to-many model
socket to send the message to all associations that are currently
established on this socket. For the one-to-one socket, this flag
has no effect.
sinfo_timetolive: 32 bit (unsigned integer)
For the sending side, this field contains the message time to live in
milliseconds. The sending side will expire the message within the
specified time period if the message as not been sent to the peer
within this time period. This value will override any default value
set using any socket option. Also note that the value of 0 is
special in that it indicates no timeout should occur on this message.
sinfo_tsn: 32 bit (unsigned integer)
For the receiving side, this field holds a TSN that was assigned to
one of the SCTP Data Chunks.
sinfo_cumtsn: 32 bit (unsigned integer)
This field will hold the current cumulative TSN as known by the
underlying SCTP layer. Note this field is ignored when sending and
only valid for a receive operation when sinfo_flags are set to
SCTP_UNORDERED.
sinfo_assoc_id: sizeof (sctp_assoc_t)
The association handle field, sinfo_assoc_id, holds the identifier
for the association announced in the SCTP_COMM_UP notification. All
notifications for a given association have the same identifier.
Ignored for one-to-one style sockets.
A sctp_sndrcvinfo item always corresponds to the data in msg_iov.
5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV)
This cmsghdr structure specifies SCTP options for SCTP header
information about a received message via recvmsg(). Note that this
structure is an extended version of SCTP_SNDRCV and will only be
received if the user has set the socket option SCTP_USE_EXT_RCVINFO
to true in addition to any event subscription needed to receive
ancillary data..
cmsg_level cmsg_type cmsg_data[]
------------ ------------ ----------------------
IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo
Here is the definition of sctp_sndrcvinfo:
struct sctp_extrcvinfo {
uint16_t sinfo_stream;
uint16_t sinfo_ssn;
uint16_t sinfo_flags;
uint32_t sinfo_ppid;
uint32_t sinfo_context;
uint32_t sinfo_timetolive;
uint32_t sinfo_tsn;
uint32_t sinfo_cumtsn;
sctp_assoc_t sinfo_assoc_id;
uint16_t next_flags;
uint16_t next_stream;
uint32_t next_asocid;
uint32_t next_length;
uint32_t next_ppid;
};
sinfo_stream: 16 bits (unsigned integer)
For recvmsg() the SCTP stack places the message's stream number in
this value. For sendmsg() this value holds the stream number that
the application wishes to send this message to. If a sender
specifies an invalid stream number an error indication is returned
and the call fails.
sinfo_ssn: 16 bits (unsigned integer)
For recvmsg() this value contains the stream sequence number that the
remote endpoint placed in the DATA chunk. For fragmented messages
this is the same number for all deliveries of the message (if more
than one recvmsg() is needed to read the message). The sendmsg()
call will ignore this parameter.
sinfo_ppid: 32 bits (unsigned integer)
This value in sendmsg() is an unsigned integer that is passed to the
remote end in each user message. In recvmsg() this value is the same
information that was passed by the upper layer in the peer
application. Please note that the SCTP stack performs no byte order
modification of this field. For example, if the DATA chunk has to
contain a given value in network byte order, the SCTP user has to
perform the htonl() computation.
sinfo_context: 32 bits (unsigned integer)
This value is an opaque 32 bit context datum that is used in the
sendmsg() function. This value is passed back to the upper layer if
a error occurs on the send of a message and is retrieved with each
undelivered message (Note: if a endpoint has done multiple sends, all
of which fail, multiple different sinfo_context values will be
returned. One with each user data message).
sinfo_flags: 16 bits (unsigned integer)
This field may contain any of the following flags and is composed of
a bitwise OR of these values.
recvmsg() flags:
SCTP_UNORDERED - This flag is present when the message was sent non-
ordered.
sendmsg() flags:
SCTP_UNORDERED - This flag requests the un-ordered delivery of the
message. If this flag is clear the datagram is considered an
ordered send.
SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the
SCTP stack to override the primary destination address with the SCTP stack to override the primary destination address with the
address found with the sendto/sendmsg call. address found with the sendto/sendmsg call.
SCTP_ABORT - Setting this flag causes the specified association to SCTP_ABORT - Setting this flag causes the specified association to
abort by sending an ABORT message to the peer (one-to-many style abort by sending an ABORT message to the peer (one-to-many style
only). The ABORT chunk will contain an error cause 'User only). The ABORT chunk will contain an error cause 'User
Initiated Abort' with cause code 12. The cause specific Initiated Abort' with cause code 12. The cause specific
information of this error cause is provided in msg_iov. information of this error cause is provided in msg_iov.
SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown
procedures on the specified association. Graceful shutdown procedures on the specified association. Graceful shutdown
assures that all data enqueued by both endpoints is successfully assures that all data enqueued by both endpoints is successfully
transmitted before closing the association (one-to-many style transmitted before closing the association (one-to-many style
only). only).
SCTP_SENDALL - This flag, if set, will cause a one-to-many model SCTP_SENDALL - This flag, if set, will cause a one-to-many model
socket to send the message to all associations that are currently socket to send the message to all associations that are currently
established on this socket. For the one-to-one socket, this flag established on this socket. For the one-to-one socket, this flag
has no effect. has no effect.
sinfo_timetolive: 32 bit (unsigned integer) sinfo_timetolive: 32 bit (unsigned integer)
For the sending side, this field contains the message time to live in For the sending side, this field contains the message time to live in
milliseconds. The sending side will expire the message within the milliseconds. The sending side will expire the message within the
specified time period if the message as not been sent to the peer specified time period if the message as not been sent to the peer
skipping to change at page 27, line 4 skipping to change at page 29, line 48
one of the SCTP Data Chunks. one of the SCTP Data Chunks.
sinfo_cumtsn: 32 bit (unsigned integer) sinfo_cumtsn: 32 bit (unsigned integer)
This field will hold the current cumulative TSN as known by the This field will hold the current cumulative TSN as known by the
underlying SCTP layer. Note this field is ignored when sending and underlying SCTP layer. Note this field is ignored when sending and
only valid for a receive operation when sinfo_flags are set to only valid for a receive operation when sinfo_flags are set to
SCTP_UNORDERED. SCTP_UNORDERED.
sinfo_assoc_id: sizeof (sctp_assoc_t) sinfo_assoc_id: sizeof (sctp_assoc_t)
The association handle field, sinfo_assoc_id, holds the identifier The association handle field, sinfo_assoc_id, holds the identifier
for the association announced in the SCTP_COMM_UP notification. All for the association announced in the SCTP_COMM_UP notification. All
notifications for a given association have the same identifier. notifications for a given association have the same identifier.
Ignored for one-to-one style sockets. Ignored for one-to-one style sockets.
A sctp_sndrcvinfo item always corresponds to the data in msg_iov. A sctp_sndrcvinfo item always corresponds to the data in msg_iov.
next_flags: 16 bit (unsigned integer)
This bitmask will hold one or more of the following values:
SCTP_NEXT_MSG_AVAIL - This bit, when set to 1, indicates that next
message information is available i.e.: next_stream, next_asocid,
next_length and next_ppid fields all have valid values. If this
bit is set to 0, then these fields are not valid and should be
ignored.
SCTP_NEXT_MSG_ISCOMPLETE - This bit, when set, indicates that the
next message is completely in the receive buffer. The next_length
field thus contains the entire message size. If this flag is set
to 0, then the next_length field only contains part of the message
size since the message is still being received (it is being
partially delivered).
SCTP_NEXT_MSG_IS_UNORDERED - This bit, when set, indicates that the
next message to be received was sent by the peer as unordered. If
this bit is not set (i.e the bit is 0) the next message to be read
is an ordered message in the stream specified.
next_stream: 16 bit (unsigned integer)
This value, when valid (see next_flags), contains the next stream
number that will be received on a subsequent call to one of the
receive message functions.
next_asocid: 32 bit (unsigned integer)
This value, when valid (see next_flags), contains the next
association identification that will be received on a subsequent call
to one of the receive message functions.
next_length: 32 bit (unsigned integer)
This value, when valid (see next_flags), contains the length of the
next message that will be received on a subsequent call to one of the
receive message functions. Note that this length may be a partial
length depending on the settings of next_flags.
next_ppid: 32 bit (unsigned integer)
This value, when valid (see next_flags), contains the ppid of the
next message that will be received on a subsequent call to one of the
receive message functions.
5.3. SCTP Events and Notifications 5.3. SCTP Events and Notifications
An SCTP application may need to understand and process events and An SCTP application may need to understand and process events and
errors that happen on the SCTP stack. These events include network errors that happen on the SCTP stack. These events include network
status changes, association startups, remote operational errors and status changes, association startups, remote operational errors and
undeliverable messages. All of these can be essential for the undeliverable messages. All of these can be essential for the
application. application.
When an SCTP application layer does a recvmsg() the message read is When an SCTP application layer does a recvmsg() the message read is
normally a data message from a peer endpoint. If the application normally a data message from a peer endpoint. If the application
skipping to change at page 28, line 16 skipping to change at page 31, line 48
struct { struct {
uint16_t sn_type; /* Notification type. */ uint16_t sn_type; /* Notification type. */
uint16_t sn_flags; uint16_t sn_flags;
uint32_t sn_length; uint32_t sn_length;
} sn_header; } sn_header;
struct sctp_assoc_change sn_assoc_change; struct sctp_assoc_change sn_assoc_change;
struct sctp_paddr_change sn_paddr_change; struct sctp_paddr_change sn_paddr_change;
struct sctp_remote_error sn_remote_error; struct sctp_remote_error sn_remote_error;
struct sctp_send_failed sn_send_failed; struct sctp_send_failed sn_send_failed;
struct sctp_shutdown_event sn_shutdown_event; struct sctp_shutdown_event sn_shutdown_event;
struct sctp_adaption_event sn_adaptation_event; struct sctp_adaptation_event sn_adaptation_event;
struct sctp_pdapi_event sn_pdapi_event; struct sctp_pdapi_event sn_pdapi_event;
struct sctp_authkey_event sn_auth_event; struct sctp_authkey_event sn_auth_event;
}; };
sn_type: 16 bits (unsigned integer) sn_type: 16 bits (unsigned integer)
The following list describes the SCTP notification and event types The following list describes the SCTP notification and event types
for the field sn_type. for the field sn_type.
SCTP_ASSOC_CHANGE: This tag indicates that an association has either SCTP_ASSOC_CHANGE: This tag indicates that an association has either
been opened or closed. Refer to Section 5.3.1.1 for details. been opened or closed. Refer to Section 5.3.1.1 for details.
SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is
part of an existing association has experienced a change of state part of an existing association has experienced a change of state
(e.g. a failure or return to service of the reachability of a (e.g. a failure or return to service of the reachability of a
skipping to change at page 29, line 5 skipping to change at page 32, line 33
structure uses the sctp_sndrecvinfo per Section 5.3.1.4. structure uses the sctp_sndrecvinfo per Section 5.3.1.4.
SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data
should be sent on this socket. should be sent on this socket.
SCTP_ADAPTATION_INDICATION: This notification holds the peers SCTP_ADAPTATION_INDICATION: This notification holds the peers
indicated adaptation layer. Please see Section 5.3.1.6. indicated adaptation layer. Please see Section 5.3.1.6.
SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a
receiver that the partial delivery has been aborted. This may receiver that the partial delivery has been aborted. This may
indicate the association is about to be aborted. Please see indicate the association is about to be aborted. Please see
Section 5.3.1.7 Section 5.3.1.7
SCTP_AUTHENTICATION_EVENT: This notification is used to tell a SCTP_AUTHENTICATION_EVENT: This notification is used to tell a
receiver that either an error occured on authentication, or a new receiver that either an error occurred on authentication, or a new
key was made active. Section 5.3.1.8 key was made active. Section 5.3.1.8
All standard values for sn_type are greater than 2^15. Values from All standard values for sn_type are greater than 2^15. Values from
2^15 and down are reserved. 2^15 and down are reserved.
sn_flags: 16 bits (unsigned integer) sn_flags: 16 bits (unsigned integer)
These are notification-specific flags. These are notification-specific flags.
sn_length: 32 bits (unsigned integer) sn_length: 32 bits (unsigned integer)
skipping to change at page 32, line 4 skipping to change at page 35, line 31
spc_state: 32 bits (signed integer) spc_state: 32 bits (signed integer)
This field holds one of a number of values that communicate the event This field holds one of a number of values that communicate the event
that happened to the address. They include: that happened to the address. They include:
Event Name Description Event Name Description
---------------- --------------- ---------------- ---------------
SCTP_ADDR_AVAILABLE - This address is now reachable. SCTP_ADDR_AVAILABLE - This address is now reachable.
SCTP_ADDR_UNREACHABLE - The address specified can no longer be SCTP_ADDR_UNREACHABLE - The address specified can no longer be
reached. Any data sent to this address is rerouted to an reached. Any data sent to this address is rerouted to an
alternate until this address becomes reachable. alternate until this address becomes reachable.
SCTP_ADDR_REMOVED - The address is no longer part of the association. SCTP_ADDR_REMOVED - The address is no longer part of the association.
SCTP_ADDR_ADDED - The address is now part of the association. SCTP_ADDR_ADDED - The address is now part of the association.
SCTP_ADDR_MADE_PRIM - This address has now been made to be the SCTP_ADDR_MADE_PRIM - This address has now been made to be the
primary destination address. primary destination address.
SCTP_ADDR_CONFIRMED - This address has now been confirmed as a valid
address.
spc_error: 32 bits (signed integer) spc_error: 32 bits (signed integer)
If the state was reached due to any error condition (e.g. If the state was reached due to any error condition (e.g.
SCTP_ADDR_UNREACHABLE) any relevant error information is available in SCTP_ADDR_UNREACHABLE) any relevant error information is available in
this field. this field.
spc_assoc_id: sizeof (sctp_assoc_t) spc_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
skipping to change at page 38, line 4 skipping to change at page 41, line 27
auth_altkeynumber: 32 bits (unsigned integer) auth_altkeynumber: 32 bits (unsigned integer)
This field holds an alternate keynumber which is used by some This field holds an alternate keynumber which is used by some
notifications. notifications.
auth_indication: 32 bits (unsigned integer) auth_indication: 32 bits (unsigned integer)
This field hold the error or indication being reported. The This field hold the error or indication being reported. The
following values are currently defined: following values are currently defined:
SCTP_AUTH_NEWKEY - this report indicates that a new key has been made SCTP_AUTH_NEWKEY - this report indicates that a new key has been made
active (used for the first time by the peer) and is now the active active (used for the first time by the peer) and is now the active
key. The auth_keynumber field holds the user specified key key. The auth_keynumber field holds the user specified key
number. number.
SCTP_KEY_CONFLICT - this report indicates that an association was
attempting to be formed and that two seperate keys were discovered
for the same peer endpoint. In other words, two distinct keys
would have been active for the same association due to multi-
homing. The field auth_keynumber contains one of the conflicting
keys and the field auth_altkeynumber contains one of the other
keys. Note that more than two key COULD be in conflict.
auth_assoc_id: sizeof (sctp_assoc_t) auth_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. identifier.
5.4. Ancillary Data Considerations and Semantics 5.4. Ancillary Data Considerations and Semantics
Programming with ancillary socket data contains some subtleties and Programming with ancillary socket data contains some subtleties and
skipping to change at page 42, line 4 skipping to change at page 45, line 15
The syntax is: The syntax is:
ret = getsockopt(int sd, int level, int optname, void *optval, ret = getsockopt(int sd, int level, int optname, void *optval,
socklen_t *optlen); socklen_t *optlen);
ret = setsockopt(int sd, int level, int optname, const void *optval, ret = setsockopt(int sd, int level, int optname, const void *optval,
socklen_t optlen); socklen_t optlen);
sd - the socket descriptor. sd - the socket descriptor.
level - set to IPPROTO_SCTP for all SCTP options. level - set to IPPROTO_SCTP for all SCTP options.
optname - the option name. optname - the option name.
optval - the buffer to store the value of the option. optval - the buffer to store the value of the option.
optlen - the size of the buffer (or the length of the option optlen - the size of the buffer (or the length of the option
returned). returned).
All socket options set on a 1-to-1 listening sockets also apply all
accepted sockets. All socket options set on a 1-to-many socket using
the assoc_id 0 applies for all future assocs on the socket.
6.3. read() and write() 6.3. read() and write()
Applications can use read() and write() to send and receive data to Applications can use read() and write() to send and receive data to
and from peer. They have the same semantics as send() and recv() and from peer. They have the same semantics as send() and recv()
except that the flags parameter cannot be used. except that the flags parameter cannot be used.
Note, these calls, when used in the one-to-many style, may only be Note, these calls, when used in the one-to-many style, may only be
used with branched off socket descriptors (see Section 8.2). used with branched off socket descriptors (see Section 8.2).
6.4. getsockname() 6.4. getsockname()
skipping to change at page 43, line 47 skipping to change at page 47, line 19
opt specifies which SCTP socket option to get. It can get any socket opt specifies which SCTP socket option to get. It can get any socket
option currently supported that requests information (either read/ option currently supported that requests information (either read/
write options or read only) such as: write options or read only) such as:
SCTP_RTOINFO SCTP_RTOINFO
SCTP_ASSOCINFO SCTP_ASSOCINFO
SCTP_DEFAULT_SEND_PARAM SCTP_DEFAULT_SEND_PARAM
SCTP_GET_PEER_ADDR_INFO SCTP_GET_PEER_ADDR_INFO
SCTP_PRIMARY_ADDR SCTP_PRIMARY_ADDR
SCTP_PEER_ADDR_PARAMS SCTP_PEER_ADDR_PARAMS
SCTP_STATUS SCTP_STATUS
SCTP_AUTH_CHUNKS SCTP_AUTH_ACTIVE_KEY
SCTP_AUTH_SECRET SCTP_PEER_AUTH_CHUNKS
SCTP_LOCAL_AUTH_CHUNKS
arg is an option-specific structure buffer provided by the caller. arg is an option-specific structure buffer provided by the caller.
See Section 8.5) subsections for more information on these options See Section 8.5) subsections for more information on these options
and option-specific structures. and option-specific structures.
sctp_opt_info() returns 0 on success, or on failure returns -1 and sctp_opt_info() returns 0 on success, or on failure returns -1 and
sets errno to the appropriate error code. sets errno to the appropriate error code.
All options that support specific settings on an association by All options that support specific settings on an association by
filling in either an association id variable or a sockaddr_storage filling in either an association id variable or a sockaddr_storage
skipping to change at page 51, line 4 skipping to change at page 54, line 16
the number of milliseconds that sacks will be delayed for. This the number of milliseconds that sacks will be delayed for. This
value will apply to all addresses of an association if the value will apply to all addresses of an association if the
spp_address field is empty. Note that unless the spp_flag is set spp_address field is empty. Note that unless the spp_flag is set
to SPP_SACKDELAY_ENABLE the value of this field is ignored. Note to SPP_SACKDELAY_ENABLE the value of this field is ignored. Note
also that a value of zero indicates the current setting should be also that a value of zero indicates the current setting should be
left unchanged. left unchanged.
spp_ipv6_flowlabel- This field is used in conjunction with the spp_ipv6_flowlabel- This field is used in conjunction with the
SPP_IPV4_FLOWLABEL flag. SPP_IPV4_FLOWLABEL flag.
spp_ipv4_tos- This field is used in conjunction with the SPP_IPV4_TOS spp_ipv4_tos- This field is used in conjunction with the SPP_IPV4_TOS
flag. flag.
spp_flags- These flags are used to control various features on an spp_flags- These flags are used to control various features on an
association. The flag field may contain zero or more of the association. The flag field is a bit mask which may contain zero
following options. or more of the following options:
SPP_HB_ENABLE - Enable heartbeats on the specified address. Note SPP_HB_ENABLE - Enable heartbeats on the specified address. Note
that if the address field is empty all addresses for the that if the address field is empty all addresses for the
association have heartbeats enabled upon them. association have heartbeats enabled upon them.
SPP_HB_DISABLE - Disable heartbeats on the speicifed address. SPP_HB_DISABLE - Disable heartbeats on the specified address.
Note that if the address field is empty all addresses for the Note that if the address field is empty all addresses for the
association will have their heartbeats disabled. Note also association will have their heartbeats disabled. Note also
that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive,
only one of these two should be specified. Enabling both only one of these two should be specified. Enabling both
fields will have undetermined results. fields will have undetermined results.
SPP_HB_DEMAND - Request a user initiated heartbeat to be made SPP_HB_DEMAND - Request a user initiated heartbeat to be made
immediately. immediately.
SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay
is to be set to the value of 0 milliseconds. is to be set to the value of 0 milliseconds.
SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the
specified address. Note that if the address feild is empty specified address. Note that if the address field is empty
then all addresses on the association are effected. then all addresses on the association are effected.
SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon
the specified address. Note that if the address feild is empty the specified address. Note that if the address field is empty
then all addresses on the association are effected. Not also then all addresses on the association are effected. Not also
that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually
exclusive. Enabling both will have undetermined results. exclusive. Enabling both will have undetermined results.
SPP_SACKDELAY_ENABLE - Setting this flag turns on delayed sack. SPP_SACKDELAY_ENABLE - Setting this flag turns on delayed sack.
The time specified in spp_sackdelay is used to specify the sack The time specified in spp_sackdelay is used to specify the sack
delay for this address. Note that if spp_address is empty then delay for this address. Note that if spp_address is empty then
all addresses will enable delayed sack and take on the sack all addresses will enable delayed sack and take on the sack
delay value specified in spp_sackdelay. delay value specified in spp_sackdelay.
SPP_SACKDELAY_DISABLE - Setting this flag turns off delayed sack. SPP_SACKDELAY_DISABLE - Setting this flag turns off delayed sack.
If the spp_address field is blank then delayed sack is disabled If the spp_address field is blank then delayed sack is disabled
skipping to change at page 52, line 4 skipping to change at page 55, line 18
specific destination address has this value set upon it. If specific destination address has this value set upon it. If
the association is specified, but not the address, then the the association is specified, but not the address, then the
flowlabel value is set for any future destination addresses flowlabel value is set for any future destination addresses
that may be added. The value is obtained in the that may be added. The value is obtained in the
spp_ipv6_flowlabel field. spp_ipv6_flowlabel field.
Upon retrieval, this flag will be set to indicate that the Upon retrieval, this flag will be set to indicate that the
spp_ipv6_flowlabel field has a valid value returned. If a spp_ipv6_flowlabel field has a valid value returned. If a
specific destination addresses is set (in the spp_address specific destination addresses is set (in the spp_address
field) when called then the value returned is that of the field) when called then the value returned is that of the
address. If just an assocaition is specified (and no address) address. If just an association is specified (and no address)
then the association default flowlabel is returned. If neither then the association default flowlabel is returned. If neither
an association nor an destination is specified, then the an association nor an destination is specified, then the
sockets default flowlabel is returned. For non IPv6 sockets, sockets default flowlabel is returned. For non IPv6 sockets,
then this flag will be left cleared. then this flag will be left cleared.
SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos
value associated with either the association or specific value associated with either the association or specific
address. If the address field is filled in, then the specific address. If the address field is filled in, then the specific
destination address has this value set upon it. If the destination address has this value set upon it. If the
association is specified, but not the address, then the tos association is specified, but not the address, then the tos
value is set for any future destination addresses that may be value is set for any future destination addresses that may be
added. The value is obtained in the spp_ipv4_tos field. added. The value is obtained in the spp_ipv4_tos field.
Upon retrieval, this flag will be set to indicate that the Upon retrieval, this flag will be set to indicate that the
spp_ipv4_tos field has a valid value returned. If a specific spp_ipv4_tos field has a valid value returned. If a specific
destination addresses is set when called (in the spp_address destination addresses is set when called (in the spp_address
field) then that specific destination addresses tos value is field) then that specific destination addresses tos value is
returned. If just an assocaition is specified then the returned. If just an association is specified then the
association default tos is returned. If neither an association association default tos is returned. If neither an association
nor an destination is specified, then the sockets default tos nor an destination is specified, then the sockets default tos
is returned. For non IPv4 sockets, then this flag will be left is returned. For non IPv4 sockets, then this flag will be left
cleared. cleared.
To read or modify these parameters, the application should call To read or modify these parameters, the application should call
sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option.
7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM)
Applications that wish to use the sendto() system call may wish to Applications that wish to use the sendto() system call may wish to
specify a default set of parameters that would normally be supplied specify a default set of parameters that would normally be supplied
through the inclusion of ancillary data. This socket option allows through the inclusion of ancillary data. This socket option allows
such an application to set the default sctp_sndrcvinfo structure. such an application to set the default sctp_sndrcvinfo structure.
The application that wishes to use this socket option simply passes The application that wishes to use this socket option simply passes
in to this call the sctp_sndrcvinfo structure defined in in to this call the sctp_sndrcvinfo structure defined in
Section 5.2.2) The input parameters accepted by this call include Section 5.2.2) The input parameters accepted by this call include
sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context,
sinfo_timetolive. The user must set the sinfo_assoc_id field to sinfo_timetolive. The sinfo_assoc_id field specifies the default
identify the association to affect if the caller is using the one-to- association used for send operations on one-to-many style sockets.
many style. It is ignored on the one-to-one style. Note that setting the
sinfo_assoc_id field to zero indicates that the users wishes to set
the endpoint default send parameters for all future associations.
7.1.15. Set notification and ancillary events (SCTP_EVENTS) 7.1.15. Set notification and ancillary events (SCTP_EVENTS)
This socket option is used to specify various notifications and This socket option is used to specify various notifications and
ancillary data the user wishes to receive. Please see Section 7.3) ancillary data the user wishes to receive. Please see Section 7.3)
for a full description of this option and its usage. for a full description of this option and its usage.
7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR)
This socket option is a boolean flag which turns on or off mapped V4 This socket option is a boolean flag which turns on or off mapped V4
skipping to change at page 53, line 35 skipping to change at page 56, line 47
the user. The option expects an integer. the user. The option expects an integer.
The default value for this option is '0' which indicates the user is The default value for this option is '0' which indicates the user is
NOT limiting fragmentation and only the PMTU will effect SCTP's NOT limiting fragmentation and only the PMTU will effect SCTP's
choice of DATA chunk size. choice of DATA chunk size.
7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK) 7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK)
This option adds a chunk type that the user is requesting to be This option adds a chunk type that the user is requesting to be
received only in an authenticated way. Changes to the list of chunks received only in an authenticated way. Changes to the list of chunks
will only effect associations that have not been formed. will only effect future associations on the socket.
struct sctp_authchunks { struct sctp_authchunk {
uint8_t sauth_chunk; uint8_t sauth_chunk;
}; };
sauth_chunks - This parameter contains a chunk type sauth_chunks - This parameter contains a chunk type
that the user is requesting to be authenticated. that the user is requesting to be authenticated.
The chunk types for INIT, INIT-ACK, COOKIE-ECHO, COOKIE-ACK, The chunk types for INIT, INIT-ACK, COOKIE-ECHO, COOKIE-ACK,
SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are
used an error MUST be returned. The usage of this option enables used an error MUST be returned. The usage of this option enables
SCTP-AUTH in cases where it is not required by other means (for SCTP-AUTH in cases where it is not required by other means (for
example the use of ADD-IP). example the use of ADD-IP).
7.1.19. Set the endpoint pair shared key (SCTP_AUTH_KEY) 7.1.19. Get or set the list of supported HMAC Identifiers
(SCTP_HMAC_IDENT)
This option will set the endpoint pair shared key which is used to This option gets or sets the list of HMAC algorithms that the local
build the association shared key. endpoint requires the peer to use.
struct sctp_hmacalgo {
uint32_t shmac_idents[];
};
shmac_idents - This parameter contains an array of HMAC Identifiers
that the local endpoint is requesting the peer to use, in priority
order.
7.1.20. Set a shared key (SCTP_AUTH_KEY)
This option will set a shared secret key which is used to build an
association shared key.
struct sctp_authkey { struct sctp_authkey {
sctp_assoc_t sca_assoc_id; sctp_assoc_t sca_assoc_id;
uint32_t sca_keynumber; uint32_t sca_keynumber;
struct sockaddr_storage sca_address;
uint8_t sca_key[]; uint8_t sca_key[];
}; };
sca_assoc_id - This parameter, if non-zero, indicates what sca_assoc_id - This parameter, if non-zero, indicates what
association that the shared key is being set upon. Note that if association that the shared key is being set upon. Note that if
this element contains zero, then the secret is set upon the this element contains zero, then the shared key is set upon the
endpoint and all future associations will use this secret (if not endpoint and all future associations will use this key (if not
changed by subsequent calls to SCTP_AUTH_KEY). changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one
sca_address - this parameter contains either a zero filled address, sockets, this parameter is ignored. Note, however, that this
in which case it has no effect on the call. Or this parameter may option will set a key on the association if the socket is
contain an existing association. An address may also be specified connected, otherwise this will set a key on the endpoint.
for a future association including the IP layer address and the sca_keynumber - this parameter is the shared key identifier by which
transport port, or just the IP layer address. Note that if the application will refer to this key. If a key of the specified
multiple keys are defined for addresses of the same endpoint (for index already exists, then this new key will replace the old
a multihomed endpoint) then an error will be returned and NO existing key. Note that shared key identifier '0' defaults to a
association will be formed on recipt of the INIT or INIT-ACK. null key.
sca_keynumber - this parameter is the key index by which the
application will refer to this key. If a key of the specified
index already exists, then this new key will replace the old key.
sca_key - This parameter contains an array of bytes that is to be sca_key - This parameter contains an array of bytes that is to be
used by the endpoint (or association) as the shared secret. used by the endpoint (or association) as the shared secret key.
Note, if the length of this field is zero, a null key is set.
7.1.20. Get the list of chunks the peer requires to be authenticated
(SCTP_PEER_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that
the peer requires to be received authenticated only.
struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id;
uint8_t gauth_chunks[];
};
gauth_assoc_id - This parameter, indicates for which association the
user is requesting the list of peer authenticated chunks.
gauth_chunks - This parameter contains an array of chunks that the
peer is requesting to be authenticated.
7.1.21. Get the list of chunks the local endpoint requires to be
authenticated (SCTP_LOCAL_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that
the local endpoint requires to be received authenticated only.
struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id;
uint8_t gauth_chunks[];
};
gauth_assoc_id - This parameter, indicates for which association the
user is requesting the list of local authenticated chunks.
gauth_chunks - This parameter contains an array of chunks that the
local endpoint is requesting to be authenticated.
7.1.22. Set the list of supported HMAC Identifiers (SCTP_HMAC_IDENT) 7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY)
This option sets a list of algorithms for a specified association This option will get or set the active shared key to be used to build
that the local endpoint requires the peer to use. the association shared key.
struct sctp_hmacalgo { struct sctp_authkeyid {
sctp_assoc_t shmac_assoc_id; sctp_assoc_t scact_assoc_id;
uint32_t shmac_idents[]; uint32_t scact_keynumber;
}; };
shmac_assoc_id - This parameter, indicates for which association the scact_assoc_id - This parameter, if non-zero, indicates what
user is setting the list of HMAC Identifiers. association that the shared key identifier is being set active
shmac_idents - This parameter contains an array of HMAC Identifiers upon. Note that if this element contains zero, then the
that the local endpoint is requesting the peer to use. activation applies to the endpoint and all future associations
will use the specified shared key identifier. For one-to-one
sockets, this parameter is ignored. Note, however, that this
option will set the active key on the association if the socket is
connected, otherwise this will set the default active key for the
endpoint.
scact_keynumber - this parameter is the shared key identifier which
the application is requesting to become the active shared key to
be used for sending authenticated chunks. The key identifier MUST
correspond to an existing shared key. Note that shared key
identifier '0' defaults to a null key.
7.1.23. Get or set the active key (SCTP_AUTH_SETKEY_ACTIVE) 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY)
This options will get or set the active key. This option will delete a shared secret key from use.
struct sctp_authkey { struct sctp_authkeyid {
sctp_assoc_t scact_assoc_id; sctp_assoc_t scact_assoc_id;
uint32_t scact_keynumber; uint32_t scact_keynumber;
uint32_t scact_sec_old;
uint32_t scact_sec_new;
struct sockaddr_storage scact_address;
}; };
scact_assoc_id - This parameter, if non-zero, indicates what scact_assoc_id - This parameter, if non-zero, indicates what
association that the shared key is being set upon. Note that if association that the shared key identifier is being deleted from.
this element contains zero, then the secret activation applys to Note that if this element contains zero, then the shared key is
the endpoint and all future associations will use this secret (if deleted from the endpoint and all associations will no longer use
not changed by subsequent calls). the specified shared key identifier (unless otherwise set on the
scact_address - this parameter contains either a zero filled address, association using SCTP_AUTH_KEY). For one-to-one sockets, this
in which case it has no effect on the call. Or this parameter may parameter is ignored. Note, however, that this option will delete
contain an existing association address. An address may also be the key from the association if the socket is connected, otherwise
specified for a future association including the IP layer address this will delete the key from the endpoint.
and the transport port, or just the IP layer address. Note that scact_keynumber - this parameter is the shared key identifier which
if multiple keys are defined for addresses of the same endpoint the application is requesting to be deleted. The key identifier
(for a multihomed endpoint) then an error will be returned and NO MUST correspond to an existing shared key and MUST NOT be the
association will be formed on recipt of the INIT or INIT-ACK. current active key. Note if this parameter is zero, use of the
scact_keynumber - this parameter is the key index by which the null key identifier '0' is disabled on the endpoint and/or
application will refer to this key. If a key of the specified association.
index already exists, then this new key will replace the old key.
scact_sec_old - this parameter list the number of seconds for which
both keys will be accepted. If this value is 0, then the new key
is made active immediately and packets with the old key will be
discarded. If this value is non-zero, then for the specified time
in seconds both keys will be accepted.
scact_sec_new - this parameter indicates the number of seconds until
the new key will start being used as the active key. If this
value is '0' then the new key will start being used immediately.
If this value is non-zero then the specified number of seconds
will be delayed until new chunks being transmitted begin using the
new key.
7.1.24. Get or set delayed ack timer (SCTP_DELAYED_ACK_TIME) 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_ACK_TIME)
This options will get or set the delayed ack timer. The time is set This options will get or set the delayed ack timer. The time is set
in milliseconds. If the assoc_id is 0, then this sets or gets the in milliseconds. If the assoc_id is 0, then this sets or gets the
endpoints default delayed ack timer value. If the assoc_id field is endpoints default delayed ack timer value. If the assoc_id field is
non-zero, then the set or get effects the specified association. non-zero, then the set or get effects the specified association.
struct sctp_assoc_value { struct sctp_assoc_value {
sctp_assoc_t assoc_id; sctp_assoc_t assoc_id;
uint32_t assoc_value; uint32_t assoc_value;
}; };
assoc_id - This parameter, indicates which association the user is assoc_id - This parameter, indicates which association the user is
preforming an action upon. Note that if this field's value is performing an action upon. Note that if this field's value is
zero then the endpoints default value is changed (effecting future zero then the endpoints default value is changed (effecting future
associations only). associations only).
assoc_value - This parameter contains the number of milliseconds that assoc_value - This parameter contains the number of milliseconds that
the user is requesting the delayed ACK timer be set to. Note that the user is requesting the delayed ACK timer be set to. Note that
this value is defined in the standard to be between 200 and 500 this value is defined in the standard to be between 200 and 500
milliseconds. milliseconds.
7.1.25. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE) 7.1.24. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE)
This options will at a minimum specify if the implementation is doing This options will at a minimum specify if the implementation is doing
fragmented interleave. Fragmented interleave, for a one to many fragmented interleave. Fragmented interleave, for a one to many
socket, is when subsequent calls to receive a message may return socket, is when subsequent calls to receive a message may return
parts of messages from different associations. Some implementations parts of messages from different associations. Some implementations
may allow you to turn this value on or off. If so, when turned off, may allow you to turn this value on or off. If so, when turned off,
no fragment interleave will occur (which will cause a head of line no fragment interleave will occur (which will cause a head of line
blocking amongst multiple associations sharing the same one to many blocking amongst multiple associations sharing the same one to many
socket). When this option is turned on, then each receive call may socket). When this option is turned on, then each receive call may
come from a different association (thus the user must receive data come from a different association (thus the user must receive data
skipping to change at page 57, line 39 skipping to change at page 60, line 18
This option takes a boolean value. A non-zero value indicates that This option takes a boolean value. A non-zero value indicates that
fragmented interleave is on. A value of zero indicates that fragmented interleave is on. A value of zero indicates that
fragmented interleave is off. fragmented interleave is off.
Note that it is important that an implementation that allows this Note that it is important that an implementation that allows this
option to be turned on, have it off by default. Otherwise an unaware option to be turned on, have it off by default. Otherwise an unaware
application using the one to many model may become confused and act application using the one to many model may become confused and act
incorrectly. incorrectly.
7.1.26. Set or Get the sctp partial delivery point 7.1.25. Set or Get the sctp partial delivery point
(SCTP_PARTIAL_DELIVERY_POINT) (SCTP_PARTIAL_DELIVERY_POINT)
This option will set or get the SCTP partial delivery point. This This option will set or get the SCTP partial delivery point. This
point is the size of a message where the partial delivery API will be point is the size of a message where the partial delivery API will be
invoked to help free up rwnd space for the peer. Setting this to a invoked to help free up rwnd space for the peer. Setting this to a
lower value will cause partial delivery's to happen more often. The lower value will cause partial delivery's to happen more often. The
call's argument is an integer that sets or gets the partial delivery calls argument is an integer that sets or gets the partial delivery
point. point.
7.1.26. Set or Get the use of extended receive info
(SCTP_USE_EXT_RCVINFO)
This option will enable or disable the use of the extended version of
the sctp_sndrcvinfo structure. If this option is disabled, then the
normal sctp_sndrcvinfo structure is returned in all receive message
calls. If this option is enabled then the sctp_extrcvinfo structure
is returned in all receive message calls.
Note that the sctp_extrcvinfo structure is never used in any send
call.
7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF)
This option will enable or disable the use of the automatic
generation of ASCONF chunks to add and delete addresses to an
existing association. Note that this option has two caveats namely:
a) it only effects sockets that are bound to all addresses on the
machine, and b) the system administrator may have an overriding
control that turns the asconf feature off no matter what setting the
socket option may have.
7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST)
This option will allow a user to change the maximum burst of packets
that can be emitted by this association. Note that the default value
is 4, and some implementations may restrict this setting so that it
can only be lowered.
7.1.29. Set or Get the default context (SCTP_CONTEXT)
The context field in the sctp_sndrcvinfo structure is normally only
used when a failed message is retrieved holding the value that was
sent down on the actual send call. This option allows the setting of
a default context on an association basis that will be received on
reading messages from the peer. This is especially helpful in the
one-2-many model for an application to keep some reference to an
internal state machine that is processing messages on the
association. Note that the setting of this value only effects
received messages from the peer and does not effect the value that is
saved with outbound messages.
To set or get this option the user fills in the following structure:
struct sctp_assoc_value {
sctp_assoc_t assoc_id;
uint32_t assoc_value;
};
assoc_id - This parameter, indicates which association the user is
performing an action upon. Note that if this field's value is
zero then the endpoints default value is changed (effecting future
associations only).
assoc_value - This parameter contains the context.
7.2. Read-Only Options 7.2. Read-Only Options
7.2.1. Association Status (SCTP_STATUS) 7.2.1. Association Status (SCTP_STATUS)
Applications can retrieve current status information about an Applications can retrieve current status information about an
association, including association state, peer receiver window size, association, including association state, peer receiver window size,
number of unacked data chunks, and number of data chunks pending number of unacked data chunks, and number of data chunks pending
receipt. This information is read-only. The following structure is receipt. This information is read-only. The following structure is
used to access this information: used to access this information:
skipping to change at page 59, line 38 skipping to change at page 63, line 23
uint32_t spinfo_srtt; uint32_t spinfo_srtt;
uint32_t spinfo_rto; uint32_t spinfo_rto;
uint32_t spinfo_mtu; uint32_t spinfo_mtu;
}; };
spinfo_address - This is filled in the application, and contains the spinfo_address - This is filled in the application, and contains the
peer address of interest. peer address of interest.
On return from getsockopt(): On return from getsockopt():
spinfo_state - This contains the peer addresses's state (either spinfo_state - This contains the peer addresses's state (either
SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifer SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier
SCTP_UNCONFIRMED) SCTP_UNCONFIRMED)
spinfo_cwnd - This contains the peer addresses's current congestion spinfo_cwnd - This contains the peer addresses's current congestion
window. window.
spinfo_srtt - This contains the peer addresses's current smoothed spinfo_srtt - This contains the peer addresses's current smoothed
round-trip time calculation in milliseconds. round-trip time calculation in milliseconds.
spinfo_rto - This contains the peer addresses's current spinfo_rto - This contains the peer addresses's current
retransmission timeout value in milliseconds. retransmission timeout value in milliseconds.
spinfo_mtu - The current P-MTU of this address. spinfo_mtu - The current P-MTU of this address.
spinfo_assoc_id - This is field may be filled in by the application,
spinfo_assoc_id - (one-to-many style socket) This is filled in the if so, this field will have priority in looking up the association
application, and identifies the association for this query. over the address specified in spinfo_address. Note that if the
address does not belong to the association specified then this
call will fail. If the application does NOT fill in the
spinfo_assoc_id, then the address will be used to lookup the
association and on return this field will have the valid
association id. In other words, this call can be used to
translate a address into an association id.
To retrieve this information, use sctp_opt_info() with the To retrieve this information, use sctp_opt_info() with the
SCTP_GET_PEER_ADDR_INFO options. SCTP_GET_PEER_ADDR_INFO options.
7.2.3. Get the list of chunks the peer requires to be authenticated
(SCTP_PEER_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that
the peer requires to be received authenticated only.
struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id;
uint8_t gauth_chunks[];
};
gauth_assoc_id - This parameter, indicates which association the user
is requesting the list of peer authenticated chunks. For one-to-
one sockets, this parameter is ignored.
gauth_chunks - This parameter contains an array of chunks that the
peer is requesting to be authenticated.
7.2.4. Get the list of chunks the local endpoint requires to be
authenticated (SCTP_LOCAL_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that
the local endpoint requires to be received authenticated only.
struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id;
uint8_t gauth_chunks[];
};
gauth_assoc_id - This parameter, indicates which association the user
is requesting the list of local authenticated chunks. For one-to-
one sockets, this parameter is ignored.
gauth_chunks - This parameter contains an array of chunks that the
local endpoint is requesting to be authenticated.
7.2.5. Get the list of current associations (SCTP_GET_ASOC_ID_LIST)
This option gets a list of current associations that are associated
with a socket.
struct sctp_assoc_ids {
uint16_t asls_assoc_start; /* array of index's start at 0 */
uint8_t asls_numb_present;
uint8_t asls_more_to_get;
sctp_assoc_t asls_assoc_id[MAX_ASOC_IDS_RET];
};
asls_assoc_start - This parameter gives an initial starting place to
begin collecting association information. Normally a user sets
this initially to 0. Subsequent calls that need to get more
association identifications (in cases where the socket has more
than MAX_ASOC_IDS_RET established i.e asls_more_to_get returns set
to false) are made by incrementing the asls_assoc_start by the
number of previous association id's seen. This cycle is repeated
until the asls_more_to_get field becomes true, indicating that all
association id's have been retrieved.
asls_numb_present - This field holds the total number of associations
that have been copied into the asls_assoc_id array. This value
will NOT be larger than MAX_ASOC_IDS_RET.
asls_more_to_get - This field holds a boolean flag indicating to the
caller if more association id's are available then asked for.
Subsequent calls to this option will be needed to gather these
association id's.
asls_assoc_id - an array of association id's that are currently
active under this socket.
MAX_ASOC_IDS_RET This value is a constant defined to limit the number
of association identifications returned with each call. This
value can be no larger than 255..
7.3. Ancillary Data and Notification Interest Options 7.3. Ancillary Data and Notification Interest Options
Applications can receive per-message ancillary information and Applications can receive per-message ancillary information and
notifications of certain SCTP events with recvmsg(). notifications of certain SCTP events with recvmsg().
The following optional information is available to the application: The following optional information is available to the application:
1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e.
stream number, TSN, SSN, etc. described in Section 5.2.2) stream number, TSN, SSN, etc. described in Section 5.2.2)
2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in
skipping to change at page 61, line 47 skipping to change at page 67, line 16
reception of partial delivery notifications. Setting the flag to 0 reception of partial delivery notifications. Setting the flag to 0
will disable partial delivery event notifications. For more will disable partial delivery event notifications. For more
information on event notifications please see Section 5.3. information on event notifications please see Section 5.3.
sctp_adaptation_layer_event - Setting this flag to 1 will enable the sctp_adaptation_layer_event - Setting this flag to 1 will enable the
reception of adaptation layer notifications. Setting the flag to 0 reception of adaptation layer notifications. Setting the flag to 0
will disable adaptation layer event notifications. For more will disable adaptation layer event notifications. For more
information on event notifications please see Section 5.3. information on event notifications please see Section 5.3.
sctp_authentication_event - Setting this flag to 1 will enable the sctp_authentication_event - Setting this flag to 1 will enable the
receiption of authentication layer notifications. Setting the flag reception of authentication layer notifications. Setting the flag to
to 0 will disable authentication layer event notifications. For More 0 will disable authentication layer event notifications. For More
information please see Section 5.3. information please see Section 5.3.
An example where an application would like to receive data io events An example where an application would like to receive data io events
and association events but no others would be as follows: and association events but no others would be as follows:
{ {
struct sctp_event_subscribe event; struct sctp_event_subscribe event;
memset(&event,0,sizeof(event)); memset(&event,0,sizeof(event));
skipping to change at page 66, line 40 skipping to change at page 72, line 7
stream_no - is the same as sinfo_stream (see section 5.2.2) stream_no - is the same as sinfo_stream (see section 5.2.2)
timetolive - is the same as sinfo_timetolive (see section 5.2.2) timetolive - is the same as sinfo_timetolive (see section 5.2.2)
context - is the same as sinfo_context (see section 5.2.2) context - is the same as sinfo_context (see section 5.2.2)
8.8. sctp_recvmsg() 8.8. sctp_recvmsg()
An implementation may provide a library function (or possibly system An implementation may provide a library function (or possibly system
call) to assist the user with the advanced features of SCTP. Note call) to assist the user with the advanced features of SCTP. Note
that in order for the sctp_sndrcvinfo structure to be filled in by that in order for the sctp_sndrcvinfo structure to be filled in by
sctp_recvmsg() the caller must enable the sctp_data_io_events with sctp_recvmsg() the caller must enable the sctp_data_io_events with
the SCTP_EVENTS option. the SCTP_EVENTS option. Note that the setting of the
SCTP_USE_EXT_RCVINFO will effect this function as well, causing the
sctp_sndrcvinfo information to be extended.
sctp_recvmsg(). Its syntax is, sctp_recvmsg(). Its syntax is,
ssize_t sctp_recvmsg(int sd, ssize_t sctp_recvmsg(int sd,
void *msg, void *msg,
size_t len, size_t len,
struct sockaddr *from, struct sockaddr *from,
socklen_t *fromlen socklen_t *fromlen
struct sctp_sndrcvinfo *sinfo struct sctp_sndrcvinfo *sinfo
int *msg_flags) int *msg_flags)
skipping to change at page 67, line 24 skipping to change at page 72, line 39
msg_flags - A pointer to a integer to be filled with any message msg_flags - A pointer to a integer to be filled with any message
flags (e.g. MSG_NOTIFICATION). flags (e.g. MSG_NOTIFICATION).
8.9. sctp_connectx() 8.9. sctp_connectx()
An implementation may provide a library function (or possibly system An implementation may provide a library function (or possibly system
call) to assist the user with associating to an endpoint that is call) to assist the user with associating to an endpoint that is
multi-homed. Much like sctp_bindx() this call allows a caller to multi-homed. Much like sctp_bindx() this call allows a caller to
specify multiple addresses at which a peer can be reached. The way specify multiple addresses at which a peer can be reached. The way
the SCTP stack uses the list of addresses to set up the association the SCTP stack uses the list of addresses to set up the association
is implementation dependant. This function only specifies that the is implementation dependent. This function only specifies that the
stack will try to make use of all the addresses in the list when stack will try to make use of all the addresses in the list when
needed. needed.
Note that the list of addresses passed in is only used for setting up Note that the list of addresses passed in is only used for setting up
the association. It does not necessarily equal the set of addresses the association. It does not necessarily equal the set of addresses
the peer uses for the resulting association. If the caller wants to the peer uses for the resulting association. If the caller wants to
find out the set of peer addresses, it must use sctp_getpaddrs() to find out the set of peer addresses, it must use sctp_getpaddrs() to
retrieve them after the association has been set up. retrieve them after the association has been set up.
sctp_connectx(). Its syntax is, sctp_connectx(). Its syntax is,
skipping to change at page 68, line 17 skipping to change at page 73, line 33
int sctp_send(int sd, int sctp_send(int sd,
const void *msg, const void *msg,
size_t len, size_t len,
const struct sctp_sndrcvinfo *sinfo, const struct sctp_sndrcvinfo *sinfo,
int flags); int flags);
sd - is the socket descriptor sd - is the socket descriptor
msg - The message to be sent msg - The message to be sent
len - The length of the message len - The length of the message
sinfo - A pointer to a sctp_sndrcvinfo struture used as described in sinfo - A pointer to a sctp_sndrcvinfo structure used as described in
5.2.2 for a sendmsg call. 5.2.2 for a sendmsg call.
flags - is used in the same format as the sendmsg call flags (e.g. flags - is used in the same format as the sendmsg call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
This function call may also be used to terminate an association using This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to an association identification by setting the sinfo.sinfo_flags to
SCTP_EOF and the sinfo.sinf_associd to the association that needs to SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs
be terminated. In such a case the len of the message would be zero. to be terminated. In such a case the len of the message would be
zero.
8.11. sctp_sendx() 8.11. sctp_sendx()
An implementation may provide another alternative function or system An implementation may provide another alternative function or system
call to assist an application with the sending of data without the call to assist an application with the sending of data without the
use of the CMSG header structures that also gives a list of use of the CMSG header structures that also gives a list of
addresses. The list of addresses is provided for implicit addresses. The list of addresses is provided for implicit
association setup. In such a case the list of addresses serves the association setup. In such a case the list of addresses serves the
same purpose as the addresses given in sctp_connectx (see same purpose as the addresses given in sctp_connectx (see
Section 8.9). Section 8.9).
skipping to change at page 69, line 4 skipping to change at page 74, line 17
sctp_sendx(). Its syntax is, sctp_sendx(). Its syntax is,
int sctp_sendx(int sd, int sctp_sendx(int sd,
const void *msg, const void *msg,
size_t len, size_t len,
struct sockaddr *addrs, struct sockaddr *addrs,
int addrcnt, int addrcnt,
struct sctp_sndrcvinfo *sinfo, struct sctp_sndrcvinfo *sinfo,
int flags); int flags);
sd - is the socket descriptor sd - is the socket descriptor
msg - The message to be sent msg - The message to be sent
len - The length of the message len - The length of the message
addrs - is an array of addresses. addrs - is an array of addresses.
addrcnt - is the number of addresses in the array. addrcnt - is the number of addresses in the array.
sinfo - A pointer to a sctp_sndrcvinfo struture used as described in sinfo - A pointer to a sctp_sndrcvinfo structure used as described in
5.2.2 for a sendmsg call. 5.2.2 for a sendmsg call.
flags - is used in the same format as the sendmsg call flags (e.g. flags - is used in the same format as the sendmsg call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
Note that on return from this call the sinfo structure will have Note that on return from this call the sinfo structure will have
changed in that the sinfo_assoc_id will be filled in with the new changed in that the sinfo_assoc_id will be filled in with the new
association id. association id.
This function call may also be used to terminate an association using This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to an association identification by setting the sinfo.sinfo_flags to
SCTP_EOF and the sinfo.sinfo_associd to the association that needs to SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs
be terminated. In such a case the len of the message would be zero. to be terminated. In such a case the len of the message would be
zero.
8.12. sctp_getaddrlen 8.12. sctp_getaddrlen
For application binary portability it is sometimes desireable to know For application binary portability it is sometimes desirable to know
what the kernel thinks is the length of a socket address family. what the kernel thinks is the length of a socket address family.
This function, when called with a valid family type will return the This function, when called with a valid family type will return the
length that the operating system uses in the specified family's length that the operating system uses in the specified family's
socket address structure. socket address structure.
int sctp_getaddrlen(sa_family_t family); int sctp_getaddrlen(sa_family_t family);
9. Preprocessor Constants 9. Preprocessor Constants
For application portability it is desireable to define pre-processor For application portability it is desirable to define pre-processor
constants for determination if sctp is present and supports various constants for determination if sctp is present and supports various
features. The following pre-processor constants should be defined in features. The following pre-processor constants should be defined in
a include file, sctp.h. a include file, sctp.h.
HAVE_SCTP - If this constant is defined to 1, then an implementation HAVE_SCTP - If this constant is defined to 1, then an implementation
of SCTP is available. of SCTP is available.
HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel
SCTP implementation is available through the sockets interface. SCTP implementation is available through the sockets interface.
HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP
implementation supports the partial reliablility extension to implementation supports the partial reliability extension to SCTP.
SCTP.
HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP
implementation supports the dynamic address extension to SCTP. implementation supports the dynamic address extension to SCTP.
HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the
SCTP implementation supports the ability to request setting of the SCTP implementation supports the ability to request setting of the
remote primary address. remote primary address.
HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1,
then the SCTP implementation supports the satellite network then the SCTP implementation supports the satellite network
extension to SCTP. extension to SCTP.
HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP
implementation dedicates separate buffer space to each association implementation dedicates separate buffer space to each association
on a one-to-many socket. If this constant is defined to 0, then on a one-to-many socket. If this constant is defined to 0, then
the implementation provides a single block of shared buffer space the implementation provides a single block of shared buffer space
for a one-to-many socket. for a one-to-many socket.
HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP
implementation supports initiating an association on a one-to-one implementation supports initiating an association on a one-to-one
style socket without the use of connect(), as outlined in style socket without the use of connect(), as outlined in
Section 4.1.5. Section 4.1.5.
HAVE_SCTP_EXT_RCVINFO - If this constant is defined to 1, then the
SCTP implementation supports the use of the extended style
sndrecinfo structure, sctp_extrcvinfo.
10. IANA considerations 10. IANA considerations
This document contains no IANA considerations. This document contains no IANA considerations.
11. Security Considerations 11. Security Considerations
Many TCP and UDP implementations reserve port numbers below 1024 for Many TCP and UDP implementations reserve port numbers below 1024 for
privileged users. If the target platform supports privileged users, privileged users. If the target platform supports privileged users,
the SCTP implementation SHOULD restrict the ability to call bind() or the SCTP implementation SHOULD restrict the ability to call bind() or
sctp_bindx() on these port numbers to privileged users. sctp_bindx() on these port numbers to privileged users.
Similarly unpriviledged users should not be able to set protocol Similarly unprivileged users should not be able to set protocol
parameters which could result in the congestion control algorithm parameters which could result in the congestion control algorithm
being more aggressive than permitted on the public Internet. These being more aggressive than permitted on the public Internet. These
parameters are: parameters are:
struct sctp_rtoinfo struct sctp_rtoinfo
If an unprivileged user inherits a one-to-many style socket with open If an unprivileged user inherits a one-to-many style socket with open
associations on a privileged port, it MAY be permitted to accept new associations on a privileged port, it MAY be permitted to accept new
associations, but it SHOULD NOT be permitted to open new associations, but it SHOULD NOT be permitted to open new
associations. This could be relevant for the r* family of protocols. associations. This could be relevant for the r* family of protocols.
 End of changes. 82 change blocks. 
235 lines changed or deleted 532 lines changed or added

This html diff was produced by rfcdiff 1.32. The latest version is available from http://www.levkowetz.com/ietf/tools/rfcdiff/