idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 22. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 3947. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3958. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3965. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3971. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 1061 has weird spacing: '...g_level cms...' == Line 1115 has weird spacing: '...g_level cms...' == Line 1247 has weird spacing: '...g_level cms...' == Line 1358 has weird spacing: '...n_event sn_s...' == Line 1361 has weird spacing: '...y_event sn_...' == (2 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are 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 example the use of ADD-IP). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 9, 2007) is 6136 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 3001 -- Looks like a reference, but probably isn't: '1' on line 3834 == Unused Reference: 'RFC2026' is defined on line 3556, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 3559, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (Obsoleted by RFC 4960) Summary: 6 errors (**), 0 flaws (~~), 12 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Cisco Systems, Inc. 4 Expires: January 10, 2008 Q. Xie 5 Motorola, Inc. 6 L. Yarroll 7 TimeSys Corp 8 K. Poon 9 Sun Microsystems, Inc. 10 M. Tuexen 11 Univ. of Applied Sciences Muenster 12 July 9, 2007 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-15.txt 17 Status of this Memo 19 By submitting this Internet-Draft, each author represents that any 20 applicable patent or other IPR claims of which he or she is aware 21 have been or will be disclosed, and any of which he or she becomes 22 aware will be disclosed, in accordance with Section 6 of BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on January 10, 2008. 42 Copyright Notice 44 Copyright (C) The IETF Trust (2007). 46 Abstract 48 This document describes a mapping of the Stream Control Transmission 49 Protocol SCTP into a sockets API. The benefits of this mapping 50 include compatibility for TCP applications, access to new SCTP 51 features and a consolidated error and event notification scheme. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6 59 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 60 3.1.1. socket() - one-to-many style socket . . . . . . . . . 7 61 3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8 62 3.1.3. listen() - One-to-many style socket . . . . . . . . . 9 63 3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9 64 3.1.5. close() - one-to-many style socket . . . . . . . . . . 11 65 3.1.6. connect() - one-to-many style socket . . . . . . . . . 11 66 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 67 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 68 3.4. Special considerations . . . . . . . . . . . . . . . . . . 13 69 4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15 70 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15 71 4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16 72 4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 16 73 4.1.3. listen() - one-to-one style socket . . . . . . . . . . 17 74 4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18 75 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18 76 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19 77 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19 78 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20 79 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20 80 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 81 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21 82 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22 83 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23 84 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24 85 5.2.3. Extended SCTP Header Information Structure 86 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27 87 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 29 88 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 29 89 5.4. Ancillary Data Considerations and Semantics . . . . . . . 40 90 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 40 91 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 40 92 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 41 93 6. Common Operations for Both Styles . . . . . . . . . . . . . . 42 94 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 42 95 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 43 96 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 44 97 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 98 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 45 99 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 46 100 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 46 101 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 47 102 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 49 103 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 49 104 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 49 105 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 49 106 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 50 107 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 50 108 7.1.9. Set Peer Primary Address 109 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 50 110 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 51 111 7.1.11. Set Adaptation Layer Indicator 112 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 51 113 7.1.12. Enable/Disable message fragmentation 114 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 51 115 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 52 116 7.1.14. Set default send parameters 117 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 54 118 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 54 119 7.1.16. Set/clear IPv4 mapped addresses 120 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 54 121 7.1.17. Get or set the maximum fragmentation size 122 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 55 123 7.1.18. Add a chunk that must be authenticated 124 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 55 125 7.1.19. Get or set the list of supported HMAC Identifiers 126 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 56 127 7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 56 128 7.1.21. Get or set the active shared key 129 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 57 130 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 58 131 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_SACK) . . . 58 132 7.1.24. Get or set fragmented interleave 133 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 59 134 7.1.25. Set or Get the sctp partial delivery point 135 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 60 136 7.1.26. Set or Get the use of extended receive info 137 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 60 138 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 61 139 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 61 140 7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 61 141 7.1.30. Enable or disable explicit EOR marking 142 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 62 143 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 62 144 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 62 145 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 63 146 7.2.3. Get the list of chunks the peer requires to be 147 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 64 148 7.2.4. Get the list of chunks the local endpoint requires 149 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 65 150 7.2.5. Get the current number of associations 151 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 65 152 7.2.6. Get the current identifiers of associations 153 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 65 154 7.3. Ancillary Data and Notification Interest Options . . . . . 66 155 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 68 156 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 68 157 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 69 158 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 70 159 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 71 160 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 71 161 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 72 162 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 72 163 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 72 164 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 73 165 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 74 166 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 75 167 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 76 168 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 76 169 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 77 170 11. Security Considerations . . . . . . . . . . . . . . . . . . . 77 171 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77 172 13. Normative references . . . . . . . . . . . . . . . . . . . . . 77 173 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 78 174 Appendix B. one-to-many style Code Example . . . . . . . . . . . 83 175 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 85 176 Intellectual Property and Copyright Statements . . . . . . . . . . 87 178 1. Introduction 180 The sockets API has provided a standard mapping of the Internet 181 Protocol suite to many operating systems. Both TCP RFC793 [RFC0793] 182 and UDP RFC768 [RFC0768] have benefited from this standard 183 representation and access method across many diverse platforms. SCTP 184 is a new protocol that provides many of the characteristics of TCP 185 but also incorporates semantics more akin to UDP. This document 186 defines a method to map the existing sockets API for use with SCTP, 187 providing both a base for access to new features and compatibility so 188 that most existing TCP applications can be migrated to SCTP with few 189 (if any) changes. 191 There are three basic design objectives: 193 1) Maintain consistency with existing sockets APIs: 194 We define a sockets mapping for SCTP that is consistent with other 195 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 196 IPv6). 197 2) Support a one-to-many style interface 198 This set of semantics is similar to that defined for connection- 199 less protocols, such as UDP. A one-to-many style SCTP socket 200 should be able to control multiple SCTP associations. This is 201 similar to an UDP socket, which can communicate with many peer end 202 points. Each of these associations is assigned an association ID 203 so that an applications can use the ID to differentiate them. 204 Note that SCTP is connection-oriented in nature, and it does not 205 support broadcast or multicast communications, as UDP does. 206 3) Support a one-to-one style interface 207 This interface supports a similar semantics as sockets for 208 connection-oriented protocols, such as TCP. A one-to-one style 209 SCTP socket should only control one SCTP association. 210 One purpose of defining this interface is to allow existing 211 applications built on other connection-oriented protocols be 212 ported to use SCTP with very little effort. And developers 213 familiar with those semantics can easily adapt to SCTP. Another 214 purpose is to make sure that existing mechanisms in most OSes to 215 deal with socket, such as select(), should continue to work with 216 this style of socket. 217 Extensions are added to this mapping to provide mechanisms to 218 exploit new features of SCTP. 220 Goals 2 and 3 are not compatible, so in this document we define two 221 modes of mapping, namely the one-to-many style mapping and the one- 222 to-one style mapping. These two modes share some common data 223 structures and operations, but will require the use of two different 224 application programming styles. Note that all new SCTP features can 225 be used with both styles of socket. The decision on which one to use 226 depends mainly on the nature of applications. 228 A mechanism is defined to extract a one-to-many style SCTP 229 association into a one-to-one style socket. 231 Some of the SCTP mechanisms cannot be adequately mapped to existing 232 socket interface. In some cases, it is more desirable to have new 233 interface instead of using existing socket calls. Section 8 of this 234 document describes those new interface. 236 2. Conventions 238 2.1. Data Types 240 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 241 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 242 (e.g., uint16_t). We also assume the argument data types from 243 1003.1g when possible (e.g., the final argument to setsockopt() is a 244 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 245 size_t data type is used. 247 3. one-to-many style Interface 249 The one-to-many style interface has the following characteristics: 251 A) Outbound association setup is implicit. 253 B) Messages are delivered in complete messages (with one notable 254 exception). 256 C) There is a 1 to MANY relationship between socket and association. 258 3.1. Basic Operation 260 A typical server in this style uses the following socket calls in 261 sequence to prepare an endpoint for servicing requests: 263 1. socket() 264 2. bind() 265 3. listen() 266 4. recvmsg() 267 5. sendmsg() 268 6. close() 270 A typical client uses the following calls in sequence to setup an 271 association with a server to request services: 273 1. socket() 274 2. sendmsg() 275 3. recvmsg() 276 4. close() 278 In this style, by default, all the associations connected to the 279 endpoint are represented with a single socket. Each associations is 280 assigned an association ID (type is sctp_assoc_t) so that an 281 application can use it to differentiate between them. In some 282 implementations, the peer endpoints addresses can also be used for 283 this purpose. But this is not required for performance reasons. If 284 an implementation does not support using addresses to differentiate 285 between different associations, the sendto() call can only be used to 286 setup an association implicitly. It cannot be used to send data to 287 an established association as the association ID cannot be specified. 289 Once as association ID is assigned to an SCTP association, that ID 290 will not be reused until the application explicitly terminates the 291 association. The resources belonged to that association will not be 292 freed until that happens. This is similar to the close() operation 293 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 294 option (section 7.1.8) is set. In this case, after the association 295 is terminated gracefully automatically, the association ID assigned 296 to it can be reused. All applications using this option should be 297 aware of this to avoid the possible problem of sending data to an 298 incorrect peer end point. 300 If the server or client wishes to branch an existing association off 301 to a separate socket, it is required to call sctp_peeloff() and in 302 the parameter specifies the association identification. The 303 sctp_peeloff() call will return a new socket which can then be used 304 with recv() and send() functions for message passing. See 305 Section 8.2 for more on branched-off associations. 307 Once an association is branched off to a separate socket, it becomes 308 completely separated from the original socket. All subsequent 309 control and data operations to that association must be done through 310 the new socket. For example, the close operation on the original 311 socket will not terminate any associations that have been branched 312 off to a different socket. 314 We will discuss the one-to-many style socket calls in more details in 315 the following subsections. 317 3.1.1. socket() - one-to-many style socket 319 Applications use socket() to create a socket descriptor to represent 320 an SCTP endpoint. 322 The syntax is, 324 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 326 or, 328 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 330 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 331 socket. 333 The first form creates an endpoint which can use only IPv4 addresses, 334 while, the second form creates an endpoint which can use both IPv6 335 and IPv4 addresses. 337 3.1.2. bind() - one-to-many style socket 339 Applications use bind() to specify which local address the SCTP 340 endpoint should associate itself with. 342 An SCTP endpoint can be associated with multiple addresses. To do 343 this, sctp_bindx() is introduced in section Section 8.1 to help 344 applications do the job of associating multiple addresses. 346 These addresses associated with a socket are the eligible transport 347 addresses for the endpoint to send and receive data. The endpoint 348 will also present these addresses to its peers during the association 349 initialization process, see RFC2960 [RFC2960]. 351 After calling bind(), if the endpoint wishes to accept new 352 associations on the socket, it must call listen() (see section 353 Section 3.1.3). 355 The syntax of bind() is, 357 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 359 sd - the socket descriptor returned by socket(). 360 addr - the address structure (struct sockaddr_in or struct 361 sockaddr_in6 RFC2553 [RFC2553]). 362 addrlen - the size of the address structure. 364 If sd is an IPv4 socket, the address passed must be an IPv4 address. 365 If the sd is an IPv6 socket, the address passed can either be an IPv4 366 or an IPv6 address. 368 Applications cannot call bind() multiple times to associate multiple 369 addresses to an endpoint. After the first call to bind(), all 370 subsequent calls will return an error. 372 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 373 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 374 operating system will associate the endpoint with an optimal address 375 set of the available interfaces. 377 If a bind() is not called prior to a sendmsg() call that initiates a 378 new association, the system picks an ephemeral port and will choose 379 an address set equivalent to binding with a wildcard address. One of 380 those addresses will be the primary address for the association. 381 This automatically enables the multi-homing capability of SCTP. 383 3.1.3. listen() - One-to-many style socket 385 By default, new associations are not accepted for one-to-many style 386 sockets. An application uses listen() to mark a socket as being able 387 to accept new associations. The syntax is, 389 int listen(int sd, int backlog); 391 sd - the socket descriptor of the endpoint. 392 backlog - if backlog is non-zero, enable listening else disable 393 listening. 395 Note that one-to-many style socket consumers do not need to call 396 accept to retrieve new associations. Calling accept() on a one-to- 397 many style socket should return EOPNOTSUPP. Rather, new associations 398 are accepted automatically, and notifications of the new associations 399 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 400 these notifications are enabled). Clients will typically not call 401 listen(), so that they can be assured that the only associations on 402 the socket will be ones they actively initiated. Server or peer-to- 403 peer sockets, on the other hand, will always accept new associations, 404 so a well-written application using server one-to-many style sockets 405 must be prepared to handle new associations from unwanted peers. 407 Also note that the SCTP_ASSOC_CHANGE event provides the association 408 ID for a new association, so if applications wish to use the 409 association ID as input to other socket calls, they should ensure 410 that the SCTP_ASSOC_CHANGE event is enabled. 412 3.1.4. sendmsg() and recvmsg() - one-to-many style socket 414 An application uses sendmsg() and recvmsg() call to transmit data to 415 and receive data from its peer. 417 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 419 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 421 sd - the socket descriptor of the endpoint. 422 message: pointer to the msghdr structure which contains a single 423 user message and possibly some ancillary data. See Section 5 for 424 complete description of the data structures. 425 flags - No new flags are defined for SCTP at this level. See 426 Section 5 for SCTP-specific flags used in the msghdr structure. 428 As we will see in Section 5, along with the user data, the ancillary 429 data field is used to carry the sctp_sndrcvinfo and/or the 430 sctp_initmsg structures to perform various SCTP functions including 431 specifying options for sending each user message. Those options, 432 depending on whether sending or receiving, include stream number, 433 stream sequence number, various flags, context and payload protocol 434 Id, etc. 436 When sending user data with sendmsg(), the msg_name field in msghdr 437 structure will be filled with one of the transport addresses of the 438 intended receiver. If there is no association existing between the 439 sender and the intended receiver, the sender's SCTP stack will set up 440 a new association and then send the user data (see Section 3.2 for 441 more on implicit association setup). 443 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 444 be delivered if that notification has been enabled, and no more data 445 can be sent to that association. Any attempt to send more data will 446 cause sendmsg() to return with an ESHUTDOWN error. Note that the 447 socket is still open for reading at this point so it is possible to 448 retrieve notifications. 450 When receiving a user message with recvmsg(), the msg_name field in 451 msghdr structure will be populated with the source transport address 452 of the user data. The caller of recvmsg() can use this address 453 information to determine to which association the received user 454 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 455 applications must use the peer transport address provided in the 456 msg_name field by recvmsg() to perform correlation to an association, 457 since they will not have the association ID. 459 If all data in a single message has been delivered, MSG_EOR will be 460 set in the msg_flags field of the msghdr structure (see section 461 Section 5.1). 463 If the application does not provide enough buffer space to completely 464 receive a data message, MSG_EOR will not be set in msg_flags. 466 Successive reads will consume more of the same message until the 467 entire message has been delivered, and MSG_EOR will be set. 469 If the SCTP stack is running low on buffers, it may partially deliver 470 a message. In this case, MSG_EOR will not be set, and more calls to 471 recvmsg() will be necessary to completely consume the message. Only 472 one message at a time can be partially delivered in any stream. The 473 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 474 what interlacing of messages occurs for both the one-to-one and the 475 one-to-many model sockets. Please consult Section 7.1.24 for further 476 details on message delivery options. 478 Note, if the socket is a branched-off socket that only represents one 479 association (see Section 3.1), the msg_name field can be used to 480 override the primary address when sending data. 482 3.1.5. close() - one-to-many style socket 484 Applications use close() to perform graceful shutdown (as described 485 in Section 10.1 of RFC2960 [RFC2960]) on ALL the associations 486 currently represented by a one-to-many style socket. 488 The syntax is: 490 ret = close(int sd); 492 sd - the socket descriptor of the associations to be closed. 494 To gracefully shutdown a specific association represented by the one- 495 to-many style socket, an application should use the sendmsg() call, 496 and including the SCTP_EOF flag. A user may optionally terminate an 497 association non-gracefully by sending with the SCTP_ABORT flag and 498 possibly passing a user specified abort code in the data field. Both 499 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 500 Section 5.2.2) in the sendmsg call. 502 If sd in the close() call is a branched-off socket representing only 503 one association, the shutdown is performed on that association only. 505 3.1.6. connect() - one-to-many style socket 507 An application may use the connect() call in the one-to-many style to 508 initiate an association without sending data. 510 The syntax is: 512 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 514 sd - the socket descriptor to have a new association added to. 515 nam - the address structure (either struct sockaddr_in or struct 516 sockaddr_in6 defined in RFC2553 [RFC2553]). 517 len - the size of the address. 518 Multiple connect() calls can be made on the same socket to create 519 multiple associations. This is different from the semantics of 520 connect() on a UDP socket. 522 3.2. Implicit Association Setup 524 Once the bind() call is complete on a one-to-many style socket, the 525 application can begin sending and receiving data using the sendmsg()/ 526 recvmsg() or sendto()/recvfrom() calls, without going through any 527 explicit association setup procedures (i.e., no connect() calls 528 required). 530 Whenever sendmsg() or sendto() is called and the SCTP stack at the 531 sender finds that there is no association existing between the sender 532 and the intended receiver (identified by the address passed either in 533 the msg_name field of msghdr structure in the sendmsg() call or the 534 dest_addr field in the sendto() call), the SCTP stack will 535 automatically setup an association to the intended receiver. 537 Upon the successful association setup a SCTP_COMM_UP notification 538 will be dispatched to the socket at both the sender and receiver 539 side. This notification can be read by the recvmsg() system call 540 (see Section 3.1.3). 542 Note, if the SCTP stack at the sender side supports bundling, the 543 first user message may be bundled with the COOKIE ECHO message 544 RFC2960 [RFC2960]. 546 When the SCTP stack sets up a new association implicitly, it first 547 consults the sctp_initmsg structure, which is passed along within the 548 ancillary data in the sendmsg() call (see Section 5.2.1 for details 549 of the data structures), for any special options to be used on the 550 new association. 552 If this information is not present in the sendmsg() call, or if the 553 implicit association setup is triggered by a sendto() call, the 554 default association initialization parameters will be used. These 555 default association parameters may be set with respective 556 setsockopt() calls or be left to the system defaults. 558 Implicit association setup cannot be initiated by send()/recv() 559 calls. 561 3.3. Non-blocking mode 563 Some SCTP users might want to avoid blocking when they call socket 564 interface function. 566 Once all bind() calls are complete on a one-to-many style socket, the 567 application must set the non-blocking option by a fcntl() (such as 568 O_NONBLOCK). After which the sendmsg() function returns immediately, 569 and the success or failure of the data message (and possible 570 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 571 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 572 be sent (due to a CANT_START_ASSOC), the sender will also receive a 573 SCTP_SEND_FAILED event. Those event(s) can be received by the user 574 calling of recvmsg(). A server (having called listen()) is also 575 notified of an association up event by the reception of a 576 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 577 possibly the reception of the first data message. 579 In order to shutdown the association gracefully, the user must call 580 sendmsg() with no data and with the SCTP_EOF flag set. The function 581 returns immediately, and completion of the graceful shutdown is 582 indicated by an SCTP_ASSOC_CHANGE notification of type 583 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be 584 done using the sctp_send() call described in Section 8.10. 586 An application is recommended to use caution when using select() (or 587 poll()) for writing on a one-to-many style socket. The reason being 588 that interpretation of select on write is implementation specific. 589 Generally a positive return on a select on write would only indicate 590 that one of the associations represented by the one-to-many socket is 591 writable. An application that writes after the select return may 592 still block since the association that was writeable is not the 593 destination association of the write call. Likewise select (or 594 poll()) for reading from a one-to-many socket will only return an 595 indication that one of the associations represented by the socket has 596 data to be read. 598 An application that wishes to know that a particular association is 599 ready for reading or writing should either use the one-to-one style 600 or use the sctp_peeloff() (see Section 8.2) function to separate the 601 association of interest from the one-to-many socket. 603 3.4. Special considerations 605 The fact that a one-to-many style socket can provide access to many 606 SCTP associations through a single socket descriptor has important 607 implications for both application programmers and system programmers 608 implementing this API. A key issue is how buffer space inside the 609 sockets layer is managed. Because this implementation detail 610 directly affects how application programmers must write their code to 611 ensure correct operation and portability, this section provides some 612 guidance to both implementors and application programmers. 614 An important feature that SCTP shares with TCP is flow control: 615 specifically, a sender may not send data faster than the receiver can 616 consume it. 618 For TCP, flow control is typically provided for in the sockets API as 619 follows. If the reader stops reading, the sender queues messages in 620 the socket layer until it uses all of its socket buffer space 621 allocation creating a "stalled connection". Further attempts to 622 write to the socket will block or return the error EAGAIN or 623 EWOULDBLOCK for a non-blocking socket. At some point, either the 624 connection is closed, or the receiver begins to read again freeing 625 space in the output queue. 627 For one-to-one style SCTP sockets (this includes sockets descriptors 628 that were separated from a one-to-many style socket with 629 sctp_peeloff()) the behavior is identical. For one-to-many style 630 SCTP sockets, the fact that we have multiple associations on a single 631 socket makes the situation more complicated. If the implementation 632 uses a single buffer space allocation shared by all associations, a 633 single stalled association can prevent the further sending of data on 634 all associations active on a particular one-to-many style socket. 636 For a blocking socket, it should be clear that a single stalled 637 association can block the entire socket. For this reason, 638 application programmers may want to use non-blocking one-to-many 639 style sockets. The application should at least be able to send 640 messages to the non-stalled associations. 642 But a non-blocking socket is not sufficient if the API implementor 643 has chosen a single shared buffer allocation for the socket. A 644 single stalled association would eventually cause the shared 645 allocation to fill, and it would become impossible to send even to 646 non-stalled associations. 648 The API implementor can solve this problem by providing each 649 association with its own allocation of outbound buffer space. Each 650 association should conceptually have as much buffer space as it would 651 have if it had its own socket. As a bonus, this simplifies the 652 implementation of sctp_peeloff(). 654 To ensure that a given stalled association will not prevent other 655 non-stalled associations from being writable, application programmers 656 should either: 658 (a) demand that the underlying implementation dedicates independent 659 buffer space allotments to each association (as suggested above), 660 or 661 (b) verify that their application layer protocol does not permit 662 large amounts of unread data at the receiver (this is true of some 663 request-response protocols, for example), or 664 (c) use one-to-one style sockets for association which may 665 potentially stall (either from the beginning, or by using 666 sctp_peeloff before sending large amounts of data that may cause a 667 stalled condition). 668 An implementation which dedicates independent buffer space for 669 each association should define HAVE_SCTP_MULTIBUF to 1. 671 4. one-to-one style Interface 673 The goal of this style is to follow as closely as possible the 674 current practice of using the sockets interface for a connection 675 oriented protocol, such as TCP. This style enables existing 676 applications using connection oriented protocols to be ported to SCTP 677 with very little effort. 679 Note that some new SCTP features and some new SCTP socket options can 680 only be utilized through the use of sendmsg() and recvmsg() calls, 681 see Section 4.1.8. Also note that some socket interfaces may not be 682 able to provide data on the third leg of the association set up with 683 this interface style. 685 4.1. Basic Operation 687 A typical server in one-to-one style uses the following system call 688 sequence to prepare an SCTP endpoint for servicing requests: 690 1. socket() 692 2. bind() 694 3. listen() 696 4. accept() 698 The accept() call blocks until a new association is set up. It 699 returns with a new socket descriptor. The server then uses the new 700 socket descriptor to communicate with the client, using recv() and 701 send() calls to get requests and send back responses. 703 Then it calls 704 5. close() 706 to terminate the association. 708 A typical client uses the following system call sequence to setup an 709 association with a server to request services: 711 1. socket() 713 2. connect() 715 After returning from connect(), the client uses send() and recv() 716 calls to send out requests and receive responses from the server. 718 The client calls 720 3. close() 722 to terminate this association when done. 724 4.1.1. socket() - one-to-one style socket 726 Applications calls socket() to create a socket descriptor to 727 represent an SCTP endpoint. 729 The syntax is: 731 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 733 or, 735 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 737 Here, SOCK_STREAM indicates the creation of a one-to-one style 738 socket. 740 The first form creates an endpoint which can use only IPv4 addresses, 741 while the second form creates an endpoint which can use both IPv6 and 742 IPv4 addresses. 744 4.1.2. bind() - one-to-one style socket 746 Applications use bind() to pass an address to be associated with an 747 SCTP endpoint to the system. bind() allows only either a single 748 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 749 endpoint can be associated with multiple addresses. To do this, 750 sctp_bindx() is introduced in Section 8.1 to help applications do the 751 job of associating multiple addresses. 753 These addresses associated with a socket are the eligible transport 754 addresses for the endpoint to send and receive data. The endpoint 755 will also present these addresses to its peers during the association 756 initialization process, see RFC2960 [RFC2960]. 758 The syntax is: 760 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 762 sd: the socket descriptor returned by socket() call. 763 addr: the address structure (either struct sockaddr_in or struct 764 sockaddr_in6 defined in RFC2553 [RFC2553]). 765 addrlen: the size of the address structure. 767 If sd is an IPv4 socket, the address passed must be an IPv4 address. 768 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 769 either be an IPv4 or an IPv6 address. 771 Applications cannot call bind() multiple times to associate multiple 772 addresses to the endpoint. After the first call to bind(), all 773 subsequent calls will return an error. 775 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 776 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 777 operating system will associate the endpoint with an optimal address 778 set of the available interfaces. 780 If a bind() is not called prior to the connect() call, the system 781 picks an ephemeral port and will choose an address set equivalent to 782 binding with a wildcard address. One of those addresses will be the 783 primary address for the association. This automatically enables the 784 multi-homing capability of SCTP. 786 The completion of this bind() process does not ready the SCTP 787 endpoint to accept inbound SCTP association requests. Until a 788 listen() system call, described below, is performed on the socket, 789 the SCTP endpoint will promptly reject an inbound SCTP INIT request 790 with an SCTP ABORT. 792 4.1.3. listen() - one-to-one style socket 794 Applications use listen() to ready the SCTP endpoint for accepting 795 inbound associations. 797 The syntax is: 799 int listen(int sd, int backlog); 800 sd: the socket descriptor of the SCTP endpoint. 801 backlog: this specifies the max number of outstanding associations 802 allowed in the socket's accept queue. These are the associations 803 that have finished the four-way initiation handshake (see Section 804 5 of RFC2960 [RFC2960]) and are in the ESTABLISHED state. Note, a 805 backlog of '0' indicates that the caller no longer wishes to 806 receive new associations. 808 4.1.4. accept() - one-to-one style socket 810 Applications use accept() call to remove an established SCTP 811 association from the accept queue of the endpoint. A new socket 812 descriptor will be returned from accept() to represent the newly 813 formed association. 815 The syntax is: 817 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 819 new_sd - the socket descriptor for the newly formed association. 820 sd - the listening socket descriptor. 821 addr - on return, will contain the primary address of the peer 822 endpoint. 823 addrlen - on return, will contain the size of addr. 825 4.1.5. connect() - one-to-one style socket 827 Applications use connect() to initiate an association to a peer. 829 The syntax is: 831 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 833 sd - the socket descriptor of the endpoint. 834 addr - the peer's address. 835 addrlen - the size of the address. 837 This operation corresponds to the ASSOCIATE primitive described in 838 section 10.1 of RFC2960 [RFC2960]. 840 By default, the new association created has only one outbound stream. 841 The SCTP_INITMSG option described in Section 7.1.3 should be used 842 before connecting to change the number of outbound streams. 844 If a bind() is not called prior to the connect() call, the system 845 picks an ephemeral port and will choose an address set equivalent to 846 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 847 respectively. One of those addresses will be the primary address for 848 the association. This automatically enables the multi-homing 849 capability of SCTP. 851 Note that SCTP allows data exchange, similar to T/TCP RFC1644 852 [RFC1644], during the association set up phase. If an application 853 wants to do this, it cannot use connect() call. Instead, it should 854 use sendto() or sendmsg() to initiate an association. If it uses 855 sendto() and it wants to change initialization behavior, it needs to 856 use the SCTP_INITMSG socket option before calling sendto(). Or it 857 can use SCTP_INIT type sendmsg() to initiate an association without 858 doing the setsockopt(). Note that some sockets implementations may 859 not support the sending of data to initiate an association with the 860 one-to-one style (implementations that do not support T/TCP normally 861 have this restriction). Implementations which allow sending of data 862 to initiate an association without calling connect() define the 863 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 865 SCTP does not support half close semantics. This means that unlike 866 T/TCP, MSG_EOF should not be set in the flags parameter when calling 867 sendto() or sendmsg() when the call is used to initiate a connection. 868 MSG_EOF is not an acceptable flag with SCTP socket. 870 4.1.6. close() - one-to-one style socket 872 Applications use close() to gracefully close down an association. 874 The syntax is: 876 int close(int sd); 878 sd - the socket descriptor of the association to be closed. 880 After an application calls close() on a socket descriptor, no further 881 socket operations will succeed on that descriptor. 883 4.1.7. shutdown() - one-to-one style socket 885 SCTP differs from TCP in that it does not have half closed semantics. 886 Hence the shutdown() call for SCTP is an approximation of the TCP 887 shutdown() call, and solves some different problems. Full TCP- 888 compatibility is not provided, so developers porting TCP applications 889 to SCTP may need to recode sections that use shutdown(). (Note that 890 it is possible to achieve the same results as half close in SCTP 891 using SCTP streams.) 893 The syntax is: 895 int shutdown(int sd, int how); 897 sd - the socket descriptor of the association to be closed. 898 how - Specifies the type of shutdown. The values are as follows: 899 SHUT_RD - Disables further receive operations. No SCTP protocol 900 action is taken. 901 SHUT_WR - Disables further send operations, and initiates the 902 SCTP shutdown sequence. 903 SHUT_RDWR - Disables further send and receive operations and 904 initiates the SCTP shutdown sequence. 906 The major difference between SCTP and TCP shutdown() is that SCTP 907 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 908 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 909 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 910 the SCTP association while still leaving the socket descriptor open, 911 so that the caller can receive back any data SCTP was unable to 912 deliver (see Section 5.3.1.4 for more information). 914 To perform the ABORT operation described in RFC2960 [RFC2960] section 915 10.1, an application can use the socket option SO_LINGER. It is 916 described in Section 7.1.4. 918 4.1.8. sendmsg() and recvmsg() - one-to-one style socket 920 With a one-to-one style socket, the application can also use 921 sendmsg() and recvmsg() to transmit data to and receive data from its 922 peer. The semantics is similar to those used in the one-to-many 923 style (section Section 3.1.3), with the following differences: 925 1) When sending, the msg_name field in the msghdr is not used to 926 specify the intended receiver, rather it is used to indicate a 927 preferred peer address if the sender wishes to discourage the stack 928 from sending the message to the primary address of the receiver. If 929 the transport address given is not part of the current association, 930 the data will not be sent and a SCTP_SEND_FAILED event will be 931 delivered to the application if send failure events are enabled. 933 4.1.9. getpeername() 935 Applications use getpeername() to retrieve the primary socket address 936 of the peer. This call is for TCP compatibility, and is not multi- 937 homed. It does not work with one-to-many style sockets. See 938 Section 8.3 for a multi-homed/one-to-many style version of the call. 940 The syntax is: 942 int getpeername(int sd, struct sockaddr *address, 943 socklen_t *len); 945 sd - the socket descriptor to be queried. 946 address - On return, the peer primary address is stored in this 947 buffer. If the socket is an IPv4 socket, the address will be 948 IPv4. If the socket is an IPv6 socket, the address will be either 949 an IPv6 or IPv4 address. 950 len - The caller should set the length of address here. On return, 951 this is set to the length of the returned address. 953 If the actual length of the address is greater than the length of the 954 supplied sockaddr structure, the stored address will be truncated. 956 5. Data Structures 958 We discuss in this section important data structures which are 959 specific to SCTP and are used with sendmsg() and recvmsg() calls to 960 control SCTP endpoint operations and to access ancillary information 961 and notifications. 963 5.1. The msghdr and cmsghdr Structures 965 The msghdr structure used in the sendmsg() and recvmsg() calls, as 966 well as the ancillary data carried in the structure, is the key for 967 the application to set and get various control information from the 968 SCTP endpoint. 970 The msghdr and the related cmsghdr structures are defined and 971 discussed in details in RFC2292 [RFC2292]. Here we will cite their 972 definitions from RFC2292 [RFC2292]. 974 The msghdr structure: 976 struct msghdr { 977 void *msg_name; /* ptr to socket address structure */ 978 socklen_t msg_namelen; /* size of socket address structure */ 979 struct iovec *msg_iov; /* scatter/gather array */ 980 size_t msg_iovlen; /* # elements in msg_iov */ 981 void *msg_control; /* ancillary data */ 982 socklen_t msg_controllen; /* ancillary data buffer length */ 983 int msg_flags; /* flags on received message */ 984 }; 986 The cmsghdr structure: 988 struct cmsghdr { 989 socklen_t cmsg_len; /* #bytes, including this header */ 990 int cmsg_level; /* originating protocol */ 991 int cmsg_type; /* protocol-specific type */ 992 /* followed by unsigned char cmsg_data[]; */ 993 }; 995 In the msghdr structure, the usage of msg_name has been discussed in 996 previous sections (see Section 3.1.3 and Section 4.1.8). 998 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 999 field) are treated as a single SCTP data chunk, rather than multiple 1000 chunks, for both sendmsg() and recvmsg(). 1002 The msg_flags are not used when sending a message with sendmsg(). 1004 If a notification has arrived, recvmsg() will return the notification 1005 with the MSG_NOTIFICATION flag set in msg_flags. If the 1006 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1007 Section 5.3 for more information about notifications. 1009 If all portions of a data frame or notification have been read, 1010 recvmsg() will return with MSG_EOR set in msg_flags. 1012 5.2. SCTP msg_control Structures 1014 A key element of all SCTP-specific socket extensions is the use of 1015 ancillary data to specify and access SCTP-specific data via the 1016 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1017 Fine-grained control over initialization and sending parameters are 1018 handled with ancillary data. 1020 Each ancillary data item is proceeded by a struct cmsghdr (see 1021 Section 5.1), which defines the function and purpose of the data 1022 contained in in the cmsg_data[] member. 1024 There are two kinds of ancillary data used by SCTP: initialization 1025 data, and, header information (SNDRCV). Initialization data (one-to- 1026 many style only) sets protocol parameters for new associations. 1027 Section 5.2.1 provides more details. Header information can set or 1028 report parameters on individual messages in a stream. See 1029 Section 5.2.2 for how to use SNDRCV ancillary data. 1031 By default on a one-to-one style socket, SCTP will pass no ancillary 1032 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1033 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1034 be enabled with socket options defined for SCTP; see Section 7.3. 1036 Note that all ancillary types are fixed length; see Section 5.4 for 1037 further discussion on this. These data structures use struct 1038 sockaddr_storage (defined in RFC2553 [RFC2553]) as a portable, fixed 1039 length address format. 1041 Other protocols may also provide ancillary data to the socket layer 1042 consumer. These ancillary data items from other protocols may 1043 intermingle with SCTP data. For example, the IPv6 socket API 1044 definitions (RFC2292 [RFC2292] and RFC2553 [RFC2553]) define a number 1045 of ancillary data items. If a socket API consumer enables delivery 1046 of both SCTP and IPv6 ancillary data, they both may appear in the 1047 same msg_control buffer in any order. An application may thus need 1048 to handle other types of ancillary data besides that passed by SCTP. 1050 The sockets application must provide a buffer large enough to 1051 accommodate all ancillary data provided via recvmsg(). If the buffer 1052 is not large enough, the ancillary data will be truncated and the 1053 msghdr's msg_flags will include MSG_CTRUNC. 1055 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1057 This cmsghdr structure provides information for initializing new SCTP 1058 associations with sendmsg(). The SCTP_INITMSG socket option uses 1059 this same data structure. This structure is not used for recvmsg(). 1061 cmsg_level cmsg_type cmsg_data[] 1062 ------------ ------------ ---------------------- 1063 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1065 Here is the definition of the sctp_initmsg structure: 1067 struct sctp_initmsg { 1068 uint16_t sinit_num_ostreams; 1069 uint16_t sinit_max_instreams; 1070 uint16_t sinit_max_attempts; 1071 uint16_t sinit_max_init_timeo; 1072 }; 1074 sinit_num_ostreams: 16 bits (unsigned integer) 1076 This is an integer number representing the number of streams that the 1077 application wishes to be able to send to. This number is confirmed 1078 in the SCTP_COMM_UP notification and must be verified since it is a 1079 negotiated number with the remote endpoint. The default value of 0 1080 indicates to use the endpoint default value. 1082 sinit_max_instreams: 16 bits (unsigned integer) 1083 This value represents the maximum number of inbound streams the 1084 application is prepared to support. This value is bounded by the 1085 actual implementation. In other words the user MAY be able to 1086 support more streams than the Operating System. In such a case, the 1087 Operating System limit overrides the value requested by the user. 1088 The default value of 0 indicates to use the endpoints default value. 1090 sinit_max_attempts: 16 bits (unsigned integer) 1092 This integer specifies how many attempts the SCTP endpoint should 1093 make at resending the INIT. This value overrides the system SCTP 1094 'Max.Init.Retransmits' value. The default value of 0 indicates to 1095 use the endpoints default value. This is normally set to the 1096 system's default 'Max.Init.Retransmit' value. 1098 sinit_max_init_timeo: 16 bits (unsigned integer) 1100 This value represents the largest Time-Out or RTO value (in 1101 milliseconds) to use in attempting an INIT. Normally the 'RTO.Max' 1102 is used to limit the doubling of the RTO upon timeout. For the INIT 1103 message this value MAY override 'RTO.Max'. This value MUST NOT 1104 influence 'RTO.Max' during data transmission and is only used to 1105 bound the initial setup time. A default value of 0 indicates to use 1106 the endpoints default value. This is normally set to the system's 1107 'RTO.Max' value (60 seconds). 1109 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1111 This cmsghdr structure specifies SCTP options for sendmsg() and 1112 describes SCTP header information about a received message through 1113 recvmsg(). 1115 cmsg_level cmsg_type cmsg_data[] 1116 ------------ ------------ ---------------------- 1117 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1119 Here is the definition of sctp_sndrcvinfo: 1121 struct sctp_sndrcvinfo { 1122 uint16_t sinfo_stream; 1123 uint16_t sinfo_ssn; 1124 uint16_t sinfo_flags; 1125 uint32_t sinfo_ppid; 1126 uint32_t sinfo_context; 1127 uint32_t sinfo_timetolive; 1128 uint32_t sinfo_tsn; 1129 uint32_t sinfo_cumtsn; 1130 sctp_assoc_t sinfo_assoc_id; 1132 }; 1134 sinfo_stream: 16 bits (unsigned integer) 1136 For recvmsg() the SCTP stack places the message's stream number in 1137 this value. For sendmsg() this value holds the stream number that 1138 the application wishes to send this message to. If a sender 1139 specifies an invalid stream number an error indication is returned 1140 and the call fails. 1142 sinfo_ssn: 16 bits (unsigned integer) 1144 For recvmsg() this value contains the stream sequence number that the 1145 remote endpoint placed in the DATA chunk. For fragmented messages 1146 this is the same number for all deliveries of the message (if more 1147 than one recvmsg() is needed to read the message). The sendmsg() 1148 call will ignore this parameter. 1150 sinfo_ppid: 32 bits (unsigned integer) 1152 This value in sendmsg() is an unsigned integer that is passed to the 1153 remote end in each user message. In recvmsg() this value is the same 1154 information that was passed by the upper layer in the peer 1155 application. Please note that the SCTP stack performs no byte order 1156 modification of this field. For example, if the DATA chunk has to 1157 contain a given value in network byte order, the SCTP user has to 1158 perform the htonl() computation. 1160 sinfo_context: 32 bits (unsigned integer) 1162 This value is an opaque 32 bit context datum that is used in the 1163 sendmsg() function. This value is passed back to the upper layer if 1164 a error occurs on the send of a message and is retrieved with each 1165 undelivered message (Note: if a endpoint has done multiple sends, all 1166 of which fail, multiple different sinfo_context values will be 1167 returned. One with each user data message). 1169 sinfo_flags: 16 bits (unsigned integer) 1171 This field may contain any of the following flags and is composed of 1172 a bitwise OR of these values. 1174 recvmsg() flags: 1176 SCTP_UNORDERED - This flag is present when the message was sent non- 1177 ordered. 1179 sendmsg() flags: 1180 SCTP_UNORDERED - This flag requests the un-ordered delivery of the 1181 message. If this flag is clear the datagram is considered an 1182 ordered send. 1184 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the 1185 SCTP stack to override the primary destination address with the 1186 address found with the sendto/sendmsg call. 1188 SCTP_ABORT - Setting this flag causes the specified association to 1189 abort by sending an ABORT message to the peer (one-to-many style 1190 only). The ABORT chunk will contain an error cause 'User 1191 Initiated Abort' with cause code 12. The cause specific 1192 information of this error cause is provided in msg_iov. 1194 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown 1195 procedures on the specified association. Graceful shutdown 1196 assures that all data enqueued by both endpoints is successfully 1197 transmitted before closing the association (one-to-many style 1198 only). 1200 SCTP_SENDALL - This flag, if set, will cause a one-to-many model 1201 socket to send the message to all associations that are currently 1202 established on this socket. For the one-to-one socket, this flag 1203 has no effect. 1205 sinfo_timetolive: 32 bit (unsigned integer) 1207 For the sending side, this field contains the message time to live in 1208 milliseconds. The sending side will expire the message within the 1209 specified time period if the message as not been sent to the peer 1210 within this time period. This value will override any default value 1211 set using any socket option. Also note that the value of 0 is 1212 special in that it indicates no timeout should occur on this message. 1214 sinfo_tsn: 32 bit (unsigned integer) 1216 For the receiving side, this field holds a TSN that was assigned to 1217 one of the SCTP Data Chunks. 1219 sinfo_cumtsn: 32 bit (unsigned integer) 1221 This field will hold the current cumulative TSN as known by the 1222 underlying SCTP layer. Note this field is ignored when sending and 1223 only valid for a receive operation when sinfo_flags are set to 1224 SCTP_UNORDERED. 1226 sinfo_assoc_id: sizeof (sctp_assoc_t) 1228 The association handle field, sinfo_assoc_id, holds the identifier 1229 for the association announced in the SCTP_COMM_UP notification. All 1230 notifications for a given association have the same identifier. 1231 Ignored for one-to-one style sockets. 1233 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1235 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1237 This cmsghdr structure specifies SCTP options for SCTP header 1238 information about a received message via recvmsg(). Note that this 1239 structure is an extended version of SCTP_SNDRCV (see Section 5.2.2) 1240 and will only be received if the user has set the socket option 1241 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1242 needed to receive ancillary data. Note that next message data is not 1243 valid unless the current message is completely read, i.e. the MSG_EOR 1244 is set, in other words if you have more data to read from the current 1245 message then no next message information will be available. 1247 cmsg_level cmsg_type cmsg_data[] 1248 ------------ ------------ ---------------------- 1249 IPPROTO_SCTP SCTP_EXTRCV struct sctp_extrcvinfo 1251 Here is the definition of sctp_extrcvinfo 1253 struct sctp_extrcvinfo { 1254 struct sctp_sndrcvinfo serinfo_sinfo; 1255 uint16_t serinfo_next_flags; 1256 uint16_t serinfo_next_stream; 1257 uint32_t serinfo_next_aid; 1258 uint32_t serinfo_next_length; 1259 uint32_t serinfo_next_ppid; 1260 }; 1262 serinfo_sinfo: structure 1264 Please see Section 5.2.2 for the details for this structure. 1266 serinfo_next_flags: 16 bit (unsigned integer) 1268 This bitmask will hold one or more of the following values: 1270 SCTP_NEXT_MSG_AVAIL - This bit, when set to 1, indicates that next 1271 message information is available i.e.: next_stream, next_asocid, 1272 next_length and next_ppid fields all have valid values. If this 1273 bit is set to 0, then these fields are not valid and should be 1274 ignored. 1276 SCTP_NEXT_MSG_ISCOMPLETE - This bit, when set, indicates that the 1277 next message is completely in the receive buffer. The next_length 1278 field thus contains the entire message size. If this flag is set 1279 to 0, then the next_length field only contains part of the message 1280 size since the message is still being received (it is being 1281 partially delivered). 1283 SCTP_NEXT_MSG_IS_UNORDERED - This bit, when set, indicates that the 1284 next message to be received was sent by the peer as unordered. If 1285 this bit is not set (i.e the bit is 0) the next message to be read 1286 is an ordered message in the stream specified. 1287 SCTP_NEXT_MSG_IS_NOTIFICATION - This bit, when set, indicates that 1288 the next message to be received is not a message from the peer, 1289 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1291 serinfo_next_stream: 16 bit (unsigned integer) 1293 This value, when valid (see sreinfo_next_flags), contains the next 1294 stream number that will be received on a subsequent call to one of 1295 the receive message functions. 1297 serinfo_next_aid: 32 bit (unsigned integer) 1299 This value, when valid (see next_flags), contains the next 1300 association identification that will be received on a subsequent call 1301 to one of the receive message functions. 1303 sreinfo_next_length: 32 bit (unsigned integer) 1305 This value, when valid (see sreinfo_next_flags), contains the length 1306 of the next message that will be received on a subsequent call to one 1307 of the receive message functions. Note that this length may be a 1308 partial length depending on the settings of next_flags. 1310 sreinfo_next_ppid: 32 bit (unsigned integer) 1312 This value, when valid (see sreinfo_next_flags), contains the ppid of 1313 the next message that will be received on a subsequent call to one of 1314 the receive message functions. 1316 5.3. SCTP Events and Notifications 1318 An SCTP application may need to understand and process events and 1319 errors that happen on the SCTP stack. These events include network 1320 status changes, association startups, remote operational errors and 1321 undeliverable messages. All of these can be essential for the 1322 application. 1324 When an SCTP application layer does a recvmsg() the message read is 1325 normally a data message from a peer endpoint. If the application 1326 wishes to have the SCTP stack deliver notifications of non-data 1327 events, it sets the appropriate socket option for the notifications 1328 it wants. See Section 7.3 for these socket options. When a 1329 notification arrives, recvmsg() returns the notification in the 1330 application-supplied data buffer via msg_iov, and sets 1331 MSG_NOTIFICATION in msg_flags. 1333 This section details the notification structures. Every notification 1334 structure carries some common fields which provides general 1335 information. 1337 A recvmsg() call will return only one notification at a time. Just 1338 as when reading normal data, it may return part of a notification if 1339 the msg_iov buffer is not large enough. If a single read is not 1340 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1341 reading the notification before subsequent data can arrive. 1343 5.3.1. SCTP Notification Structure 1345 The notification structure is defined as the union of all 1346 notification types. 1348 union sctp_notification { 1349 struct { 1350 uint16_t sn_type; /* Notification type. */ 1351 uint16_t sn_flags; 1352 uint32_t sn_length; 1353 } sn_header; 1354 struct sctp_assoc_change sn_assoc_change; 1355 struct sctp_paddr_change sn_paddr_change; 1356 struct sctp_remote_error sn_remote_error; 1357 struct sctp_send_failed sn_send_failed; 1358 struct sctp_shutdown_event sn_shutdown_event; 1359 struct sctp_adaptation_event sn_adaptation_event; 1360 struct sctp_pdapi_event sn_pdapi_event; 1361 struct sctp_authkey_event sn_auth_event; 1362 }; 1364 sn_type: 16 bits (unsigned integer) 1366 The following list describes the SCTP notification and event types 1367 for the field sn_type. 1369 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1370 been opened or closed. Refer to Section 5.3.1.1 for details. 1371 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1372 part of an existing association has experienced a change of state 1373 (e.g. a failure or return to service of the reachability of a 1374 endpoint via a specific transport address). Please see 1375 Section 5.3.1.2 for data structure details. 1376 SCTP_REMOTE_ERROR: The attached error message is an Operational 1377 Error received from the remote peer. It includes the complete TLV 1378 sent by the remote endpoint. See Section 5.3.1.3 for the detailed 1379 format. 1380 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1381 remote endpoint. This structure includes the original 1382 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1383 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1384 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1385 should be sent on this socket. 1386 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1387 indicated adaptation layer. Please see Section 5.3.1.6. 1388 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1389 receiver that the partial delivery has been aborted. This may 1390 indicate the association is about to be aborted. Please see 1391 Section 5.3.1.7 1392 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1393 receiver that either an error occurred on authentication, or a new 1394 key was made active. Section 5.3.1.8 1396 All standard values for sn_type are greater than 2^15. Values from 1397 2^15 and down are reserved. 1399 sn_flags: 16 bits (unsigned integer) 1401 These are notification-specific flags. 1403 sn_length: 32 bits (unsigned integer) 1405 This is the length of the whole sctp_notification structure including 1406 the sn_type, sn_flags, and sn_length fields. 1408 5.3.1.1. SCTP_ASSOC_CHANGE 1410 Communication notifications inform the ULP that an SCTP association 1411 has either begun or ended. The identifier for a new association is 1412 provided by this notification. The notification information has the 1413 following format: 1415 struct sctp_assoc_change { 1416 uint16_t sac_type; 1417 uint16_t sac_flags; 1418 uint32_t sac_length; 1419 uint16_t sac_state; 1420 uint16_t sac_error; 1421 uint16_t sac_outbound_streams; 1422 uint16_t sac_inbound_streams; 1423 sctp_assoc_t sac_assoc_id; 1424 uint8_t sac_info[0]; 1425 }; 1427 sac_type: 1429 It should be SCTP_ASSOC_CHANGE. 1431 sac_flags: 16 bits (unsigned integer) 1433 Currently unused. 1435 sac_length: 32 bits (unsigned integer) 1437 This field is the total length of the notification data, including 1438 the notification header. 1440 sac_state: 16 bits (signed integer) 1442 This field holds one of a number of values that communicate the event 1443 that happened to the association. They include: 1445 Event Name Description 1447 ---------------- --------------- 1449 SCTP_COMM_UP - A new association is now ready and data may be 1450 exchanged with this peer. 1451 SCTP_COMM_LOST - The association has failed. The association is now 1452 in the closed state. If SEND FAILED notifications are turned on, 1453 a SCTP_COMM_LOST is followed by a series of SCTP_SEND_FAILED 1454 events, one for each outstanding message. 1455 SCTP_RESTART - SCTP has detected that the peer has restarted. 1457 SCTP_SHUTDOWN_COMP - The association has gracefully closed. 1458 SCTP_CANT_STR_ASSOC - The association failed to setup. If non 1459 blocking mode is set and data was sent (in the udp mode), a 1460 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED 1461 events, one for each outstanding message. 1463 sac_error: 16 bits (signed integer) 1465 If the state was reached due to a error condition (e.g. 1466 SCTP_COMM_LOST) any relevant error information is available in this 1467 field. This corresponds to the protocol error codes defined in 1468 RFC2960 [RFC2960]. 1470 sac_outbound_streams: 16 bits (unsigned integer) 1472 sac_inbound_streams: 16 bits (unsigned integer) 1474 The maximum number of streams allowed in each direction are available 1475 in sac_outbound_streams and sac_inbound streams. 1477 sac_assoc_id: sizeof (sctp_assoc_t) 1479 The association id field, holds the identifier for the association. 1480 All notifications for a given association have the same association 1481 identifier. For one-to-one style socket, this field is ignored. 1483 sac_info: variable 1485 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1486 for this association, sac_info[] contains the complete ABORT chunk as 1487 defined in the SCTP specification RFC2960 [RFC2960] section 3.3.7. 1489 5.3.1.2. SCTP_PEER_ADDR_CHANGE 1491 When a destination address on a multi-homed peer encounters a change 1492 an interface details event is sent. The information has the 1493 following structure: 1495 struct sctp_paddr_change { 1496 uint16_t spc_type; 1497 uint16_t spc_flags; 1498 uint32_t spc_length; 1499 struct sockaddr_storage spc_aaddr; 1500 uint32_t spc_state; 1501 uint32_t spc_error; 1502 sctp_assoc_t spc_assoc_id; 1503 } 1505 spc_type: 1507 It should be SCTP_PEER_ADDR_CHANGE. 1509 spc_flags: 16 bits (unsigned integer) 1511 Currently unused. 1513 spc_length: 32 bits (unsigned integer) 1515 This field is the total length of the notification data, including 1516 the notification header. 1518 spc_aaddr: sizeof (struct sockaddr_storage) 1520 The affected address field, holds the remote peer's address that is 1521 encountering the change of state. 1523 spc_state: 32 bits (signed integer) 1525 This field holds one of a number of values that communicate the event 1526 that happened to the address. They include: 1528 Event Name Description 1530 ---------------- --------------- 1532 SCTP_ADDR_AVAILABLE - This address is now reachable. 1533 SCTP_ADDR_UNREACHABLE - The address specified can no longer be 1534 reached. Any data sent to this address is rerouted to an 1535 alternate until this address becomes reachable. 1536 SCTP_ADDR_REMOVED - The address is no longer part of the 1537 association. 1538 SCTP_ADDR_ADDED - The address is now part of the association. 1539 SCTP_ADDR_MADE_PRIM - This address has now been made to be the 1540 primary destination address. 1541 SCTP_ADDR_CONFIRMED - This address has now been confirmed as a valid 1542 address. 1544 spc_error: 32 bits (signed integer) 1546 If the state was reached due to any error condition (e.g. 1547 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1548 this field. 1550 spc_assoc_id: sizeof (sctp_assoc_t) 1552 The association id field, holds the identifier for the association. 1554 All notifications for a given association have the same association 1555 identifier. For one-to-one style socket, this field is ignored. 1557 5.3.1.3. SCTP_REMOTE_ERROR 1559 A remote peer may send an Operational Error message to its peer. 1560 This message indicates a variety of error conditions on an 1561 association. The entire ERROR chunk as it appears on the wire is 1562 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1563 specification RFC2960 [RFC2960] and any extensions for a list of 1564 possible error formats. SCTP error notifications have the format: 1566 struct sctp_remote_error { 1567 uint16_t sre_type; 1568 uint16_t sre_flags; 1569 uint32_t sre_length; 1570 uint16_t sre_error; 1571 sctp_assoc_t sre_assoc_id; 1572 uint8_t sre_data[0]; 1573 }; 1575 sre_type: 1577 It should be SCTP_REMOTE_ERROR. 1579 sre_flags: 16 bits (unsigned integer) 1581 Currently unused. 1583 sre_length: 32 bits (unsigned integer) 1585 This field is the total length of the notification data, including 1586 the notification header and the contents of sre_data. 1588 sre_error: 16 bits (unsigned integer) 1590 This value represents one of the Operational Error causes defined in 1591 the SCTP specification, in network byte order. 1593 sre_assoc_id: sizeof (sctp_assoc_t) 1595 The association id field, holds the identifier for the association. 1596 All notifications for a given association have the same association 1597 identifier. For one-to-one style socket, this field is ignored. 1599 sre_data: variable 1600 This contains the ERROR chunk as defined in the SCTP specification 1601 RFC2960 [RFC2960] section 3.3.10. 1603 5.3.1.4. SCTP_SEND_FAILED 1605 If SCTP cannot deliver a message it may return the message as a 1606 notification. 1608 struct sctp_send_failed { 1609 uint16_t ssf_type; 1610 uint16_t ssf_flags; 1611 uint32_t ssf_length; 1612 uint32_t ssf_error; 1613 struct sctp_sndrcvinfo ssf_info; 1614 sctp_assoc_t ssf_assoc_id; 1615 uint8_t ssf_data[0]; 1616 }; 1618 ssf_type: 1620 It should be SCTP_SEND_FAILED. 1622 ssf_flags: 16 bits (unsigned integer) 1624 The flag value will take one of the following values: 1626 SCTP_DATA_UNSENT - Indicates that the data was never put on the 1627 wire. 1628 SCTP_DATA_SENT - Indicates that the data was put on the wire. Note 1629 that this does not necessarily mean that the data was (or was not) 1630 successfully delivered. 1632 ssf_length: 32 bits (unsigned integer) 1634 This field is the total length of the notification data, including 1635 the notification header and the payload in ssf_data. 1637 ssf_error: 16 bits (unsigned integer) 1639 This value represents the reason why the send failed, and if set, 1640 will be a SCTP protocol error code as defined in RFC2960 [RFC2960] 1641 section 3.3.10. 1643 ssf_info: sizeof (struct sctp_sndrcvinfo) 1645 The original send information associated with the undelivered 1646 message. 1648 ssf_assoc_id: sizeof (sctp_assoc_t) 1650 The association id field, sf_assoc_id, holds the identifier for the 1651 association. All notifications for a given association have the same 1652 association identifier. For one-to-one style socket, this field is 1653 ignored. 1655 ssf_data: variable length 1657 The undelivered message, exactly as delivered by the caller to the 1658 original send*() call. 1660 5.3.1.5. SCTP_SHUTDOWN_EVENT 1662 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1663 inform the application that it should cease sending data. 1665 struct sctp_shutdown_event { 1666 uint16_t sse_type; 1667 uint16_t sse_flags; 1668 uint32_t sse_length; 1669 sctp_assoc_t sse_assoc_id; 1670 }; 1672 sse_type 1674 It should be SCTP_SHUTDOWN_EVENT 1676 sse_flags: 16 bits (unsigned integer) 1678 Currently unused. 1680 sse_length: 32 bits (unsigned integer) 1682 This field is the total length of the notification data, including 1683 the notification header. It will generally be sizeof (struct 1684 sctp_shutdown_event). 1686 sse_flags: 16 bits (unsigned integer) 1688 Currently unused. 1690 sse_assoc_id: sizeof (sctp_assoc_t) 1692 The association id field, holds the identifier for the association. 1693 All notifications for a given association have the same association 1694 identifier. For one-to-one style socket, this field is ignored. 1696 5.3.1.6. SCTP_ADAPTATION_INDICATION 1698 When a peer sends a Adaptation Layer Indication parameter , SCTP 1699 delivers this notification to inform the application that of the 1700 peers requested adaptation layer. 1702 struct sctp_adaptation_event { 1703 uint16_t sai_type; 1704 uint16_t sai_flags; 1705 uint32_t sai_length; 1706 uint32_t sai_adaptation_ind; 1707 sctp_assoc_t sai_assoc_id; 1708 }; 1710 sai_type 1712 It should be SCTP_ADAPTATION_INDICATION 1714 sai_flags: 16 bits (unsigned integer) 1716 Currently unused. 1718 sai_length: 32 bits (unsigned integer) 1720 This field is the total length of the notification data, including 1721 the notification header. It will generally be sizeof (struct 1722 sctp_adaptation_event). 1724 sai_adaptation_ind: 32 bits (unsigned integer) 1726 This field holds the bit array sent by the peer in the adaptation 1727 layer indication parameter. The bits are in network byte order. 1729 sai_assoc_id: sizeof (sctp_assoc_t) 1731 The association id field, holds the identifier for the association. 1732 All notifications for a given association have the same association 1733 identifier. For one-to-one style socket, this field is ignored. 1735 5.3.1.7. SCTP_PARTIAL_DELIVERY_EVENT 1737 When a receiver is engaged in a partial delivery of a message this 1738 notification will be used to indicate various events. 1740 struct sctp_pdapi_event { 1741 uint16_t pdapi_type; 1742 uint16_t pdapi_flags; 1743 uint32_t pdapi_length; 1744 uint32_t pdapi_indication; 1745 uint32_t pdapi_stream; 1746 uint32_t pdapi_seq; 1747 sctp_assoc_t pdapi_assoc_id; 1748 }; 1750 pdapi_type 1752 It should be SCTP_PARTIAL_DELIVERY_EVENT 1754 pdapi_flags: 16 bits (unsigned integer) 1756 Currently unused. 1758 pdapi_length: 32 bits (unsigned integer) 1760 This field is the total length of the notification data, including 1761 the notification header. It will generally be sizeof (struct 1762 sctp_pdapi_event). 1764 pdapi_indication: 32 bits (unsigned integer) 1766 This field holds the indication being sent to the application 1767 possible values include: 1769 SCTP_PARTIAL_DELIVERY_ABORTED 1771 pdapi_stream: 16 bits (unsigned integer) 1773 This field holds the stream on which the partial delivery event 1774 happened. 1776 pdapi_seq: 16 bits (unsigned integer) 1778 This field holds the stream sequence number which was being partially 1779 delivered. 1781 pdapi_assoc_id: sizeof (sctp_assoc_t) 1783 The association id field, holds the identifier for the association. 1784 All notifications for a given association have the same association 1785 identifier. For one-to-one style socket, this field is ignored. 1787 5.3.1.8. SCTP_AUTHENTICATION_EVENT 1789 When a receiver is using authentication this message will provide 1790 notifications regarding new keys being made active as well as errors. 1792 struct sctp_authkey_event { 1793 uint16_t auth_type; 1794 uint16_t auth_flags; 1795 uint32_t auth_length; 1796 uint16_t auth_keynumber; 1797 uint16_t auth_altkeynumber; 1798 uint32_t auth_indication; 1799 sctp_assoc_t auth_assoc_id; 1800 }; 1802 auth_type 1804 It should be SCTP_AUTHENTICATION_EVENT 1806 auth_flags: 16 bits (unsigned integer) 1808 Currently unused. 1810 auth_length: 32 bits (unsigned integer) 1812 This field is the total length of the notification data, including 1813 the notification header. It will generally be sizeof (struct 1814 sctp_authkey_event). 1816 auth_keynumber: 32 bits (unsigned integer) 1818 This field holds the keynumber set by the user for the effected key. 1819 If more than one key is involved, this will contain one of the keys 1820 involved in the notification. 1822 auth_altkeynumber: 32 bits (unsigned integer) 1824 This field holds an alternate keynumber which is used by some 1825 notifications. 1827 auth_indication: 32 bits (unsigned integer) 1829 This field hold the error or indication being reported. The 1830 following values are currently defined: 1832 SCTP_AUTH_NEWKEY - this report indicates that a new key has been 1833 made active (used for the first time by the peer) and is now the 1834 active key. The auth_keynumber field holds the user specified key 1835 number. 1837 auth_assoc_id: sizeof (sctp_assoc_t) 1839 The association id field, holds the identifier for the association. 1840 All notifications for a given association have the same association 1841 identifier. 1843 5.4. Ancillary Data Considerations and Semantics 1845 Programming with ancillary socket data contains some subtleties and 1846 pitfalls, which are discussed below. 1848 5.4.1. Multiple Items and Ordering 1850 Multiple ancillary data items may be included in any call to 1851 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1852 items, or both. 1854 The ordering of ancillary data items (either by SCTP or another 1855 protocol) is not significant and is implementation-dependent, so 1856 applications must not depend on any ordering. 1858 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1859 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1860 sendmsg() or recvmsg() call. 1862 5.4.2. Accessing and Manipulating Ancillary Data 1864 Applications can infer the presence of data or ancillary data by 1865 examining the msg_iovlen and msg_controllen msghdr members, 1866 respectively. 1868 Implementations may have different padding requirements for ancillary 1869 data, so portable applications should make use of the macros 1870 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1871 RFC2292 [RFC2292] and your SCTP implementation's documentation for 1872 more information. Following is an example, from RFC2292 [RFC2292], 1873 demonstrating the use of these macros to access ancillary data: 1875 struct msghdr msg; 1876 struct cmsghdr *cmsgptr; 1878 /* fill in msg */ 1880 /* call recvmsg() */ 1882 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1883 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1884 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1885 u_char *ptr; 1887 ptr = CMSG_DATA(cmsgptr); 1888 /* process data pointed to by ptr */ 1889 } 1890 } 1892 5.4.3. Control Message Buffer Sizing 1894 The information conveyed via SCTP_SNDRCV events will often be 1895 fundamental to the correct and sane operation of the sockets 1896 application. This is particularly true of the one-to-many semantics, 1897 but also of the one-ton-one semantics. For example, if an 1898 application needs to send and receive data on different SCTP streams, 1899 SCTP_SNDRCV events are indispensable. 1901 Given that some ancillary data is critical, and that multiple 1902 ancillary data items may appear in any order, applications should be 1903 carefully written to always provide a large enough buffer to contain 1904 all possible ancillary data that can be presented by recvmsg(). If 1905 the buffer is too small, and crucial data is truncated, it may pose a 1906 fatal error condition. 1908 Thus it is essential that applications be able to deterministically 1909 calculate the maximum required buffer size to pass to recvmsg(). One 1910 constraint imposed on this specification that makes this possible is 1911 that all ancillary data definitions are of a fixed length. One way 1912 to calculate the maximum required buffer size might be to take the 1913 sum the sizes of all enabled ancillary data item structures, as 1914 calculated by CMSG_SPACE. For example, if we enabled 1915 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [RFC2292], we would 1916 calculate and allocate the buffer size as follows: 1918 size_t total; 1919 void *buf; 1921 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1922 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1924 buf = malloc(total); 1926 We could then use this buffer for msg_control on each call to 1927 recvmsg() and be assured that we would not lose any ancillary data to 1928 truncation. 1930 6. Common Operations for Both Styles 1932 6.1. send(), recv(), sendto(), recvfrom() 1934 Applications can use send() and sendto() to transmit data to the peer 1935 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1936 data from the peer. 1938 The syntax is: 1940 ssize_t send(int sd, const void *msg, size_t len, int flags); 1941 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1942 const struct sockaddr *to, socklen_t tolen); 1943 ssize_t recv(int sd, void *buf, size_t len, int flags); 1944 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1945 struct sockaddr *from, socklen_t *fromlen); 1947 sd - the socket descriptor of an SCTP endpoint. 1948 msg - the message to be sent. 1949 len - the size of the message or the size of buffer. 1950 to - one of the peer addresses of the association to be used to send 1951 the message. 1952 tolen - the size of the address. 1953 buf - the buffer to store a received message. 1954 from - the buffer to store the peer address used to send the 1955 received message. 1956 fromlen - the size of the from address 1957 flags - (described below). 1959 These calls give access to only basic SCTP protocol features. If 1960 either peer in the association uses multiple streams, or sends 1961 unordered data these calls will usually be inadequate, and may 1962 deliver the data in unpredictable ways. 1964 SCTP has the concept of multiple streams in one association. The 1965 above calls do not allow the caller to specify on which stream a 1966 message should be sent. The system uses stream 0 as the default 1967 stream for send() and sendto(). recv() and recvfrom() return data 1968 from any stream, but the caller can not distinguish the different 1969 streams. This may result in data seeming to arrive out of order. 1970 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1971 provide no indication. 1973 SCTP is message based. The msg buffer above in send() and sendto() 1974 is considered to be a single message. This means that if the caller 1975 wants to send a message which is composed by several buffers, the 1976 caller needs to combine them before calling send() or sendto(). 1977 Alternately, the caller can use sendmsg() to do that without 1978 combining them. recv() and recvfrom() cannot distinguish message 1979 boundaries. 1981 In receiving, if the buffer supplied is not large enough to hold a 1982 complete message, the receive call acts like a stream socket and 1983 returns as much data as will fit in the buffer. 1985 Note, the send() and recv() calls may not be used for a one-to-many 1986 style socket. 1988 Note, if an application calls a send function with no user data and 1989 no ancillary data the SCTP implementation should reject the request 1990 with an appropriate error message. An implementation is NOT allowed 1991 to send a Data chunk with no user data RFC2960 [RFC2960]. 1993 6.2. setsockopt(), getsockopt() 1995 Applications use setsockopt() and getsockopt() to set or retrieve 1996 socket options. Socket options are used to change the default 1997 behavior of sockets calls. They are described in Section 7 1999 The syntax is: 2001 ret = getsockopt(int sd, int level, int optname, void *optval, 2002 socklen_t *optlen); 2003 ret = setsockopt(int sd, int level, int optname, const void *optval, 2004 socklen_t optlen); 2006 sd - the socket descriptor. 2007 level - set to IPPROTO_SCTP for all SCTP options. 2009 optname - the option name. 2010 optval - the buffer to store the value of the option. 2011 optlen - the size of the buffer (or the length of the option 2012 returned). 2014 All socket options set on a 1-to-1 listening sockets also apply all 2015 accepted sockets. All socket options set on a 1-to-many socket using 2016 the assoc_id 0 applies for all future assocs on the socket. 2018 6.3. read() and write() 2020 Applications can use read() and write() to send and receive data to 2021 and from peer. They have the same semantics as send() and recv() 2022 except that the flags parameter cannot be used. 2024 Note, these calls, when used in the one-to-many style, may only be 2025 used with branched off socket descriptors (see Section 8.2). 2027 6.4. getsockname() 2029 Applications use getsockname() to retrieve the locally-bound socket 2030 address of the specified socket. This is especially useful if the 2031 caller let SCTP chose a local port. This call is for where the 2032 endpoint is not multi-homed. It does not work well with multi-homed 2033 sockets. See Section 8.5 for a multi-homed version of the call. 2035 The syntax is: 2037 int getsockname(int sd, struct sockaddr *address, 2038 socklen_t *len); 2040 sd - the socket descriptor to be queried. 2041 address - On return, one locally bound address (chosen by the SCTP 2042 stack) is stored in this buffer. If the socket is an IPv4 socket, 2043 the address will be IPv4. If the socket is an IPv6 socket, the 2044 address will be either an IPv6 or IPv4 address. 2045 len - The caller should set the length of address here. On return, 2046 this is set to the length of the returned address. 2048 If the actual length of the address is greater than the length of the 2049 supplied sockaddr structure, the stored address will be truncated. 2051 If the socket has not been bound to a local name, the value stored in 2052 the object pointed to by address is unspecified. 2054 7. Socket Options 2056 The following sub-section describes various SCTP level socket options 2057 that are common to both styles. SCTP associations can be multi- 2058 homed. Therefore, certain option parameters include a 2059 sockaddr_storage structure to select which peer address the option 2060 should be applied to. 2062 For the one-to-many style sockets, an sctp_assoc_t structure 2063 (association ID) is used to identify the the association instance 2064 that the operation affects. So it must be set when using this style. 2066 For the one-to-one style sockets and branched off one-to-many style 2067 sockets (see Section 8.2) this association ID parameter is ignored. 2069 Note that socket or IP level options are set or retrieved per socket. 2070 This means that for one-to-many style sockets, those options will be 2071 applied to all associations belonging to the socket. And for one-to- 2072 one style, those options will be applied to all peer addresses of the 2073 association controlled by the socket. Applications should be very 2074 careful in setting those options. 2076 For some IP stacks getsockopt() is read-only; so a new interface will 2077 be needed when information must be passed both in to and out of the 2078 SCTP stack. The syntax for sctp_opt_info() is, 2080 int sctp_opt_info(int sd, 2081 sctp_assoc_t id, 2082 int opt, 2083 void *arg, 2084 socklen_t *size); 2086 The sctp_opt_info() call is a replacement for getsockopt() only and 2087 will not set any options associated with the specified socket. A 2088 setsockopt() must be used to set any writeable option. 2090 For one-to-many style sockets, id specifies the association to query. 2091 For one-to-one style sockets, id is ignored. 2093 opt specifies which SCTP socket option to get. It can get any socket 2094 option currently supported that requests information (either read/ 2095 write options or read only) such as: 2096 SCTP_RTOINFO 2097 SCTP_ASSOCINFO 2098 SCTP_DEFAULT_SEND_PARAM 2099 SCTP_GET_PEER_ADDR_INFO 2100 SCTP_PRIMARY_ADDR 2101 SCTP_PEER_ADDR_PARAMS 2102 SCTP_STATUS 2103 SCTP_CONTEXT 2104 SCTP_AUTH_ACTIVE_KEY 2105 SCTP_PEER_AUTH_CHUNKS 2106 SCTP_LOCAL_AUTH_CHUNKS 2108 arg is an option-specific structure buffer provided by the caller. 2109 See Section 8.5) subsections for more information on these options 2110 and option-specific structures. 2112 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2113 sets errno to the appropriate error code. 2115 All options that support specific settings on an association by 2116 filling in either an association id variable or a sockaddr_storage 2117 SHOULD also support setting of the same value for the entire endpoint 2118 (i.e. future associations). To accomplish this the following logic 2119 is used when setting one of these options: 2121 a) If an address is specified via a sockaddr_storage that is included 2122 in the structure, the address is used to lookup the association 2123 and the settings are applied to the specific address (if 2124 appropriate) or to the entire association. 2125 b) If an association identification is filled in but not a 2126 sockaddr_storage (if present), the association is found using the 2127 association identification and the settings should be applied to 2128 the entire association (since a specific address is not 2129 specified). Note this also applies to options that hold an 2130 association identification in their structure but do not have a 2131 sockaddr_storage field. 2132 c) If neither the sockaddr_storage or association identification is 2133 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2134 the association identification is 0, the settings are a default 2135 and to be applied to the endpoint (all future associations). 2137 7.1. Read / Write Options 2139 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2141 The protocol parameters used to initialize and bound retransmission 2142 timeout (RTO) are tunable. See RFC2960 [RFC2960] for more 2143 information on how these parameters are used in RTO calculation. 2145 The following structure is used to access and modify these 2146 parameters: 2148 struct sctp_rtoinfo { 2149 sctp_assoc_t srto_assoc_id; 2150 uint32_t srto_initial; 2151 uint32_t srto_max; 2152 uint32_t srto_min; 2153 }; 2155 srto_initial - This contains the initial RTO value. 2156 srto_max and srto_min - These contain the maximum and minimum bounds 2157 for all RTOs. 2158 srto_assoc_id - (one-to-many style socket) This is filled in the 2159 application, and identifies the association for this query. If 2160 this parameter is '0' (on a one-to-many style socket), then the 2161 change effects the entire endpoint. 2163 All parameters are time values, in milliseconds. A value of 0, when 2164 modifying the parameters, indicates that the current value should not 2165 be changed. 2167 To access or modify these parameters, the application should call 2168 getsockopt or setsockopt() respectively with the option name 2169 SCTP_RTOINFO. 2171 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2173 This option is used to both examine and set various association and 2174 endpoint parameters. 2176 See RFC2960 [RFC2960] for more information on how this parameter is 2177 used. The sasoc_assoc_id parameter is ignored for one-to-one style 2178 socket. 2180 The following structure is used to access and modify this parameters: 2182 struct sctp_assocparams { 2183 sctp_assoc_t sasoc_assoc_id; 2184 uint16_t sasoc_asocmaxrxt; 2185 uint16_t sasoc_number_peer_destinations; 2186 uint32_t sasoc_peer_rwnd; 2187 uint32_t sasoc_local_rwnd; 2188 uint32_t sasoc_cookie_life; 2189 }; 2190 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2191 to make for the association. 2192 sasoc_number_peer_destinations - This is the number of destination 2193 addresses that the peer has. 2194 sasoc_peer_rwnd - This holds the current value of the peers rwnd 2195 (reported in the last SACK) minus any outstanding data (i.e. data 2196 inflight). 2197 sasoc_local_rwnd - This holds the last reported rwnd that was sent 2198 to the peer. 2199 sasoc_cookie_life - This is the associations cookie life value used 2200 when issuing cookies. 2201 sasoc_assoc_id - This is filled in the application, and identifies 2202 the association for this query. 2204 This information may be examined for either the endpoint or a 2205 specific association. To examine a endpoints default parameters the 2206 association id (sasoc_assoc_id) should must be set to the value '0'. 2207 The values of the sasoc_peer_rwnd is meaningless when examining 2208 endpoint information. 2210 All parameters are time values, in milliseconds. A value of 0, when 2211 modifying the parameters, indicates that the current value should not 2212 be changed. 2214 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2215 on either an endpoint or association basis. The rwnd and destination 2216 counts (sasoc_number_peer_destinations, 2217 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2218 placed in these is ignored. 2220 To access or modify these parameters, the application should call 2221 getsockopt or setsockopt() respectively with the option name 2222 SCTP_ASSOCINFO. 2224 The maximum number of retransmissions before an address is considered 2225 unreachable is also tunable, but is address-specific, so it is 2226 covered in a separate option. If an application attempts to set the 2227 value of the association maximum retransmission parameter to more 2228 than the sum of all maximum retransmission parameters, setsockopt() 2229 shall return an error. The reason for this, from RFC2960 [RFC2960] 2230 section 8.2: 2232 Note: When configuring the SCTP endpoint, the user should avoid 2233 having the value of 'Association.Max.Retrans' larger than the 2234 summation of the 'Path.Max.Retrans' of all the destination addresses 2235 for the remote endpoint. Otherwise, all the destination addresses 2236 may become inactive while the endpoint still considers the peer 2237 endpoint reachable. 2239 7.1.3. Initialization Parameters (SCTP_INITMSG) 2241 Applications can specify protocol parameters for the default 2242 association initialization. The structure used to access and modify 2243 these parameters is defined in Section 5.2.1). The option name 2244 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2246 Setting initialization parameters is effective only on an unconnected 2247 socket (for one-to-many style sockets only future associations are 2248 effected by the change). With one-to-one style sockets, this option 2249 is inherited by sockets derived from a listener socket. 2251 7.1.4. SO_LINGER 2253 An application using the one-to-one style socket can use this option 2254 to perform the SCTP ABORT primitive. The linger option structure is: 2256 struct linger { 2257 int l_onoff; /* option on/off */ 2258 int l_linger; /* linger time */ 2259 }; 2261 To enable the option, set l_onoff to 1. If the l_linger value is set 2262 to 0, calling close() is the same as the ABORT primitive. If the 2263 value is set to a negative value, the setsockopt() call will return 2264 an error. If the value is set to a positive value linger_time, the 2265 close() can be blocked for at most linger_time ms. If the graceful 2266 shutdown phase does not finish during this period, close() will 2267 return but the graceful shutdown phase continues in the system. 2269 Note, this is a socket level option NOT an SCTP level option. So 2270 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2271 setsockopt() call. 2273 7.1.5. SCTP_NODELAY 2275 Turn on/off any Nagle-like algorithm. This means that packets are 2276 generally sent as soon as possible and no unnecessary delays are 2277 introduced, at the cost of more packets in the network. Expects an 2278 integer boolean flag. 2280 7.1.6. SO_RCVBUF 2282 Sets receive buffer size in octets. For SCTP one-to-one style 2283 sockets, this controls the receiver window size. For one-to-many 2284 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2285 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2286 as 1, this controls the receiver window size for each association 2287 bound to the socket descriptor. If the implementation defines 2288 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2289 buffer for the whole socket. The call expects an integer. 2291 7.1.7. SO_SNDBUF 2293 Sets send buffer size. For SCTP one-to-one style sockets, this 2294 controls the amount of data SCTP may have waiting in internal buffers 2295 to be sent. This option therefore bounds the maximum size of data 2296 that can be sent in a single send call. For one-to-many style 2297 sockets, the effect is the same, except that it applies to one or all 2298 associations (see Section 3.4) bound to the socket descriptor used in 2299 the setsockopt() or getsockopt() call. The option applies to each 2300 association's window size separately. The call expects an integer. 2302 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) 2304 This socket option is applicable to the one-to-many style socket 2305 only. When set it will cause associations that are idle for more 2306 than the specified number of seconds to automatically close using the 2307 graceful shutdown procedure. An association being idle is defined as 2308 an association that has NOT sent or received user data. The special 2309 value of '0' indicates that no automatic close of any associations 2310 should be performed, this is the default value. The option expects 2311 an integer defining the number of seconds of idle time before an 2312 association is closed. 2314 An application using this option should enable receiving the 2315 association change notification. This is the only mechanism an 2316 application is informed about the closing of an association. After 2317 an association is closed, the association ID assigned to it can be 2318 reused. An application should be aware of this to avoid the possible 2319 problem of sending data to an incorrect peer end point. 2321 7.1.9. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2323 Requests that the peer mark the enclosed address as the association 2324 primary. The enclosed address must be one of the association's 2325 locally bound addresses. The following structure is used to make a 2326 set primary request: 2328 struct sctp_setpeerprim { 2329 sctp_assoc_t sspp_assoc_id; 2330 struct sockaddr_storage sspp_addr; 2331 }; 2332 sspp_addr - The address to set as primary 2333 sspp_assoc_id - This is filled in by the application, and identifies 2334 the association for this request. 2336 Note that this option really should be considered a write only option 2337 (not a read/write option) since it can NOT be passed to a 2338 getsockopt() call and is only valid when used with setsockopt() if 2339 the implementation supports this feature since this functionality is 2340 optional. Implementations that do not support this functionality 2341 should return EOPNOTSUPP. 2343 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) 2345 Requests that the local SCTP stack use the enclosed peer address as 2346 the association primary. The enclosed address must be one of the 2347 association peer's addresses. The following structure is used to 2348 make a set peer primary request: 2350 struct sctp_setprim { 2351 sctp_assoc_t ssp_assoc_id; 2352 struct sockaddr_storage ssp_addr; 2353 }; 2355 ssp_addr - The address to set as primary 2356 ssp_assoc_id - This is filled in by the application, and identifies 2357 the association for this request. 2359 7.1.11. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2361 Requests that the local endpoint set the specified Adaptation Layer 2362 Indication parameter for all future INIT and INIT-ACK exchanges. 2364 struct sctp_setadaptation { 2365 uint32_t ssb_adaptation_ind; 2366 }; 2368 ssb_adaptation_ind - The adaptation layer indicator that will be 2369 included in any outgoing Adaptation Layer Indication parameter. 2371 7.1.12. Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2373 This option is a on/off flag and is passed an integer where a non- 2374 zero is on and a zero is off. If enabled no SCTP message 2375 fragmentation will be performed. Instead if a message being sent 2376 exceeds the current PMTU size, the message will NOT be sent and 2377 instead a error will be indicated to the user. 2379 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2381 Applications can enable or disable heartbeats for any peer address of 2382 an association, modify an address's heartbeat interval, force a 2383 heartbeat to be sent immediately, and adjust the address's maximum 2384 number of retransmissions sent before an address is considered 2385 unreachable. The following structure is used to access and modify an 2386 address's parameters: 2388 struct sctp_paddrparams { 2389 sctp_assoc_t spp_assoc_id; 2390 struct sockaddr_storage spp_address; 2391 uint32_t spp_hbinterval; 2392 uint16_t spp_pathmaxrxt; 2393 uint32_t spp_pathmtu; 2394 uint32_t spp_flags; 2395 uint32_t spp_ipv6_flowlabel; 2396 uint8_t spp_ipv4_tos; 2397 }; 2399 spp_assoc_id - (one-to-many style socket) This is filled in the 2400 application, and identifies the association for this query. 2401 spp_address - This specifies which address is of interest. 2402 spp_hbinterval - This contains the value of the heartbeat interval, 2403 in milliseconds. Note that unless the spp_flag is set to 2404 SPP_HB_ENABLE the value of this field is ignored. Note also that 2405 a value of zero indicates the current setting should be left 2406 unchanged. To set an actual value of zero the use of the flag 2407 SPP_HB_TIME_IS_ZERO should be used. 2408 spp_pathmaxrxt - This contains the maximum number of retransmissions 2409 before this address shall be considered unreachable. Note that a 2410 value of zero indicates the current setting should be left 2411 unchanged. 2412 spp_pathmtu - When Path MTU discovery is disabled the value 2413 specified here will be the "fixed" path mtu (i.e. the value of the 2414 spp_flags field must include the flag SPP_PMTUD_DISABLE for this 2415 field to have any effect). Note that if the spp_address field is 2416 empty then all destinations for this association will have this 2417 fixed path mtu set upon them. If an address is specified, then 2418 only that address will be effected. Note also that this option 2419 cannot be set on the endpoint, but must be set on each individual 2420 association. Also, when disabling PMTU discovery, the 2421 implementation may disallow this behavior if the "fixed" path mtu 2422 is below the constant value SCTP_SMALLEST_PMTU. 2424 spp_ipv6_flowlabel- This field is used in conjunction with the 2425 SPP_IPV6_FLOWLABEL flag. 2426 spp_ipv4_tos- This field is used in conjunction with the 2427 SPP_IPV4_TOS flag. 2428 spp_flags- These flags are used to control various features on an 2429 association. The flag field is a bit mask which may contain zero 2430 or more of the following options: 2431 SPP_HB_ENABLE - Enable heartbeats on the specified address. Note 2432 that if the address field is empty all addresses for the 2433 association have heartbeats enabled upon them. 2434 SPP_HB_DISABLE - Disable heartbeats on the specified address. 2435 Note that if the address field is empty all addresses for the 2436 association will have their heartbeats disabled. Note also 2437 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2438 only one of these two should be specified. Enabling both 2439 fields will have undetermined results. 2440 SPP_HB_DEMAND - Request a user initiated heartbeat to be made 2441 immediately. 2442 SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay 2443 is to be set to the value of 0 milliseconds. 2444 SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the 2445 specified address. Note that if the address field is empty 2446 then all addresses on the association are effected. 2447 SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon 2448 the specified address. Note that if the address field is empty 2449 then all addresses on the association are effected. Not also 2450 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2451 exclusive. Enabling both will have undetermined results. 2452 SPP_IPV6_FLOWLABEL - Setting this flag enables setting of the 2453 IPV6 flowlabel value associated with either the association or 2454 the specific address. If the address field is filled in, then 2455 the specific destination address has this value set upon it. 2456 If the association is specified, but not the address, then the 2457 flowlabel value is set for any future destination addresses 2458 that may be added. The value is obtained in the 2459 spp_ipv6_flowlabel field. 2461 Upon retrieval, this flag will be set to indicate that the 2462 spp_ipv6_flowlabel field has a valid value returned. If a 2463 specific destination addresses is set (in the spp_address 2464 field) when called then the value returned is that of the 2465 address. If just an association is specified (and no address) 2466 then the association default flowlabel is returned. If neither 2467 an association nor an destination is specified, then the 2468 sockets default flowlabel is returned. For non IPv6 sockets, 2469 then this flag will be left cleared. 2471 SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos 2472 value associated with either the association or specific 2473 address. If the address field is filled in, then the specific 2474 destination address has this value set upon it. If the 2475 association is specified, but not the address, then the tos 2476 value is set for any future destination addresses that may be 2477 added. The value is obtained in the spp_ipv4_tos field. 2479 Upon retrieval, this flag will be set to indicate that the 2480 spp_ipv4_tos field has a valid value returned. If a specific 2481 destination addresses is set when called (in the spp_address 2482 field) then that specific destination addresses tos value is 2483 returned. If just an association is specified then the 2484 association default tos is returned. If neither an association 2485 nor an destination is specified, then the sockets default tos 2486 is returned. For non IPv4 sockets, then this flag will be left 2487 cleared. 2489 To read or modify these parameters, the application should call 2490 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2492 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2494 Applications that wish to use the sendto() system call may wish to 2495 specify a default set of parameters that would normally be supplied 2496 through the inclusion of ancillary data. This socket option allows 2497 such an application to set the default sctp_sndrcvinfo structure. 2498 The application that wishes to use this socket option simply passes 2499 in to this call the sctp_sndrcvinfo structure defined in 2500 Section 5.2.2) The input parameters accepted by this call include 2501 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2502 sinfo_timetolive. The sinfo_assoc_id field specifies the association 2503 to apply the parameters to in a one-to-many style sockets. It is 2504 ignored on the one-to-one style. Note that setting the 2505 sinfo_assoc_id field to zero indicates that the users wishes to set 2506 the endpoint default send parameters for all future associations. 2508 7.1.15. Set notification and ancillary events (SCTP_EVENTS) 2510 This socket option is used to specify various notifications and 2511 ancillary data the user wishes to receive. Please see Section 7.3) 2512 for a full description of this option and its usage. 2514 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2516 This socket option is a boolean flag which turns on or off mapped V4 2517 addresses. If this option is turned on and the socket is type 2518 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2520 If this option is turned off, then no mapping will be done of V4 2521 addresses and a user will receive both PF_INET6 and PF_INET type 2522 addresses on the socket. 2524 By default this option is turned off and expects an integer to be 2525 passed where non-zero turns on the option and zero turns off the 2526 option. 2528 7.1.17. Get or set the maximum fragmentation size (SCTP_MAXSEG) 2530 This option will get or set the maximum size to put in any outgoing 2531 SCTP DATA chunk. If a message is larger than this size it will be 2532 fragmented by SCTP into the specified size. Note that the underlying 2533 SCTP implementation may fragment into smaller sized chunks when the 2534 PMTU of the underlying association is smaller than the value set by 2535 the user. The default value for this option is '0' which indicates 2536 the user is NOT limiting fragmentation and only the PMTU will effect 2537 SCTP's choice of DATA chunk size. Note also that values set larger 2538 than the maximum size of an IP datagram will effectively let SCTP 2539 control fragmentation (i.e. the same as setting this option to 0). 2541 struct sctp_assoc_value { 2542 sctp_assoc_t assoc_id; 2543 uint32_t assoc_value; 2544 }; 2546 assoc_id - This parameter, indicates which association the user is 2547 performing an action upon. Note that if this field's value is 2548 zero then the endpoints default value is changed (effecting future 2549 associations only). 2550 assoc_value - This parameter specifies the maximum size in bytes. 2552 7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK) 2554 This set option adds a chunk type that the user is requesting to be 2555 received only in an authenticated way. Changes to the list of chunks 2556 will only effect future associations on the socket. 2558 struct sctp_authchunk { 2559 uint8_t sauth_chunk; 2560 }; 2562 sauth_chunks - This parameter contains a chunk type 2563 that the user is requesting to be authenticated. 2565 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 2566 chunks MUST not be used. If they are used an error MUST be returned. 2567 The usage of this option enables SCTP-AUTH in cases where it is not 2568 required by other means (for example the use of ADD-IP). 2570 Note that this option is write-only. Using this option in a 2571 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2573 7.1.19. Get or set the list of supported HMAC Identifiers 2574 (SCTP_HMAC_IDENT) 2576 This option gets or sets the list of HMAC algorithms that the local 2577 endpoint requires the peer to use. 2579 struct sctp_hmacalgo { 2580 uint16_t shmac_idents[]; 2581 }; 2583 shmac_idents - This parameter contains an array of HMAC Identifiers 2584 that the local endpoint is requesting the peer to use, in priority 2585 order. The following identifiers are valid: 2587 1) SCTP_AUTH_HMAC_ID_SHA1 2588 2) SCTP_AUTH_HMAC_ID_SHA256 (optional) 2589 3) SCTP_AUTH_HMAC_ID_SHA224 (optional) 2590 4) SCTP_AUTH_HMAC_ID_SHA384 (optional) 2591 4) SCTP_AUTH_HMAC_ID_SHA512 (optional) 2593 Note that the list supplied must include SHA1 and may include any 2594 of the other values in its preferred order (lowest list postion 2595 has the most preference in algorithm selection). Note also that 2596 the lack of SHA1, or the inclusion of an unknown HMAC identifier 2597 (including optional identifers unknown to the implementation) will 2598 cause the set option to fail and return an error. 2600 7.1.20. Set a shared key (SCTP_AUTH_KEY) 2602 This option will set a shared secret key which is used to build an 2603 association shared key. 2605 struct sctp_authkey { 2606 sctp_assoc_t sca_assoc_id; 2607 uint16_t sca_keynumber; 2608 uint8_t sca_key[]; 2609 }; 2610 sca_assoc_id - This parameter, if non-zero, indicates what 2611 association that the shared key is being set upon. Note that if 2612 this element contains zero, then the shared key is set upon the 2613 endpoint and all future associations will use this key (if not 2614 changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one 2615 sockets, this parameter is ignored. Note, however, that this 2616 option will set a key on the association if the socket is 2617 connected, otherwise this will set a key on the endpoint. 2618 sca_keynumber - this parameter is the shared key identifier by which 2619 the application will refer to this key. If a key of the specified 2620 index already exists, then this new key will replace the old 2621 existing key. Note that shared key identifier '0' defaults to a 2622 null key. 2623 sca_key - This parameter contains an array of bytes that is to be 2624 used by the endpoint (or association) as the shared secret key. 2625 Note, if the length of this field is zero, a null key is set. 2627 Note that this option is write-only. Using this option in a 2628 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2630 7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY) 2632 This option will get or set the active shared key to be used to build 2633 the association shared key. 2635 struct sctp_authkeyid { 2636 sctp_assoc_t scact_assoc_id; 2637 uint16_t scact_keynumber; 2638 }; 2640 scact_assoc_id - This parameter, if non-zero, indicates what 2641 association that the shared key identifier is being set active 2642 upon. Note that if this element contains zero, then the 2643 activation applies to the endpoint and all future associations 2644 will use the specified shared key identifier. For one-to-one 2645 sockets, this parameter is ignored. Note, however, that this 2646 option will set the active key on the association if the socket is 2647 connected, otherwise this will set the default active key for the 2648 endpoint. 2649 scact_keynumber - this parameter is the shared key identifier which 2650 the application is requesting to become the active shared key to 2651 be used for sending authenticated chunks. The key identifier MUST 2652 correspond to an existing shared key. Note that shared key 2653 identifier '0' defaults to a null key. 2655 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) 2657 This set option will delete a shared secret key from use. 2659 struct sctp_authkeyid { 2660 sctp_assoc_t scact_assoc_id; 2661 uint16_t scact_keynumber; 2662 }; 2664 scact_assoc_id - This parameter, if non-zero, indicates what 2665 association that the shared key identifier is being deleted from. 2666 Note that if this element contains zero, then the shared key is 2667 deleted from the endpoint and all associations will no longer use 2668 the specified shared key identifier (unless otherwise set on the 2669 association using SCTP_AUTH_KEY). For one-to-one sockets, this 2670 parameter is ignored. Note, however, that this option will delete 2671 the key from the association if the socket is connected, otherwise 2672 this will delete the key from the endpoint. 2673 scact_keynumber - this parameter is the shared key identifier which 2674 the application is requesting to be deleted. The key identifier 2675 MUST correspond to an existing shared key and MUST NOT be the 2676 current active key. Note if this parameter is zero, use of the 2677 null key identifier '0' is disabled on the endpoint and/or 2678 association. 2680 Note that this option is write-only. Using this option in a 2681 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2683 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_SACK) 2685 This option will effect the way delayed acks are performed. This 2686 option allows you to get or set the delayed ack time, in 2687 milliseconds. It also allows changing the delayed ack frequency. 2688 Changing the frequency to 1 disables the delayed sack algorithm. If 2689 the assoc_id is 0, then this sets or gets the endpoints default 2690 values. If the assoc_id field is non-zero, then the set or get 2691 effects the specified association for the one to many model (the 2692 assoc_id field is ignored by the one to one model). Note that if 2693 sack_delay or sack_freq are 0 when setting this option, then the 2694 current values will remain unchanged. 2696 struct sctp_sack_info { 2697 sctp_assoc_t sack_assoc_id; 2698 uint32_t sack_delay; 2699 uint32_t sack_freq; 2701 }; 2703 sack_assoc_id - This parameter, indicates which association the user 2704 is performing an action upon. Note that if this field's value is 2705 zero then the endpoints default value is changed (effecting future 2706 associations only). 2707 sack_delay - This parameter contains the number of milliseconds that 2708 the user is requesting the delayed ACK timer be set to. Note that 2709 this value is defined in the standard to be between 200 and 500 2710 milliseconds. 2711 sack_freq - This parameter contains the number of packets that must 2712 be received before a sack is sent without waiting for the delay 2713 timer to expire. The default value for this is 2, setting this 2714 value to 1 will disable the delayed sack algorithm. 2716 7.1.24. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE) 2718 Fragmented interleave controls how the presentation of messages 2719 occurs for the message receiver. There are three levels of fragment 2720 interleave defined. Two of the levels effect the one-to-one model, 2721 while the one-to-many model is effected by all three levels. 2723 This option takes an integer value. It can be set to a value of 0, 1 2724 or 2. Attempting to set this level to other values will return an 2725 error. 2727 Setting the three levels provides the following receiver 2728 interactions: 2730 level 0 - Prevents the interleaving of any messages. This means 2731 that when a partial delivery begins, no other messages will be 2732 received except the message being partially delivered. If another 2733 message arrives on a different stream (or association) that could 2734 be delivered, it will be blocked waiting for the user to read all 2735 of the partially delivered message. 2736 level 1 - Allows interleaving of messages that are from different 2737 associations. For the one-to-one model, level 0 and level 1 thus 2738 have the same meaning since a one-to-one socket always receives 2739 messages from the same association. Note that setting the one-to- 2740 many model to this level may cause multiple partial delivers from 2741 different associations but for any given association, only one 2742 message will be delivered until all parts of a message have been 2743 delivered. This means that one large message, being read with an 2744 association identification of "X", will block other messages from 2745 association "X" from being delivered. 2747 level 2 - Allows complete interleaving of messages. This level 2748 requires that the sender carefully observe not only the peer 2749 association identification (or address) but also must pay careful 2750 attention to the stream number. With this option enabled a 2751 partially delivered message may begin being delivered for 2752 association "X" stream "Y" and the next subsequent receive may 2753 return a message from association "X" stream "Z". Note that no 2754 other messages would be delivered for association "X" stream "Y" 2755 until all of stream "Y"'s partially delivered message was read. 2756 Note that this option also effects the one-to-one model. Also 2757 note that for the one-to-many model not only may another streams 2758 message from the same association be delivered from the next 2759 receive, some other associations message may be delivered upon the 2760 next receive. 2762 An implementation should default the one-to-many model to level 1. 2763 The reason for this is that otherwise it is possible that a peer 2764 could begin sending a partial message and thus block all other peers 2765 from sending data. However a setting of level 2 requires the 2766 application to not only be aware of the association (via the 2767 association id or peers address) but also the stream number. The 2768 stream number is NOT present unless the user has subscribed to the 2769 sctp_data_io_events (see Section 7.3). This is also why we recommend 2770 that the one-to-one model be defaulted to level 0 (level 1 for the 2771 one-to-one model has no effect). Note that an implementation should 2772 return an error if a application attempts to set the level to 2 and 2773 has NOT subscribed to the sctp_data_io_events. 2775 7.1.25. Set or Get the sctp partial delivery point 2776 (SCTP_PARTIAL_DELIVERY_POINT) 2778 This option will set or get the SCTP partial delivery point. This 2779 point is the size of a message where the partial delivery API will be 2780 invoked to help free up rwnd space for the peer. Setting this to a 2781 lower value will cause partial deliveries to happen more often. The 2782 calls argument is an integer that sets or gets the partial delivery 2783 point. Note also that the call will fail if the user attempts to set 2784 this value larger than the socket receive buffer size. 2786 Note that any single message having a length smaller than or equal to 2787 the SCTP partial delivery point will be delivered in one single read 2788 call as long as the user provided buffer is large enough to hold the 2789 message. 2791 7.1.26. Set or Get the use of extended receive info 2792 (SCTP_USE_EXT_RCVINFO) 2794 This option will enable or disable the use of the extended version of 2795 the sctp_sndrcvinfo structure. If this option is disabled, then the 2796 normal sctp_sndrcvinfo structure is returned in all receive message 2797 calls. If this option is enabled then the sctp_extrcvinfo structure 2798 is returned in all receive message calls. 2800 Note that the sctp_extrcvinfo structure is never used in any send 2801 call. 2803 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) 2805 This option will enable or disable the use of the automatic 2806 generation of ASCONF chunks to add and delete addresses to an 2807 existing association. Note that this option has two caveats namely: 2808 a) it only effects sockets that are bound to all addresses on the 2809 machine, and b) the system administrator may have an overriding 2810 control that turns the asconf feature off no matter what setting the 2811 socket option may have. 2813 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) 2815 This option will allow a user to change the maximum burst of packets 2816 that can be emitted by this association. Note that the default value 2817 is 4, and some implementations may restrict this setting so that it 2818 can only be lowered. 2820 7.1.29. Set or Get the default context (SCTP_CONTEXT) 2822 The context field in the sctp_sndrcvinfo structure is normally only 2823 used when a failed message is retrieved holding the value that was 2824 sent down on the actual send call. This option allows the setting of 2825 a default context on an association basis that will be received on 2826 reading messages from the peer. This is especially helpful in the 2827 one-2-many model for an application to keep some reference to an 2828 internal state machine that is processing messages on the 2829 association. Note that the setting of this value only effects 2830 received messages from the peer and does not effect the value that is 2831 saved with outbound messages. 2833 To set or get this option the user fills in the following structure: 2835 struct sctp_assoc_value { 2836 sctp_assoc_t assoc_id; 2837 uint32_t assoc_value; 2838 }; 2839 assoc_id - This parameter, indicates which association the user is 2840 performing an action upon. Note that if this field's value is 2841 zero then the endpoints default value is changed (effecting future 2842 associations only). 2843 assoc_value - This parameter contains the context. 2845 7.1.30. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR) 2847 This boolean flag is used to enable or disable explict end of record 2848 (EOR) marking. When this option is enabled, a user may make multiple 2849 send system calls to send a record and must indicate that they are 2850 finished sending a particular record by including on the send the 2851 SCTP_EOR flag. If this boolean flag is disabled then each individual 2852 send system call is considered to have a SCTP_EOR indicator set on it 2853 implicitly without the user having to explicitly add this flag. 2855 7.2. Read-Only Options 2857 7.2.1. Association Status (SCTP_STATUS) 2859 Applications can retrieve current status information about an 2860 association, including association state, peer receiver window size, 2861 number of unacked data chunks, and number of data chunks pending 2862 receipt. This information is read-only. The following structure is 2863 used to access this information: 2865 struct sctp_status { 2866 sctp_assoc_t sstat_assoc_id; 2867 int32_t sstat_state; 2868 uint32_t sstat_rwnd; 2869 uint16_t sstat_unackdata; 2870 uint16_t sstat_penddata; 2871 uint16_t sstat_instrms; 2872 uint16_t sstat_outstrms; 2873 uint32_t sstat_fragmentation_point; 2874 struct sctp_paddrinfo sstat_primary; 2875 }; 2877 sstat_state - This contains the association's current state one of 2878 the following values: 2879 SCTP_CLOSED 2880 SCTP_BOUND 2881 SCTP_LISTEN 2882 SCTP_COOKIE_WAIT 2883 SCTP_COOKIE_ECHOED 2884 SCTP_ESTABLISHED 2885 SCTP_SHUTDOWN_PENDING 2886 SCTP_SHUTDOWN_SENT 2887 SCTP_SHUTDOWN_RECEIVED 2888 SCTP_SHUTDOWN_ACK_SENT 2889 sstat_rwnd - This contains the association peer's current receiver 2890 window size. 2891 sstat_unackdata - This is the number of unacked data chunks. 2892 sstat_penddata - This is the number of data chunks pending receipt. 2893 sstat_primary - This is information on the current primary peer 2894 address. 2895 sstat_assoc_id - (one-to-many style socket) This holds the an 2896 identifier for the association. All notifications for a given 2897 association have the same association identifier. 2898 sstat_instrms - The number of streams that the peer will be using 2899 inbound. 2900 sstat_outstrms - The number of streams that the endpoint is allowed 2901 to use outbound. 2902 sstat_fragmentation_point - The size at which SCTP fragmentation 2903 will occur. 2905 To access these status values, the application calls getsockopt() 2906 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2907 ignored for one-to-one style socket. 2909 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2911 Applications can retrieve information about a specific peer address 2912 of an association, including its reachability state, congestion 2913 window, and retransmission timer values. This information is read- 2914 only. The following structure is used to access this information: 2916 struct sctp_paddrinfo { 2917 sctp_assoc_t spinfo_assoc_id; 2918 struct sockaddr_storage spinfo_address; 2919 int32_t spinfo_state; 2920 uint32_t spinfo_cwnd; 2921 uint32_t spinfo_srtt; 2922 uint32_t spinfo_rto; 2923 uint32_t spinfo_mtu; 2924 }; 2925 spinfo_address - This is filled in the application, and contains the 2926 peer address of interest. 2928 On return from getsockopt(): 2930 spinfo_state - This contains the peer addresses's state (either 2931 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 2932 SCTP_UNCONFIRMED) 2933 spinfo_cwnd - This contains the peer addresses's current congestion 2934 window. 2935 spinfo_srtt - This contains the peer addresses's current smoothed 2936 round-trip time calculation in milliseconds. 2937 spinfo_rto - This contains the peer addresses's current 2938 retransmission timeout value in milliseconds. 2939 spinfo_mtu - The current P-MTU of this address. 2940 spinfo_assoc_id - This is field may be filled in by the application, 2941 if so, this field will have priority in looking up the association 2942 over the address specified in spinfo_address. Note that if the 2943 address does not belong to the association specified then this 2944 call will fail. If the application does NOT fill in the 2945 spinfo_assoc_id, then the address will be used to lookup the 2946 association and on return this field will have the valid 2947 association id. In other words, this call can be used to 2948 translate a address into an association id. 2950 To retrieve this information, use sctp_opt_info() with the 2951 SCTP_GET_PEER_ADDR_INFO options. 2953 7.2.3. Get the list of chunks the peer requires to be authenticated 2954 (SCTP_PEER_AUTH_CHUNKS) 2956 This option gets a list of chunks for a specified association that 2957 the peer requires to be received authenticated only. 2959 struct sctp_authchunks { 2960 sctp_assoc_t gauth_assoc_id; 2961 uint8_t gauth_chunks[]; 2962 }; 2964 gauth_assoc_id - This parameter, indicates which association the 2965 user is requesting the list of peer authenticated chunks. For 2966 one-to-one sockets, this parameter is ignored. 2968 gauth_chunks - This parameter contains an array of chunks that the 2969 peer is requesting to be authenticated. 2971 7.2.4. Get the list of chunks the local endpoint requires to be 2972 authenticated (SCTP_LOCAL_AUTH_CHUNKS) 2974 This option gets a list of chunks for a specified association that 2975 the local endpoint requires to be received authenticated only. 2977 struct sctp_authchunks { 2978 sctp_assoc_t gauth_assoc_id; 2979 uint8_t gauth_chunks[]; 2980 }; 2982 gauth_assoc_id - This parameter, indicates which association the 2983 user is requesting the list of local authenticated chunks. For 2984 one-to-one sockets, this parameter is ignored. 2985 gauth_chunks - This parameter contains an array of chunks that the 2986 local endpoint is requesting to be authenticated. 2988 7.2.5. Get the current number of associations (SCTP_GET_ASSOC_NUMBER) 2990 This option gets the current number of associations that are attached 2991 to a one-to-many style socket. The option value is an uint32_t. 2993 7.2.6. Get the current identifiers of associations 2994 (SCTP_GET_ASSOC_ID_LIST) 2996 This option gets the current list of SCTP association identifiers of 2997 the SCTP associations handled by a one-to-many style socket. The 2998 option value has the structure 3000 struct sctp_assoc_ids { 3001 sctp_assoc_t gaids_assoc_id[0]; 3002 }; 3004 The caller MUST provide a large enough buffer to hold all association 3005 identifiers. If the buffer is too small, an error MUST be returned. 3006 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3007 idea how large the buffer has to be. 3009 7.3. Ancillary Data and Notification Interest Options 3011 Applications can receive per-message ancillary information and 3012 notifications of certain SCTP events with recvmsg(). 3014 The following optional information is available to the application: 3016 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3017 stream number, TSN, SSN, etc. described in Section 5.2.2) 3018 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 3019 Section 5.3.1.1) 3020 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in 3021 Section 5.3.1.2) 3022 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in 3023 Section 5.3.1.4) 3024 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in 3025 Section 5.3.1.3) 3026 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in 3027 Section 5.3.1.5) 3028 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 3029 (described in Section 5.3.1.7) 3030 8. SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): 3031 (described in Section 5.3.1.6) 3032 9. SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event): 3033 (described in Section 5.3.1.8) 3035 To receive any ancillary data or notifications, first the application 3036 registers it's interest by calling the SCTP_EVENTS setsockopt() with 3037 the following structure. 3039 struct sctp_event_subscribe{ 3040 uint8_t sctp_data_io_event; 3041 uint8_t sctp_association_event; 3042 uint8_t sctp_address_event; 3043 uint8_t sctp_send_failure_event; 3044 uint8_t sctp_peer_error_event; 3045 uint8_t sctp_shutdown_event; 3046 uint8_t sctp_partial_delivery_event; 3047 uint8_t sctp_adaptation_layer_event; 3048 uint8_t sctp_authentication_event; 3049 }; 3051 sctp_data_io_event - Setting this flag to 1 will cause the reception 3052 of SCTP_SNDRCV information on a per message basis. The application 3053 will need to use the recvmsg() interface so that it can receive the 3054 event information contained in the msg_control field. Please see 3055 Section 5.2 for further details. Setting the flag to 0 will disable 3056 reception of the message control information. 3058 sctp_association_event - Setting this flag to 1 will enable the 3059 reception of association event notifications. Setting the flag to 0 3060 will disable association event notifications. For more information 3061 on event notifications please see Section 5.3. 3063 sctp_address_event - Setting this flag to 1 will enable the reception 3064 of address event notifications. Setting the flag to 0 will disable 3065 address event notifications. For more information on event 3066 notifications please see Section 5.3. 3068 sctp_send_failure_event - Setting this flag to 1 will enable the 3069 reception of send failure event notifications. Setting the flag to 0 3070 will disable send failure event notifications. For more information 3071 on event notifications please see Section 5.3. 3073 sctp_peer_error_event - Setting this flag to 1 will enable the 3074 reception of peer error event notifications. Setting the flag to 0 3075 will disable peer error event notifications. For more information on 3076 event notifications please see Section 5.3. 3078 sctp_shutdown_event - Setting this flag to 1 will enable the 3079 reception of shutdown event notifications. Setting the flag to 0 3080 will disable shutdown event notifications. For more information on 3081 event notifications please see Section 5.3. 3083 sctp_partial_delivery_event - Setting this flag to 1 will enable the 3084 reception of partial delivery notifications. Setting the flag to 0 3085 will disable partial delivery event notifications. For more 3086 information on event notifications please see Section 5.3. 3088 sctp_adaptation_layer_event - Setting this flag to 1 will enable the 3089 reception of adaptation layer notifications. Setting the flag to 0 3090 will disable adaptation layer event notifications. For more 3091 information on event notifications please see Section 5.3. 3093 sctp_authentication_event - Setting this flag to 1 will enable the 3094 reception of authentication layer notifications. Setting the flag to 3095 0 will disable authentication layer event notifications. For More 3096 information please see Section 5.3. 3098 An example where an application would like to receive data io events 3099 and association events but no others would be as follows: 3101 { 3102 struct sctp_event_subscribe event; 3104 memset(&event,0,sizeof(event)); 3106 event.sctp_data_io_event = 1; 3107 event.sctp_association_event = 1; 3109 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3110 } 3112 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3113 receives ancillary data and notifications for ALL associations bound 3114 to the file descriptor. For one-to-one style SCTP sockets, the 3115 caller receives ancillary data and notifications for only the single 3116 association bound to the file descriptor. 3118 By default both the one-to-one style and one-to-many style socket has 3119 all options off. 3121 8. New Interfaces 3123 Depending on the system, the following interface can be implemented 3124 as a system call or library function. 3126 8.1. sctp_bindx() 3128 The syntax of sctp_bindx() is, 3130 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 3131 int flags); 3133 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3134 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3135 or IPv6 addresses. 3137 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3138 Section 3.1.2 for this usage. 3140 addrs is a pointer to an array of one or more socket addresses. Each 3141 address is contained in its appropriate structure. For an IPv6 3142 socket, an array of sockaddr_in6 would be returned. For a IPv4 3143 socket, an array of sockaddr_in would be returned. The caller 3144 specifies the number of addresses in the array with addrcnt. Note 3145 that the wildcard addresses cannot be used with this function, doing 3146 so will result in an error. 3148 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3149 -1, and sets errno to the appropriate error code. 3151 For SCTP, the port given in each socket address must be the same, or 3152 sctp_bindx() will fail, setting errno to EINVAL. 3154 The flags parameter is formed from the bitwise OR of zero or more of 3155 the following currently defined flags: 3157 SCTP_BINDX_ADD_ADDR 3159 SCTP_BINDX_REM_ADDR 3161 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3162 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3163 addresses from the association. The two flags are mutually 3164 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3165 caller may not remove all addresses from an association; sctp_bindx() 3166 will reject such an attempt with EINVAL. 3168 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3169 additional addresses with an endpoint after calling bind(). Or use 3170 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3171 socket is associated with so that no new association accepted will be 3172 associated with those addresses. If the endpoint supports dynamic 3173 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 3174 endpoint to send the appropriate message to the peer to change the 3175 peers address lists. 3177 Adding and removing addresses from a connected association is 3178 optional functionality. Implementations that do not support this 3179 functionality should return EOPNOTSUPP. 3181 sctp_binx() can be called on an already bound socket or on an unbound 3182 socket. If the socket is unbound and the first port number in the 3183 addrs is zero, the kernel will chose a port number. All port number 3184 after the first one being 0 MUST also be zero. If the first port 3185 number is not zero, the following port numbers MUST be zero or have 3186 the same value as the first one. For an already bound socket, all 3187 port numbers provided MUST the the bound one or 0. 3189 8.2. Branched-off Association 3191 After an association is established on a one-to-many style socket, 3192 the application may wish to branch off the association into a 3193 separate socket/file descriptor. 3195 This is particularly desirable when, for instance, the application 3196 wishes to have a number of sporadic message senders/receivers remain 3197 under the original one-to-many style socket but branch off those 3198 associations carrying high volume data traffic into their own 3199 separate socket descriptors. 3201 The application uses sctp_peeloff() call to branch off an association 3202 into a separate socket (Note the semantics are somewhat changed from 3203 the traditional one-to-one style accept() call). Note that the new 3204 socket is a one-to-one style socket. Thus it will be confined to 3205 operations allowed for a one-to-one style socket. 3207 The syntax is: 3209 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 3211 new_sd: the new socket descriptor representing the branched-off 3212 association. 3213 sd: the original one-to-many style socket descriptor returned from 3214 the socket() system call (see Section 3.1.1). 3215 assoc_id: the specified identifier of the association that is to be 3216 branched off to a separate file descriptor (Note, in a traditional 3217 one-to-one style accept() call, this would be an out parameter, 3218 but for the one-to-many style call, this is an in parameter). 3220 8.3. sctp_getpaddrs() 3222 sctp_getpaddrs() returns all peer addresses in an association. The 3223 syntax is, 3225 int sctp_getpaddrs(int sd, sctp_assoc_t id, 3226 struct sockaddr **addrs); 3228 On return, addrs will point to an array dynamically allocated 3229 sockaddr structures of the appropriate type for the socket type. The 3230 caller should use sctp_freepaddrs() to free the memory. Note that 3231 the in/out parameter addrs must not be NULL. 3233 If sd is an IPv4 socket, the addresses returned will be all IPv4 3234 addresses. If sd is an IPv6 socket, the addresses returned can be a 3235 mix of IPv4 or IPv6 addresses. 3237 For one-to-many style sockets, id specifies the association to query. 3238 For one-to-one style sockets, id is ignored. 3240 On success, sctp_getpaddrs() returns the number of peer addresses in 3241 the association. If there is no association on this socket, 3242 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3243 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3244 is undefined. 3246 8.4. sctp_freepaddrs() 3248 sctp_freepaddrs() frees all resources allocated by 3249 sctp_getpaddrs(). Its syntax is, 3251 void sctp_freepaddrs(struct sockaddr *addrs); 3252 addrs is the array of peer addresses returned by sctp_getpaddrs(). 3254 8.5. sctp_getladdrs() 3256 sctp_getladdrs() returns all locally bound address(es) on a socket. 3257 The syntax is, 3259 int sctp_getladdrs(int sd, sctp_assoc_t id, 3260 struct sockaddr **ss); 3262 On return, addrs will point to a dynamically allocated array of 3263 sockaddr structures of the appropriate type for the socket type. The 3264 caller should use sctp_freeladdrs() to free the memory. Note that 3265 the in/out parameter addrs must not be NULL. 3267 If sd is an IPv4 socket, the addresses returned will be all IPv4 3268 addresses. If sd is an IPv6 socket, the addresses returned can be a 3269 mix of IPv4 or IPv6 addresses. 3271 For one-to-many style sockets, id specifies the association to query. 3272 For one-to-one style sockets, id is ignored. 3274 If the id field is set to the value '0' then the locally bound 3275 addresses are returned without regard to any particular association. 3277 On success, sctp_getladdrs() returns the number of local addresses 3278 bound to the socket. If the socket is unbound, sctp_getladdrs() 3279 returns 0, and the value of *addrs is undefined. If an error occurs, 3280 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3282 8.6. sctp_freeladdrs() 3284 sctp_freeladdrs() frees all resources allocated by 3285 sctp_getladdrs(). Its syntax is, 3287 void sctp_freeladdrs(struct sockaddr *addrs); 3289 addrs is the array of peer addresses returned by sctp_getladdrs(). 3291 8.7. sctp_sendmsg() 3293 An implementation may provide a library function (or possibly system 3294 call) to assist the user with the advanced features of SCTP. 3296 sctp_sendmsg(). Its syntax is, 3298 ssize_t sctp_sendmsg(int sd, 3299 const void *msg, 3300 size_t len, 3301 const struct sockaddr *to, 3302 socklen_t tolen, 3303 uint32_t ppid, 3304 uint32_t flags, 3305 uint16_t stream_no, 3306 uint32_t timetolive, 3307 uint32_t context) 3309 sd - is the socket descriptor 3310 msg - is the message to be sent. 3311 len - is the length of the message. 3312 to - is the destination address of the message. 3313 tolen - is the length of the destination address. 3314 ppid - is the same as sinfo_ppid (see section 5.2.2) 3315 flags - is the same as sinfo_flags (see section 5.2.2) 3316 stream_no - is the same as sinfo_stream (see section 5.2.2) 3317 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 3318 context - is the same as sinfo_context (see section 5.2.2) 3319 The call returns the number of characters sent, or -1 if an error 3320 occurred. The variable errno is then set appropriately. 3322 8.8. sctp_recvmsg() 3324 An implementation may provide a library function (or possibly system 3325 call) to assist the user with the advanced features of SCTP. Note 3326 that in order for the sctp_sndrcvinfo structure to be filled in by 3327 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3328 the SCTP_EVENTS option. Note that the setting of the 3329 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the 3330 sctp_sndrcvinfo information to be extended. 3332 sctp_recvmsg(). Its syntax is, 3334 ssize_t sctp_recvmsg(int sd, 3335 void *msg, 3336 size_t len, 3337 struct sockaddr *from, 3338 socklen_t *fromlen 3339 struct sctp_sndrcvinfo *sinfo 3340 int *msg_flags) 3342 sd - is the socket descriptor 3343 msg - is a message buffer to be filled. 3344 len - is the length of the message buffer. 3345 from - is a pointer to a address to be filled with the sender of 3346 this messages address. 3347 fromlen - is the from length. 3348 sinfo - A pointer to a sctp_sndrcvinfo structure to be filled upon 3349 receipt of the message. 3350 msg_flags - A pointer to a integer to be filled with any message 3351 flags (e.g. MSG_NOTIFICATION). 3352 The call returns the number of bytes received, or -1 if an error 3353 occurred. The variable errno is then set appropriately. 3355 8.9. sctp_connectx() 3357 An implementation may provide a library function (or possibly system 3358 call) to assist the user with associating to an endpoint that is 3359 multi-homed. Much like sctp_bindx() this call allows a caller to 3360 specify multiple addresses at which a peer can be reached. The way 3361 the SCTP stack uses the list of addresses to set up the association 3362 is implementation dependent. This function only specifies that the 3363 stack will try to make use of all the addresses in the list when 3364 needed. 3366 Note that the list of addresses passed in is only used for setting up 3367 the association. It does not necessarily equal the set of addresses 3368 the peer uses for the resulting association. If the caller wants to 3369 find out the set of peer addresses, it must use sctp_getpaddrs() to 3370 retrieve them after the association has been set up. 3372 sctp_connectx(). Its syntax is, 3374 int sctp_connectx(int sd, 3375 struct sockaddr *addrs, 3376 int addrcnt, 3377 sctp_assoc_t *id) 3379 sd - is the socket descriptor 3380 addrs - is an array of addresses. 3381 addrcnt - is the number of addresses in the array. 3382 id - is an output parameter that if passed in as a non-NULL will 3383 return the association identification for the newly created 3384 association (if successful). 3386 The call returns 0 on success or -1 if an error occured. The 3387 variable errno is then set appropriately. 3389 8.10. sctp_send() 3391 An implementation may provide another alternative function or system 3392 call to assist an application with the sending of data without the 3393 use of the CMSG header structures. The function takes the following 3394 form: 3396 sctp_send(). Its syntax is, 3398 int sctp_send(int sd, 3399 const void *msg, 3400 size_t len, 3401 const struct sctp_sndrcvinfo *sinfo, 3402 int flags); 3404 sd - is the socket descriptor 3405 msg - The message to be sent 3406 len - The length of the message 3407 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3408 in 5.2.2 for a sendmsg call. 3409 flags - is used in the same format as the sendmsg call flags (e.g. 3410 MSG_DONTROUTE). 3412 This function call may also be used to terminate an association using 3413 an association identification by setting the sinfo.sinfo_flags to 3414 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3415 to be terminated. In such a case the len of the message would be 3416 zero. 3418 The call returns the number of characters sent, or -1 if an error 3419 occurred. The variable errno is then set appropriately. 3421 8.11. sctp_sendx() 3423 An implementation may provide another alternative function or system 3424 call to assist an application with the sending of data without the 3425 use of the CMSG header structures that also gives a list of 3426 addresses. The list of addresses is provided for implicit 3427 association setup. In such a case the list of addresses serves the 3428 same purpose as the addresses given in sctp_connectx (see 3429 Section 8.9). 3431 sctp_sendx(). Its syntax is, 3433 int sctp_sendx(int sd, 3434 const void *msg, 3435 size_t len, 3436 struct sockaddr *addrs, 3437 int addrcnt, 3438 struct sctp_sndrcvinfo *sinfo, 3439 int flags); 3441 sd - is the socket descriptor 3442 msg - The message to be sent 3443 len - The length of the message 3444 addrs - is an array of addresses. 3445 addrcnt - is the number of addresses in the array. 3446 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3447 in 5.2.2 for a sendmsg call. 3448 flags - is used in the same format as the sendmsg call flags (e.g. 3449 MSG_DONTROUTE). 3451 Note that on return from this call the sinfo structure will have 3452 changed in that the sinfo_assoc_id will be filled in with the new 3453 association id. 3455 This function call may also be used to terminate an association using 3456 an association identification by setting the sinfo.sinfo_flags to 3457 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3458 to be terminated. In such a case the len of the message would be 3459 zero. 3461 The call returns the number of characters sent, or -1 if an error 3462 occurred. The variable errno is then set appropriately. 3464 8.12. sctp_getaddrlen 3466 For application binary portability it is sometimes desirable to know 3467 what the kernel thinks is the length of a socket address family. 3468 This function, when called with a valid family type will return the 3469 length that the operating system uses in the specified family's 3470 socket address structure. 3472 int sctp_getaddrlen(sa_family_t family); 3474 9. Preprocessor Constants 3476 For application portability it is desirable to define pre-processor 3477 constants for determination if sctp is present and supports various 3478 features. The following pre-processor constants should be defined in 3479 a include file, sctp.h. 3481 HAVE_SCTP - If this constant is defined, then an implementation of 3482 SCTP is available. 3483 HAVE_KERNEL_SCTP - If this constant is defined, then a kernel SCTP 3484 implementation is available through the sockets interface. 3485 HAVE_SCTP_PRSCTP - If this constant is defined, then the SCTP 3486 implementation supports the partial reliability extension to SCTP. 3487 HAVE_SCTP_ADDIP - If this constant is defined, then the SCTP 3488 implementation supports the dynamic address extension to SCTP. 3489 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined, then the 3490 SCTP implementation supports the ability to request setting of the 3491 remote primary address. 3492 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined, then 3493 the SCTP implementation supports the satellite network extension 3494 to SCTP. 3495 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 3496 implementation dedicates separate buffer space to each association 3497 on a one-to-many socket. If this constant is defined to 0, then 3498 the implementation provides a single block of shared buffer space 3499 for a one-to-many socket. 3500 HAVE_SCTP_NOCONNECT - If this constant is defined, then the SCTP 3501 implementation supports initiating an association on a one-to-one 3502 style socket without the use of connect(), as outlined in 3503 Section 4.1.5. 3504 HAVE_SCTP_EXT_RCVINFO - If this constant is defined, then the SCTP 3505 implementation supports the use of the extended style sndrecinfo 3506 structure, sctp_extrcvinfo. 3508 10. IANA considerations 3510 This document contains no IANA considerations. 3512 11. Security Considerations 3514 Many TCP and UDP implementations reserve port numbers below 1024 for 3515 privileged users. If the target platform supports privileged users, 3516 the SCTP implementation SHOULD restrict the ability to call bind() or 3517 sctp_bindx() on these port numbers to privileged users. 3519 Similarly unprivileged users should not be able to set protocol 3520 parameters which could result in the congestion control algorithm 3521 being more aggressive than permitted on the public Internet. These 3522 parameters are: 3524 struct sctp_rtoinfo 3526 If an unprivileged user inherits a one-to-many style socket with open 3527 associations on a privileged port, it MAY be permitted to accept new 3528 associations, but it SHOULD NOT be permitted to open new 3529 associations. This could be relevant for the r* family of protocols. 3531 12. Acknowledgments 3533 Special acknowledgment is given to Ken Fujita and Jonathan Woods who 3534 helped extensively in the early formation of this document. 3536 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3537 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, and 3538 many others on the TSVWG mailing list for contributing valuable 3539 comments. 3541 A special thanks to Phillip Conrad, for his suggested text, quick and 3542 constructive insights, and most of all his persistent fighting to 3543 keep the interface to SCTP usable for the application programmer. 3545 13. Normative references 3547 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3548 RFC 793, September 1981. 3550 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3551 August 1980. 3553 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3554 Functional Specification", RFC 1644, July 1994. 3556 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3557 3", BCP 9, RFC 2026, October 1996. 3559 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3560 Requirement Levels", BCP 14, RFC 2119, March 1997. 3562 [RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for 3563 IPv6", RFC 2292, February 1998. 3565 [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, 3566 "Basic Socket Interface Extensions for IPv6", RFC 2553, 3567 March 1999. 3569 [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., 3570 Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., 3571 Zhang, L., and V. Paxson, "Stream Control Transmission 3572 Protocol", RFC 2960, October 2000. 3574 Appendix A. one-to-one style Code Example 3576 The following code is a simple implementation of an echo server over 3577 SCTP. The example shows how to use some features of one-to-one style 3578 IPv4 SCTP sockets, including: 3580 o Opening, binding, and listening for new associations on a socket; 3581 o Enabling ancillary data 3582 o Enabling notifications 3583 o Using ancillary data with sendmsg() and recvmsg() 3584 o Using MSG_EOR to determine if an entire message has been read 3585 o Handling notifications 3587 #include 3588 #include 3589 #include 3590 #include 3591 #include 3592 #include 3593 #include 3594 #include 3595 #include 3597 #define BUFLEN 100 3599 static void 3600 handle_event(void *buf) 3601 { 3602 struct sctp_assoc_change *sac; 3603 struct sctp_send_failed *ssf; 3604 struct sctp_paddr_change *spc; 3605 struct sctp_remote_error *sre; 3606 union sctp_notification *snp; 3607 char addrbuf[INET6_ADDRSTRLEN]; 3608 const char *ap; 3609 struct sockaddr_in *sin; 3610 struct sockaddr_in6 *sin6; 3612 snp = buf; 3614 switch (snp->sn_header.sn_type) { 3615 case SCTP_ASSOC_CHANGE: 3616 sac = &snp->sn_assoc_change; 3617 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3618 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3619 sac->sac_inbound_streams, sac->sac_outbound_streams); 3620 break; 3621 case SCTP_SEND_FAILED: 3622 ssf = &snp->sn_send_failed; 3623 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3624 ssf->ssf_error); 3625 break; 3627 case SCTP_PEER_ADDR_CHANGE: 3628 spc = &snp->sn_paddr_change; 3629 if (spc->spc_aaddr.ss_family == AF_INET) { 3630 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3631 ap = inet_ntop(AF_INET, &sin->sin_addr, 3632 addrbuf, INET6_ADDRSTRLEN); 3633 } else { 3634 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3635 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3636 addrbuf, INET6_ADDRSTRLEN); 3637 } 3638 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3639 spc->spc_state, spc->spc_error); 3640 break; 3641 case SCTP_REMOTE_ERROR: 3642 sre = &snp->sn_remote_error; 3643 printf("^^^ remote_error: err=%hu len=%hu\n", 3644 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3645 break; 3646 case SCTP_SHUTDOWN_EVENT: 3647 printf("^^^ shutdown event\n"); 3648 break; 3649 default: 3650 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3651 break; 3652 }; 3653 } 3655 static void * 3656 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3657 ssize_t *nrp, size_t cmsglen) 3658 { 3659 ssize_t nr = 0, nnr = 0; 3660 struct iovec iov[1]; 3662 *nrp = 0; 3663 iov->iov_base = buf; 3664 iov->iov_len = *buflen; 3665 msg->msg_iov = iov; 3666 msg->msg_iovlen = 1; 3668 for (;;) { 3669 #ifndef MSG_XPG4_2 3670 #define MSG_XPG4_2 0 3671 #endif 3672 msg->msg_flags = MSG_XPG4_2; 3673 msg->msg_controllen = cmsglen; 3675 nnr = recvmsg(fd, msg, 0); 3676 if (nnr <= 0) { 3677 /* EOF or error */ 3678 *nrp = nr; 3679 return (NULL); 3680 } 3681 nr += nnr; 3683 if ((msg->msg_flags & MSG_EOR) != 0) { 3684 *nrp = nr; 3685 return (buf); 3686 } 3688 /* Realloc the buffer? */ 3689 if (*buflen == (size_t)nr) { 3690 buf = realloc(buf, *buflen * 2); 3691 if (buf == 0) { 3692 fprintf(stderr, "out of memory\n"); 3693 exit(1); 3694 } 3695 *buflen *= 2; 3696 } 3697 /* Set the next read offset */ 3698 iov->iov_base = (char *)buf + nr; 3699 iov->iov_len = *buflen - nr; 3700 } 3701 } 3703 static void 3704 echo(int fd, int socketModeone_to_many) 3705 { 3706 ssize_t nr; 3707 struct sctp_sndrcvinfo *sri; 3708 struct msghdr msg[1]; 3709 struct cmsghdr *cmsg; 3710 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3711 char *buf; 3712 size_t buflen; 3713 struct iovec iov[1]; 3714 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3715 /* Allocate the initial data buffer */ 3716 buflen = BUFLEN; 3717 if (!(buf = malloc(BUFLEN))) { 3718 fprintf(stderr, "out of memory\n"); 3719 exit(1); 3720 } 3722 /* Set up the msghdr structure for receiving */ 3723 memset(msg, 0, sizeof (*msg)); 3724 msg->msg_control = cbuf; 3725 msg->msg_controllen = cmsglen; 3726 msg->msg_flags = 0; 3727 cmsg = (struct cmsghdr *)cbuf; 3728 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3730 /* Wait for something to echo */ 3731 while (buf = mysctp_recvmsg(fd, msg, 3732 buf, &buflen, &nr, cmsglen)) { 3734 /* Intercept notifications here */ 3735 if (msg->msg_flags & MSG_NOTIFICATION) { 3736 handle_event(buf); 3737 continue; 3738 } 3740 iov->iov_base = buf; 3741 iov->iov_len = nr; 3742 msg->msg_iov = iov; 3743 msg->msg_iovlen = 1; 3745 printf("got %u bytes on stream %hu:\n", nr, 3746 sri->sinfo_stream); 3747 write(0, buf, nr); 3749 /* Echo it back */ 3750 msg->msg_flags = MSG_XPG4_2; 3751 if (sendmsg(fd, msg, 0) < 0) { 3752 perror("sendmsg"); 3753 exit(1); 3754 } 3755 } 3757 if (nr < 0) { 3758 perror("recvmsg"); 3759 } 3760 if(socketModeone_to_many == 0) 3761 close(fd); 3762 } 3764 int main() 3765 { 3766 struct sctp_event_subscribe event; 3767 int lfd, cfd; 3768 int onoff = 1; 3769 struct sockaddr_in sin[1]; 3770 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3771 perror("socket"); 3772 exit(1); 3773 } 3775 sin->sin_family = AF_INET; 3776 sin->sin_port = htons(7); 3777 sin->sin_addr.s_addr = INADDR_ANY; 3778 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3779 perror("bind"); 3780 exit(1); 3781 } 3783 if (listen(lfd, 1) == -1) { 3784 perror("listen"); 3785 exit(1); 3786 } 3788 /* Wait for new associations */ 3789 for (;;) { 3790 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3791 perror("accept"); 3792 exit(1); 3793 } 3795 /* Enable all events */ 3796 event.sctp_data_io_event = 1; 3797 event.sctp_association_event = 1; 3798 event.sctp_address_event = 1; 3799 event.sctp_send_failure_event = 1; 3800 event.sctp_peer_error_event = 1; 3801 event.sctp_shutdown_event = 1; 3802 event.sctp_partial_delivery_event = 1; 3803 event.sctp_adaptation_layer_event = 1; 3804 if (setsockopt(cfd, IPPROTO_SCTP, 3805 SCTP_EVENTS, &event, 3806 sizeof(event)) != 0) { 3807 perror("setevent failed"); 3808 exit(1); 3809 } 3810 /* Echo back any and all data */ 3811 echo(cfd,0); 3812 } 3813 } 3815 Appendix B. one-to-many style Code Example 3817 The following code is a simple implementation of an echo server over 3818 SCTP. The example shows how to use some features of one-to-many 3819 style IPv4 SCTP sockets, including: 3821 o Opening and binding of a socket; 3822 o Enabling ancillary data 3823 o Enabling notifications 3824 o Using ancillary data with sendmsg() and recvmsg() 3825 o Using MSG_EOR to determine if an entire message has been read 3826 o Handling notifications 3828 Note most functions defined in Appendix A are reused in this example. 3830 int main() 3831 { 3832 int fd; 3833 int idleTime = 2; 3834 struct sockaddr_in sin[1]; 3835 struct sctp_event_subscribe event; 3837 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3838 perror("socket"); 3839 exit(1); 3840 } 3842 sin->sin_family = AF_INET; 3843 sin->sin_port = htons(7); 3844 sin->sin_addr.s_addr = INADDR_ANY; 3845 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3846 perror("bind"); 3847 exit(1); 3848 } 3850 /* Enable all notifications and events */ 3851 event.sctp_data_io_event = 1; 3852 event.sctp_association_event = 1; 3853 event.sctp_address_event = 1; 3854 event.sctp_send_failure_event = 1; 3855 event.sctp_peer_error_event = 1; 3856 event.sctp_shutdown_event = 1; 3857 event.sctp_partial_delivery_event = 1; 3858 event.sctp_adaptation_layer_event = 1; 3859 if (setsockopt(fd, IPPROTO_SCTP, 3860 SCTP_EVENTS, &event, 3861 sizeof(event)) != 0) { 3862 perror("setevent failed"); 3863 exit(1); 3864 } 3865 /* Set associations to auto-close in 2 seconds of 3866 * inactivity 3867 */ 3868 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3869 &idleTime, 4) < 0) { 3870 perror("setsockopt SCTP_AUTOCLOSE"); 3871 exit(1); 3872 } 3874 /* Allow new associations to be accepted */ 3875 if (listen(fd, 1) < 0) { 3876 perror("listen"); 3877 exit(1); 3878 } 3880 /* Wait for new associations */ 3881 while(1){ 3882 /* Echo back any and all data */ 3883 echo(fd,1); 3884 } 3885 } 3887 Authors' Addresses 3889 Randall R. Stewart 3890 Cisco Systems, Inc. 3891 4875 Forest Drive 3892 Suite 200 3893 Columbia, SC 29206 3894 USA 3896 Phone: 3897 Email: rrs@cisco.com 3899 Qiaobing Xie 3900 Motorola, Inc. 3901 1501 W. Shure Drive, #2309 3902 Arlington Heights, IL 60004 3903 USA 3905 Phone: 3906 Email: qxie1@email.mot.com 3908 La Monte H.P. Yarroll 3909 TimeSys Corp 3910 925 Liberty Ave. 3911 Pittsburgh, PA 15222 3912 USA 3914 Phone: 3915 Email: piggy@acm.org 3917 Kacheong Poon 3918 Sun Microsystems, Inc. 3919 4150 Network Circle 3920 Santa Clara, CA 95054 3921 USA 3923 Phone: 3924 Email: kacheong.poon@sun.com 3925 Michael Tuexen 3926 Univ. of Applied Sciences Muenster 3927 Stegerwaldstr. 39 3928 48565 Steinfurt 3929 Germany 3931 Email: tuexen@fh-muenster.de 3933 Full Copyright Statement 3935 Copyright (C) The IETF Trust (2007). 3937 This document is subject to the rights, licenses and restrictions 3938 contained in BCP 78, and except as set forth therein, the authors 3939 retain all their rights. 3941 This document and the information contained herein are provided on an 3942 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3943 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 3944 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 3945 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 3946 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3947 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3949 Intellectual Property 3951 The IETF takes no position regarding the validity or scope of any 3952 Intellectual Property Rights or other rights that might be claimed to 3953 pertain to the implementation or use of the technology described in 3954 this document or the extent to which any license under such rights 3955 might or might not be available; nor does it represent that it has 3956 made any independent effort to identify any such rights. Information 3957 on the procedures with respect to rights in RFC documents can be 3958 found in BCP 78 and BCP 79. 3960 Copies of IPR disclosures made to the IETF Secretariat and any 3961 assurances of licenses to be made available, or the result of an 3962 attempt made to obtain a general license or permission for the use of 3963 such proprietary rights by implementers or users of this 3964 specification can be obtained from the IETF on-line IPR repository at 3965 http://www.ietf.org/ipr. 3967 The IETF invites any interested party to bring to its attention any 3968 copyrights, patents or patent applications, or other proprietary 3969 rights that may cover technology that may be required to implement 3970 this standard. Please address the information to the IETF at 3971 ietf-ipr@ietf.org. 3973 Acknowledgment 3975 Funding for the RFC Editor function is provided by the IETF 3976 Administrative Support Activity (IASA).