idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-18.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 4010. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4021. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4028. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4034. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. 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 -- 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 (November 3, 2008) is 5653 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: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 3901 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft The Resource Group 4 Intended status: Informational K. Poon 5 Expires: May 7, 2009 Sun Microsystems, Inc. 6 M. Tuexen 7 Univ. of Applied Sciences Muenster 8 V. Yasevich 9 HP 10 P. Lei 11 Cisco Systems, Inc. 12 November 3, 2008 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-18.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 May 7, 2009. 42 Abstract 44 This document describes a mapping of the Stream Control Transmission 45 Protocol SCTP into a sockets API. The benefits of this mapping 46 include compatibility for TCP applications, access to new SCTP 47 features and a consolidated error and event notification scheme. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 53 3. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 4. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 6 55 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 56 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 7 57 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 8 58 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 9 59 4.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 10 60 4.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 11 61 4.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 12 62 4.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 63 4.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 64 4.4. Special considerations . . . . . . . . . . . . . . . . . . 14 65 5. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 15 66 5.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 67 5.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 16 68 5.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 17 69 5.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 18 70 5.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 18 71 5.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 19 72 5.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 20 73 5.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 20 74 5.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 21 75 5.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 21 76 6. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 22 77 6.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 22 78 6.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 23 79 6.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 24 80 6.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 25 81 6.2.3. Extended SCTP Header Information Structure 82 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27 83 6.3. SCTP Events and Notifications . . . . . . . . . . . . . . 28 84 6.3.1. SCTP Notification Structure . . . . . . . . . . . . . 29 85 6.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 30 86 6.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 32 87 6.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 33 88 6.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 33 89 6.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 35 90 6.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 35 91 6.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 36 92 6.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 37 93 6.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 37 94 6.4. Ancillary Data Considerations and Semantics . . . . . . . 38 95 6.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 38 96 6.4.2. Accessing and Manipulating Ancillary Data . . . . . . 38 97 6.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 39 98 7. Common Operations for Both Styles . . . . . . . . . . . . . . 40 99 7.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 40 100 7.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 42 101 7.3. read() and write() . . . . . . . . . . . . . . . . . . . . 42 102 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 43 103 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 43 104 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 45 105 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 45 106 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 46 107 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 47 108 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 47 109 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 48 110 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 48 111 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 48 112 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 48 113 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 49 114 8.1.10. Set Adaptation Layer Indicator 115 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 49 116 8.1.11. Enable/Disable Message Fragmentation 117 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 49 118 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 50 119 8.1.13. Set Default Send Parameters 120 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 52 121 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 52 122 8.1.15. Set/Clear IPv4 Mapped Addresses 123 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 53 124 8.1.16. Get or Set the Maximum Fragmentation Size 125 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 53 126 8.1.17. Get or Set the List of Supported HMAC Identifiers 127 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 53 128 8.1.18. Get or Set the Active Shared Key 129 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 54 130 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 55 131 8.1.20. Get or Set Fragmented Interleave 132 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 56 133 8.1.21. Set or Get the SCTP Partial Delivery Point 134 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 57 135 8.1.22. Set or Get the Use of Extended Receive Info 136 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 57 137 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 57 138 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 58 139 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 58 140 8.1.26. Enable or Disable Explicit EOR Marking 141 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 59 142 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 59 143 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 59 144 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 59 145 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 60 146 8.2.3. Get the List of Chunks the Peer Requires to be 147 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 61 148 8.2.4. Get the List of Chunks the Local Endpoint Requires 149 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 62 150 8.2.5. Get the Current Number of Associations 151 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 62 152 8.2.6. Get the Current Identifiers of Associations 153 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 62 154 8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 63 155 8.3.1. Set Peer Primary Address 156 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 63 157 8.3.2. Add a Chunk That Must Be Authenticated 158 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 63 159 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 64 160 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 64 161 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 65 162 8.4. Ancillary Data and Notification Interest Options . . . . . 66 163 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 68 164 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 68 165 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 69 166 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 70 167 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 71 168 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 71 169 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 72 170 9.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 72 171 9.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 73 172 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 73 173 9.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 74 174 9.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 75 175 9.12. sctp_getaddrlen() . . . . . . . . . . . . . . . . . . . . 76 176 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76 177 11. Security Considerations . . . . . . . . . . . . . . . . . . . 77 178 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77 179 13. Normative References . . . . . . . . . . . . . . . . . . . . . 77 180 Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 78 181 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 83 182 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 85 183 Intellectual Property and Copyright Statements . . . . . . . . . . 87 185 1. Introduction 187 The sockets API has provided a standard mapping of the Internet 188 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 189 [RFC0768] have benefited from this standard representation and access 190 method across many diverse platforms. SCTP is a new protocol that 191 provides many of the characteristics of TCP but also incorporates 192 semantics more akin to UDP. This document defines a method to map 193 the existing sockets API for use with SCTP, providing both a base for 194 access to new features and compatibility so that most existing TCP 195 applications can be migrated to SCTP with few (if any) changes. 197 There are three basic design objectives: 198 1. Maintain consistency with existing sockets APIs: We define a 199 sockets mapping for SCTP that is consistent with other sockets 200 API protocol mappings (for instance, UDP, TCP, IPv4, and IPv6). 201 2. Support a one-to-many style interface This set of semantics is 202 similar to that defined for connection-less protocols, such as 203 UDP. A one-to-many style SCTP socket should be able to control 204 multiple SCTP associations. This is similar to an UDP socket, 205 which can communicate with many peer end points. Each of these 206 associations is assigned an association ID so that an 207 applications can use the ID to differentiate them. Note that 208 SCTP is connection-oriented in nature, and it does not support 209 broadcast or multicast communications, as UDP does. 210 3. Support a one-to-one style interface This interface supports a 211 similar semantics as sockets for connection-oriented protocols, 212 such as TCP. A one-to-one style SCTP socket should only control 213 one SCTP association. One purpose of defining this interface is 214 to allow existing applications built on other connection-oriented 215 protocols be ported to use SCTP with very little effort. And 216 developers familiar with those semantics can easily adapt to 217 SCTP. Another purpose is to make sure that existing mechanisms 218 in most OSes to deal with socket, such as select(), should 219 continue to work with this style of socket. Extensions are added 220 to this mapping to provide mechanisms to exploit new features of 221 SCTP. 223 Goals 2 and 3 are not compatible, so in this document we define two 224 modes of mapping, namely the one-to-many style mapping and the one- 225 to-one style mapping. These two modes share some common data 226 structures and operations, but will require the use of two different 227 application programming styles. Note that all new SCTP features can 228 be used with both styles of socket. The decision on which one to use 229 depends mainly on the nature of applications. 231 A mechanism is defined to extract a one-to-many style SCTP 232 association into a one-to-one style socket. 234 Some of the SCTP mechanisms cannot be adequately mapped to existing 235 socket interface. In some cases, it is more desirable to have new 236 interface instead of using existing socket calls. Section 9 of this 237 document describes those new interface. 239 2. Conventions 241 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 242 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 243 document are to be interpreted as described in [RFC2119]. 245 3. Data Types 247 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 248 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 249 (e.g., uint16_t). We also assume the argument data types from 250 1003.1g when possible (e.g., the final argument to setsockopt() is a 251 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 252 size_t data type is used. 254 4. One-to-Many Style Interface 256 The one-to-many style interface has the following characteristics: 257 o Outbound association setup is implicit. 258 o Messages are delivered in complete messages (with one notable 259 exception). 260 o There is a 1 to MANY relationship between socket and association. 262 4.1. Basic Operation 264 A typical server in this style uses the following socket calls in 265 sequence to prepare an endpoint for servicing requests: 266 o socket() 267 o bind() 268 o listen() 269 o recvmsg() 270 o sendmsg() 271 o close() 273 A typical client uses the following calls in sequence to setup an 274 association with a server to request services: 275 o socket() 276 o sendmsg() 277 o recvmsg() 278 o close() 280 In this style, by default, all the associations connected to the 281 endpoint are represented with a single socket. Each associations is 282 assigned an association ID (type is sctp_assoc_t) so that an 283 application can use it to differentiate between them. In some 284 implementations, the peer endpoints addresses can also be used for 285 this purpose. But this is not required for performance reasons. If 286 an implementation does not support using addresses to differentiate 287 between different associations, the sendto() call can only be used to 288 setup an association implicitly. It cannot be used to send data to 289 an established association as the association ID cannot be specified. 291 Once as association ID is assigned to an SCTP association, that ID 292 will not be reused until the application explicitly terminates the 293 association. The resources belonged to that association will not be 294 freed until that happens. This is similar to the close() operation 295 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 296 option (section 7.1.8) is set. In this case, after the association 297 is terminated gracefully automatically, the association ID assigned 298 to it can be reused. All applications using this option should be 299 aware of this to avoid the possible problem of sending data to an 300 incorrect peer end point. 302 If the server or client wishes to branch an existing association off 303 to a separate socket, it is required to call sctp_peeloff() and in 304 the parameter specifies the association identification. The 305 sctp_peeloff() call will return a new socket which can then be used 306 with recv() and send() functions for message passing. See 307 Section 9.2 for more on branched-off associations. 309 Once an association is branched off to a separate socket, it becomes 310 completely separated from the original socket. All subsequent 311 control and data operations to that association must be done through 312 the new socket. For example, the close operation on the original 313 socket will not terminate any associations that have been branched 314 off to a different socket. 316 We will discuss the one-to-many style socket calls in more details in 317 the following subsections. 319 4.1.1. socket() 321 Applications use socket() to create a socket descriptor to represent 322 an SCTP endpoint. 324 The function prototype is 325 int socket(int domain, 326 int type, 327 int protocol); 329 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 330 type and IPPROTO_SCTP as the protocol. 332 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 333 socket. 335 The first form creates an endpoint which can use only IPv4 addresses, 336 while, the second form creates an endpoint which can use both IPv6 337 and IPv4 addresses. 339 4.1.2. bind() 341 Applications use bind() to specify which local address the SCTP 342 endpoint should associate itself with. 344 An SCTP endpoint can be associated with multiple addresses. To do 345 this, sctp_bindx() is introduced in Section 9.1 to help applications 346 do the job of associating multiple addresses. 348 These addresses associated with a socket are the eligible transport 349 addresses for the endpoint to send and receive data. The endpoint 350 will also present these addresses to its peers during the association 351 initialization process, see [RFC4960]. 353 After calling bind(), if the endpoint wishes to accept new 354 associations on the socket, it must call listen() (see 355 Section 4.1.3). 357 The function prototype of bind() is 359 int bind(int sd, 360 struct sockaddr *addr, 361 socklen_t addrlen); 363 and the arguments are 364 sd: The socket descriptor returned by socket(). 365 addr: The address structure (struct sockaddr_in or struct 366 sockaddr_in6, see [RFC3493]). 367 addrlen: The size of the address structure. 369 If sd is an IPv4 socket, the address passed must be an IPv4 address. 370 If the sd is an IPv6 socket, the address passed can either be an IPv4 371 or an IPv6 address. 373 Applications cannot call bind() multiple times to associate multiple 374 addresses to an endpoint. After the first call to bind(), all 375 subsequent calls will return an error. 377 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 378 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 379 operating system will associate the endpoint with an optimal address 380 set of the available interfaces. 382 If a bind() is not called prior to a sendmsg() call that initiates a 383 new association, the system picks an ephemeral port and will choose 384 an address set equivalent to binding with a wildcard address. One of 385 those addresses will be the primary address for the association. 386 This automatically enables the multi-homing capability of SCTP. 388 4.1.3. listen() 390 By default, new associations are not accepted for one-to-many style 391 sockets. An application uses listen() to mark a socket as being able 392 to accept new associations. 394 The function prototype is 396 int listen(int sd, 397 int backlog); 399 and the arguments are 400 sd: The socket descriptor of the endpoint. 401 backlog: If backlog is non-zero, enable listening else disable 402 listening. 404 Note that one-to-many style socket consumers do not need to call 405 accept to retrieve new associations. Calling accept() on a one-to- 406 many style socket should return EOPNOTSUPP. Rather, new associations 407 are accepted automatically, and notifications of the new associations 408 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 409 these notifications are enabled). Clients will typically not call 410 listen(), so that they can be assured that the only associations on 411 the socket will be ones they actively initiated. Server or peer-to- 412 peer sockets, on the other hand, will always accept new associations, 413 so a well-written application using server one-to-many style sockets 414 must be prepared to handle new associations from unwanted peers. 416 Also note that the SCTP_ASSOC_CHANGE event provides the association 417 ID for a new association, so if applications wish to use the 418 association ID as input to other socket calls, they should ensure 419 that the SCTP_ASSOC_CHANGE event is enabled. 421 4.1.4. sendmsg() and recvmsg() 423 An application uses sendmsg() and recvmsg() call to transmit data to 424 and receive data from its peer. 426 The function prototypes are 428 ssize_t sendmsg(int sd, 429 const struct msghdr *message, 430 int flags); 432 and 434 ssize_t recvmsg(int sd, 435 struct msghdr *message, 436 int flags); 438 using the arguments: 439 sd: The socket descriptor of the endpoint. 440 message: Pointer to the msghdr structure which contains a single 441 user message and possibly some ancillary data. See Section 6 for 442 complete description of the data structures. 443 flags: No new flags are defined for SCTP at this level. See 444 Section 6 for SCTP-specific flags used in the msghdr structure. 446 As we will see in Section 6, along with the user data, the ancillary 447 data field is used to carry the sctp_sndrcvinfo and/or the 448 sctp_initmsg structures to perform various SCTP functions including 449 specifying options for sending each user message. Those options, 450 depending on whether sending or receiving, include stream number, 451 stream sequence number, various flags, context and payload protocol 452 Id, etc. 454 When sending user data with sendmsg(), the msg_name field in msghdr 455 structure will be filled with one of the transport addresses of the 456 intended receiver. If there is no association existing between the 457 sender and the intended receiver, the sender's SCTP stack will set up 458 a new association and then send the user data (see Section 4.2 for 459 more on implicit association setup). If an SCTP_INIT cmsg structure 460 is used with NULL data, an association will be established using the 461 parameters from the struct sctp_initmsg structure. If no SCTP_INIT 462 cmsg structure is used in combination with NULL data, an association 463 is established using the default parameters. If NULL data is used, 464 no association exists and the SCTP_ABORT or SCTP_EOF -1 MUST be 465 returned and an errno SHOULD be set to something like EDONOTBESTUPID. 466 Sending a message using sendmsg() is atomic unless explicit EOR 467 marking is enabled on the socket specified by sd. 469 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 470 be delivered if that notification has been enabled, and no more data 471 can be sent to that association. Any attempt to send more data will 472 cause sendmsg() to return with an ESHUTDOWN error. Note that the 473 socket is still open for reading at this point so it is possible to 474 retrieve notifications. 476 When receiving a user message with recvmsg(), the msg_name field in 477 msghdr structure will be populated with the source transport address 478 of the user data. The caller of recvmsg() can use this address 479 information to determine to which association the received user 480 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 481 applications must use the peer transport address provided in the 482 msg_name field by recvmsg() to perform correlation to an association, 483 since they will not have the association ID. 485 If all data in a single message has been delivered, MSG_EOR will be 486 set in the msg_flags field of the msghdr structure (see section 487 Section 6.1). 489 If the application does not provide enough buffer space to completely 490 receive a data message, MSG_EOR will not be set in msg_flags. 491 Successive reads will consume more of the same message until the 492 entire message has been delivered, and MSG_EOR will be set. 494 If the SCTP stack is running low on buffers, it may partially deliver 495 a message. In this case, MSG_EOR will not be set, and more calls to 496 recvmsg() will be necessary to completely consume the message. Only 497 one message at a time can be partially delivered in any stream. The 498 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 499 what interlacing of messages occurs for both the one-to-one and the 500 one-to-many model sockets. Please consult Section 8.1.20 for further 501 details on message delivery options. 503 Note, if the socket is a branched-off socket that only represents one 504 association (see Section 4.1), the msg_name field can be used to 505 override the primary address when sending data. 507 4.1.5. close() 509 Applications use close() to perform graceful shutdown (as described 510 in Section 10.1 of [RFC4960]) on ALL the associations currently 511 represented by a one-to-many style socket. 513 The function prototype is 515 int close(int sd); 516 and the argument is 517 sd: The socket descriptor of the associations to be closed. 519 To gracefully shutdown a specific association represented by the one- 520 to-many style socket, an application should use the sendmsg() call, 521 and including the SCTP_EOF flag. A user may optionally terminate an 522 association non-gracefully by sending with the SCTP_ABORT flag and 523 possibly passing a user specified abort code in the data field. Both 524 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 525 Section 6.2.2) in the sendmsg call. 527 If sd in the close() call is a branched-off socket representing only 528 one association, the shutdown is performed on that association only. 530 4.1.6. connect() 532 An application may use the connect() call in the one-to-many style to 533 initiate an association without sending data. 535 The function prototype is 537 int connect(int sd, 538 const struct sockaddr *nam, 539 socklen_t len); 541 and the arguments are 542 sd: The socket descriptor to have a new association added to. 543 nam: The address structure (either struct sockaddr_in or struct 544 sockaddr_in6 defined in [RFC3493]). 545 len: The size of the address. 547 Multiple connect() calls can be made on the same socket to create 548 multiple associations. This is different from the semantics of 549 connect() on a UDP socket. 551 4.2. Implicit Association Setup 553 Implicit association setup applies only to one-to-many style sockets. 554 For one-to-one style sockets implicit association setup MUST NOT be 555 used. 557 Once the bind() call is complete on a one-to-many style socket, the 558 application can begin sending and receiving data using the sendmsg()/ 559 recvmsg() or sendto()/recvfrom() calls, without going through any 560 explicit association setup procedures (i.e., no connect() calls 561 required). 563 Whenever sendmsg() or sendto() is called and the SCTP stack at the 564 sender finds that there is no association existing between the sender 565 and the intended receiver (identified by the address passed either in 566 the msg_name field of msghdr structure in the sendmsg() call or the 567 dest_addr field in the sendto() call), the SCTP stack will 568 automatically setup an association to the intended receiver. 570 Upon the successful association setup a SCTP_COMM_UP notification 571 will be dispatched to the socket at both the sender and receiver 572 side. This notification can be read by the recvmsg() system call 573 (see Section 4.1.3). 575 Note, if the SCTP stack at the sender side supports bundling, the 576 first user message may be bundled with the COOKIE ECHO message 577 [RFC4960]. 579 When the SCTP stack sets up a new association implicitly, it first 580 consults the sctp_initmsg structure, which is passed along within the 581 ancillary data in the sendmsg() call (see Section 6.2.1 for details 582 of the data structures), for any special options to be used on the 583 new association. 585 If this information is not present in the sendmsg() call, or if the 586 implicit association setup is triggered by a sendto() call, the 587 default association initialization parameters will be used. These 588 default association parameters may be set with respective 589 setsockopt() calls or be left to the system defaults. 591 Implicit association setup cannot be initiated by send()/recv() 592 calls. 594 4.3. Non-blocking mode 596 Some SCTP users might want to avoid blocking when they call socket 597 interface function. 599 Once all bind() calls are complete on a one-to-many style socket, the 600 application must set the non-blocking option by a fcntl() (such as 601 O_NONBLOCK). After which the sendmsg() function returns immediately, 602 and the success or failure of the data message (and possible 603 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 604 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 605 be sent (due to a CANT_START_ASSOC), the sender will also receive a 606 SCTP_SEND_FAILED event. Those event(s) can be received by the user 607 calling of recvmsg(). A server (having called listen()) is also 608 notified of an association up event by the reception of a 609 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 610 possibly the reception of the first data message. 612 In order to shutdown the association gracefully, the user must call 613 sendmsg() with no data and with the SCTP_EOF flag set. The function 614 returns immediately, and completion of the graceful shutdown is 615 indicated by an SCTP_ASSOC_CHANGE notification of type 616 SHUTDOWN_COMPLETE (see Section 6.3.2). Note that this can also be 617 done using the sctp_send() call described in Section 9.10. 619 An application is recommended to use caution when using select() (or 620 poll()) for writing on a one-to-many style socket. The reason being 621 that interpretation of select on write is implementation specific. 622 Generally a positive return on a select on write would only indicate 623 that one of the associations represented by the one-to-many socket is 624 writable. An application that writes after the select return may 625 still block since the association that was writeable is not the 626 destination association of the write call. Likewise select (or 627 poll()) for reading from a one-to-many socket will only return an 628 indication that one of the associations represented by the socket has 629 data to be read. 631 An application that wishes to know that a particular association is 632 ready for reading or writing should either use the one-to-one style 633 or use the sctp_peeloff() (see Section 9.2) function to separate the 634 association of interest from the one-to-many socket. 636 4.4. Special considerations 638 The fact that a one-to-many style socket can provide access to many 639 SCTP associations through a single socket descriptor has important 640 implications for both application programmers and system programmers 641 implementing this API. A key issue is how buffer space inside the 642 sockets layer is managed. Because this implementation detail 643 directly affects how application programmers must write their code to 644 ensure correct operation and portability, this section provides some 645 guidance to both implementers and application programmers. 647 An important feature that SCTP shares with TCP is flow control: 648 specifically, a sender may not send data faster than the receiver can 649 consume it. 651 For TCP, flow control is typically provided for in the sockets API as 652 follows. If the reader stops reading, the sender queues messages in 653 the socket layer until it uses all of its socket buffer space 654 allocation creating a "stalled connection". Further attempts to 655 write to the socket will block or return the error EAGAIN or 656 EWOULDBLOCK for a non-blocking socket. At some point, either the 657 connection is closed, or the receiver begins to read again freeing 658 space in the output queue. 660 For one-to-one style SCTP sockets (this includes sockets descriptors 661 that were separated from a one-to-many style socket with 662 sctp_peeloff()) the behavior is identical. For one-to-many style 663 SCTP sockets, the fact that we have multiple associations on a single 664 socket makes the situation more complicated. If the implementation 665 uses a single buffer space allocation shared by all associations, a 666 single stalled association can prevent the further sending of data on 667 all associations active on a particular one-to-many style socket. 669 For a blocking socket, it should be clear that a single stalled 670 association can block the entire socket. For this reason, 671 application programmers may want to use non-blocking one-to-many 672 style sockets. The application should at least be able to send 673 messages to the non-stalled associations. 675 But a non-blocking socket is not sufficient if the API implementer 676 has chosen a single shared buffer allocation for the socket. A 677 single stalled association would eventually cause the shared 678 allocation to fill, and it would become impossible to send even to 679 non-stalled associations. 681 The API implementer can solve this problem by providing each 682 association with its own allocation of outbound buffer space. Each 683 association should conceptually have as much buffer space as it would 684 have if it had its own socket. As a bonus, this simplifies the 685 implementation of sctp_peeloff(). 687 To ensure that a given stalled association will not prevent other 688 non-stalled associations from being writable, application programmers 689 should either: 690 o demand that the underlying implementation dedicates independent 691 buffer space allotments to each association (as suggested above), 692 or 693 o verify that their application layer protocol does not permit large 694 amounts of unread data at the receiver (this is true of some 695 request-response protocols, for example), or 696 o use one-to-one style sockets for association which may potentially 697 stall (either from the beginning, or by using sctp_peeloff before 698 sending large amounts of data that may cause a stalled condition). 700 5. One-to-One Style Interface 702 The goal of this style is to follow as closely as possible the 703 current practice of using the sockets interface for a connection 704 oriented protocol, such as TCP. This style enables existing 705 applications using connection oriented protocols to be ported to SCTP 706 with very little effort. 708 Note that some new SCTP features and some new SCTP socket options can 709 only be utilized through the use of sendmsg() and recvmsg() calls, 710 see Section 5.1.8. Also note that some socket interfaces may not be 711 able to provide data on the third leg of the association set up with 712 this interface style. 714 5.1. Basic Operation 716 A typical server in one-to-one style uses the following system call 717 sequence to prepare an SCTP endpoint for servicing requests: 718 o socket() 719 o bind() 720 o listen() 721 o accept() 723 The accept() call blocks until a new association is set up. It 724 returns with a new socket descriptor. The server then uses the new 725 socket descriptor to communicate with the client, using recv() and 726 send() calls to get requests and send back responses. 728 Then it calls 729 o close() 730 to terminate the association. 732 A typical client uses the following system call sequence to setup an 733 association with a server to request services: 734 o socket() 735 o connect() 737 After returning from connect(), the client uses send() and recv() 738 calls to send out requests and receive responses from the server. 740 The client calls 741 o close() 742 to terminate this association when done. 744 5.1.1. socket() 746 Applications calls socket() to create a socket descriptor to 747 represent an SCTP endpoint. 749 The function prototype is 751 int socket(int domain, 752 int type, 753 int protocol); 755 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 756 type and IPPROTO_SCTP as the protocol. 758 Here, SOCK_STREAM indicates the creation of a one-to-one style 759 socket. 761 The first form creates an endpoint which can use only IPv4 addresses, 762 while the second form creates an endpoint which can use both IPv6 and 763 IPv4 addresses. 765 5.1.2. bind() 767 Applications use bind() to pass an address to be associated with an 768 SCTP endpoint to the system. bind() allows only either a single 769 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 770 endpoint can be associated with multiple addresses. To do this, 771 sctp_bindx() is introduced in Section 9.1 to help applications do the 772 job of associating multiple addresses. 774 These addresses associated with a socket are the eligible transport 775 addresses for the endpoint to send and receive data. The endpoint 776 will also present these addresses to its peers during the association 777 initialization process, see [RFC4960]. 779 The function prototype of bind() is 781 int bind(int sd, 782 struct sockaddr *addr, 783 socklen_t addrlen); 785 and the arguments are 786 sd: The socket descriptor returned by socket(). 787 addr: The address structure (struct sockaddr_in or struct 788 sockaddr_in6, see [RFC3493]). 789 addrlen: The size of the address structure. 791 If sd is an IPv4 socket, the address passed must be an IPv4 address. 792 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 793 either be an IPv4 or an IPv6 address. 795 Applications cannot call bind() multiple times to associate multiple 796 addresses to the endpoint. After the first call to bind(), all 797 subsequent calls will return an error. 799 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 800 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 801 operating system will associate the endpoint with an optimal address 802 set of the available interfaces. 804 If a bind() is not called prior to the connect() call, the system 805 picks an ephemeral port and will choose an address set equivalent to 806 binding with a wildcard address. One of those addresses will be the 807 primary address for the association. This automatically enables the 808 multi-homing capability of SCTP. 810 The completion of this bind() process does not ready the SCTP 811 endpoint to accept inbound SCTP association requests. Until a 812 listen() system call, described below, is performed on the socket, 813 the SCTP endpoint will promptly reject an inbound SCTP INIT request 814 with an SCTP ABORT. 816 5.1.3. listen() 818 Applications use listen() to ready the SCTP endpoint for accepting 819 inbound associations. 821 The function prototype is 823 int listen(int sd, 824 int backlog); 826 and the arguments are 827 sd: the socket descriptor of the SCTP endpoint. 828 backlog: this specifies the max number of outstanding associations 829 allowed in the socket's accept queue. These are the associations 830 that have finished the four-way initiation handshake (see Section 831 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 832 of '0' indicates that the caller no longer wishes to receive new 833 associations. 835 5.1.4. accept() 837 Applications use accept() call to remove an established SCTP 838 association from the accept queue of the endpoint. A new socket 839 descriptor will be returned from accept() to represent the newly 840 formed association. 842 The function prototype is 844 int accept(int sd, 845 struct sockaddr *addr, 846 socklen_t *addrlen); 848 and the arguments are 849 sd: The listening socket descriptor. 850 addr: On return, will contain the primary address of the peer 851 endpoint. 852 addrlen: On return, will contain the size of addr. 853 The functions returns the socket descriptor for the newly formed 854 association. 856 5.1.5. connect() 858 Applications use connect() to initiate an association to a peer. 860 The function prototype is 862 int connect(int sd, 863 const struct sockaddr *addr, 864 socklen_t addrlen); 866 and the arguments are 867 sd: The socket descriptor of the endpoint. 868 addr: The peer's address. 869 addrlen: The size of the address. 871 This operation corresponds to the ASSOCIATE primitive described in 872 section 10.1 of [RFC4960]. 874 By default, the new association created has only one outbound stream. 875 The SCTP_INITMSG option described in Section 8.1.3 should be used 876 before connecting to change the number of outbound streams. 878 If a bind() is not called prior to the connect() call, the system 879 picks an ephemeral port and will choose an address set equivalent to 880 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 881 respectively. One of those addresses will be the primary address for 882 the association. This automatically enables the multi-homing 883 capability of SCTP. 885 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 886 during the association set up phase. If an application wants to do 887 this, it cannot use connect() call. Instead, it should use sendto() 888 or sendmsg() to initiate an association. If it uses sendto() and it 889 wants to change initialization behavior, it needs to use the 890 SCTP_INITMSG socket option before calling sendto(). Or it can use 891 SCTP_INIT type sendmsg() to initiate an association without doing the 892 setsockopt(). Note that some sockets implementations may not support 893 the sending of data to initiate an association with the one-to-one 894 style (implementations that do not support T/TCP normally have this 895 restriction). 897 SCTP does not support half close semantics. This means that unlike 898 T/TCP, MSG_EOF should not be set in the flags parameter when calling 899 sendto() or sendmsg() when the call is used to initiate a connection. 900 MSG_EOF is not an acceptable flag with SCTP socket. 902 5.1.6. close() 904 Applications use close() to gracefully close down an association. 906 The function prototype is 908 int close(int sd); 910 and the argument is 911 sd: The socket descriptor of the associations to be closed. 913 After an application calls close() on a socket descriptor, no further 914 socket operations will succeed on that descriptor. 916 5.1.7. shutdown() 918 SCTP differs from TCP in that it does not have half closed semantics. 919 Hence the shutdown() call for SCTP is an approximation of the TCP 920 shutdown() call, and solves some different problems. Full TCP- 921 compatibility is not provided, so developers porting TCP applications 922 to SCTP may need to recode sections that use shutdown(). (Note that 923 it is possible to achieve the same results as half close in SCTP 924 using SCTP streams.) 926 The function prototype is 928 int shutdown(int sd, 929 int how); 931 and the arguments are 932 sd: The socket descriptor of the association to be closed. 933 how: Specifies the type of shutdown. The values are as follows: 934 SHUT_RD: Disables further receive operations. No SCTP protocol 935 action is taken. 936 SHUT_WR: Disables further send operations, and initiates the SCTP 937 shutdown sequence. 938 SHUT_RDWR: Disables further send and receive operations and 939 initiates the SCTP shutdown sequence. 941 The major difference between SCTP and TCP shutdown() is that SCTP 942 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 943 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 944 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 945 the SCTP association while still leaving the socket descriptor open, 946 so that the caller can receive back any data SCTP was unable to 947 deliver (see Section 6.3.5 for more information). 949 To perform the ABORT operation described in [RFC4960] section 10.1, 950 an application can use the socket option SO_LINGER. It is described 951 in Section 8.1.4. 953 5.1.8. sendmsg() and recvmsg() 955 With a one-to-one style socket, the application can also use 956 sendmsg() and recvmsg() to transmit data to and receive data from its 957 peer. The semantics is similar to those used in the one-to-many 958 style (section Section 4.1.3), with the following differences: 959 1. When sending, the msg_name field in the msghdr is not used to 960 specify the intended receiver, rather it is used to indicate a 961 preferred peer address if the sender wishes to discourage the 962 stack from sending the message to the primary address of the 963 receiver. If the socket is connected and the transport address 964 given is not part of the current association, the data will not 965 be sent and a SCTP_SEND_FAILED event will be delivered to the 966 application if send failure events are enabled. 967 2. Using sendmsg() on a non-connected one-to-one style socket for 968 implicit connection setup may or may not work depending on the 969 SCTP implementation. 971 5.1.9. getpeername() 973 Applications use getpeername() to retrieve the primary socket address 974 of the peer. This call is for TCP compatibility, and is not multi- 975 homed. It does not work with one-to-many style sockets. See 976 Section 9.3 for a multi-homed/one-to-many style version of the call. 978 The function prototype is 980 int getpeername(int sd, 981 struct sockaddr *address, 982 socklen_t *len); 984 and the arguments are: 985 sd: The socket descriptor to be queried. 986 address: On return, the peer primary address is stored in this 987 buffer. If the socket is an IPv4 socket, the address will be 988 IPv4. If the socket is an IPv6 socket, the address will be either 989 an IPv6 or IPv4 address. 991 len: The caller should set the length of address here. On return, 992 this is set to the length of the returned address. 994 If the actual length of the address is greater than the length of the 995 supplied sockaddr structure, the stored address will be truncated. 997 6. Data Structures 999 We discuss in this section important data structures which are 1000 specific to SCTP and are used with sendmsg() and recvmsg() calls to 1001 control SCTP endpoint operations and to access ancillary information 1002 and notifications. 1004 6.1. The msghdr and cmsghdr Structures 1006 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1007 well as the ancillary data carried in the structure, is the key for 1008 the application to set and get various control information from the 1009 SCTP endpoint. 1011 The msghdr and the related cmsghdr structures are defined and 1012 discussed in details in [RFC3542]. Here we will cite their 1013 definitions from [RFC3542]. 1015 The msghdr structure: 1017 struct msghdr { 1018 void *msg_name; /* ptr to socket address structure */ 1019 socklen_t msg_namelen; /* size of socket address structure */ 1020 struct iovec *msg_iov; /* scatter/gather array */ 1021 size_t msg_iovlen; /* # elements in msg_iov */ 1022 void *msg_control; /* ancillary data */ 1023 socklen_t msg_controllen; /* ancillary data buffer length */ 1024 int msg_flags; /* flags on received message */ 1025 }; 1027 and the cmsghdr structure: 1029 struct cmsghdr { 1030 socklen_t cmsg_len; /* #bytes, including this header */ 1031 int cmsg_level; /* originating protocol */ 1032 int cmsg_type; /* protocol-specific type */ 1033 /* followed by unsigned char cmsg_data[]; */ 1034 }; 1036 In the msghdr structure, the usage of msg_name has been discussed in 1037 previous sections (see Section 4.1.3 and Section 5.1.8). 1039 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1040 field) are treated as a single SCTP data chunk, rather than multiple 1041 chunks, for both sendmsg() and recvmsg(). 1043 The msg_flags are not used when sending a message with sendmsg(). 1045 If a notification has arrived, recvmsg() will return the notification 1046 with the MSG_NOTIFICATION flag set in msg_flags. If the 1047 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1048 Section 6.3 for more information about notifications. 1050 If all portions of a data frame or notification have been read, 1051 recvmsg() will return with MSG_EOR set in msg_flags. 1053 6.2. SCTP msg_control Structures 1055 A key element of all SCTP-specific socket extensions is the use of 1056 ancillary data to specify and access SCTP-specific data via the 1057 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1058 Fine-grained control over initialization and sending parameters are 1059 handled with ancillary data. 1061 Each ancillary data item is proceeded by a struct cmsghdr (see 1062 Section 6.1), which defines the function and purpose of the data 1063 contained in in the cmsg_data[] member. 1065 There are two kinds of ancillary data used by SCTP: initialization 1066 data, and, header information (SNDRCV). Initialization data (one-to- 1067 many style only) sets protocol parameters for new associations. 1068 Section 6.2.1 provides more details. Header information can set or 1069 report parameters on individual messages in a stream. See 1070 Section 6.2.2 for how to use SNDRCV ancillary data. 1072 By default on a one-to-one style socket, SCTP will pass no ancillary 1073 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1074 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1075 be enabled with socket options defined for SCTP; see Section 8.4. 1077 Note that all ancillary types are fixed length; see Section 6.4 for 1078 further discussion on this. These data structures use struct 1079 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1080 address format. 1082 Other protocols may also provide ancillary data to the socket layer 1083 consumer. These ancillary data items from other protocols may 1084 intermingle with SCTP data. For example, the IPv6 socket API 1085 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1086 data items. If a socket API consumer enables delivery of both SCTP 1087 and IPv6 ancillary data, they both may appear in the same msg_control 1088 buffer in any order. An application may thus need to handle other 1089 types of ancillary data besides that passed by SCTP. 1091 The sockets application must provide a buffer large enough to 1092 accommodate all ancillary data provided via recvmsg(). If the buffer 1093 is not large enough, the ancillary data will be truncated and the 1094 msghdr's msg_flags will include MSG_CTRUNC. 1096 6.2.1. SCTP Initiation Structure (SCTP_INIT) 1098 This cmsghdr structure provides information for initializing new SCTP 1099 associations with sendmsg(). The SCTP_INITMSG socket option uses 1100 this same data structure. This structure is not used for recvmsg(). 1102 +--------------+-----------+---------------------+ 1103 | cmsg_level | cmsg_type | cmsg_data[] | 1104 +--------------+-----------+---------------------+ 1105 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1106 +--------------+-----------+---------------------+ 1108 Here is the definition of the sctp_initmsg structure: 1110 struct sctp_initmsg { 1111 uint16_t sinit_num_ostreams; 1112 uint16_t sinit_max_instreams; 1113 uint16_t sinit_max_attempts; 1114 uint16_t sinit_max_init_timeo; 1115 }; 1117 sinit_num_ostreams: This is an integer number representing the 1118 number of streams that the application wishes to be able to send 1119 to. This number is confirmed in the SCTP_COMM_UP notification and 1120 must be verified since it is a negotiated number with the remote 1121 endpoint. The default value of 0 indicates to use the endpoint 1122 default value. 1123 sinit_max_instreams: This value represents the maximum number of 1124 inbound streams the application is prepared to support. This 1125 value is bounded by the actual implementation. In other words the 1126 user MAY be able to support more streams than the Operating 1127 System. In such a case, the Operating System limit overrides the 1128 value requested by the user. The default value of 0 indicates to 1129 use the endpoints default value. 1130 sinit_max_attempts: This integer specifies how many attempts the 1131 SCTP endpoint should make at resending the INIT. This value 1132 overrides the system SCTP 'Max.Init.Retransmits' value. The 1133 default value of 0 indicates to use the endpoints default value. 1134 This is normally set to the system's default 'Max.Init.Retransmit' 1135 value. 1136 sinit_max_init_timeo: This value represents the largest Time-Out or 1137 RTO value (in milliseconds) to use in attempting an INIT. 1138 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1139 upon timeout. For the INIT message this value MAY override 1140 'RTO.Max'. This value MUST NOT influence 'RTO.Max' during data 1141 transmission and is only used to bound the initial setup time. A 1142 default value of 0 indicates to use the endpoints default value. 1143 This is normally set to the system's 'RTO.Max' value (60 seconds). 1145 6.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1147 This cmsghdr structure specifies SCTP options for sendmsg() and 1148 describes SCTP header information about a received message through 1149 recvmsg(). 1151 +--------------+-------------+------------------------+ 1152 | cmsg_level | cmsg_type | cmsg_data[] | 1153 +--------------+-------------+------------------------+ 1154 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1155 +--------------+-------------+------------------------+ 1157 Here is the definition of sctp_sndrcvinfo: 1159 struct sctp_sndrcvinfo { 1160 uint16_t sinfo_stream; 1161 uint16_t sinfo_ssn; 1162 uint16_t sinfo_flags; 1163 uint16_t sinfo_pr_policy; 1164 uint32_t sinfo_ppid; 1165 uint32_t sinfo_context; 1166 uint32_t sinfo_pr_value; 1167 uint32_t sinfo_tsn; 1168 uint32_t sinfo_cumtsn; 1169 sctp_assoc_t sinfo_assoc_id; 1170 }; 1172 sinfo_stream: For recvmsg() the SCTP stack places the message's 1173 stream number in this value. For sendmsg() this value holds the 1174 stream number that the application wishes to send this message to. 1175 If a sender specifies an invalid stream number an error indication 1176 is returned and the call fails. 1177 sinfo_ssn: For recvmsg() this value contains the stream sequence 1178 number that the remote endpoint placed in the DATA chunk. For 1179 fragmented messages this is the same number for all deliveries of 1180 the message (if more than one recvmsg() is needed to read the 1181 message). The sendmsg() call will ignore this parameter. 1183 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1184 passed to the remote end in each user message. In recvmsg() this 1185 value is the same information that was passed by the upper layer 1186 in the peer application. Please note that the SCTP stack performs 1187 no byte order modification of this field. For example, if the 1188 DATA chunk has to contain a given value in network byte order, the 1189 SCTP user has to perform the htonl() computation. 1190 sinfo_context: This value is an opaque 32 bit context datum that is 1191 used in the sendmsg() function. This value is passed back to the 1192 upper layer if a error occurs on the send of a message and is 1193 retrieved with each undelivered message (Note: if a endpoint has 1194 done multiple sends, all of which fail, multiple different 1195 sinfo_context values will be returned. One with each user data 1196 message). 1197 sinfo_flags: This field may contain any of the following flags and 1198 is composed of a bitwise OR of these values. 1199 recvmsg() flags: 1200 SCTP_UNORDERED: This flag is present when the message was sent 1201 non-ordered. 1202 sendmsg() flags: 1203 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1204 message. If this flag is clear the datagram is considered an 1205 ordered send. 1206 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1207 SCTP stack to override the primary destination address with the 1208 address found with the sendto/sendmsg call. 1209 SCTP_ABORT: Setting this flag causes the specified association to 1210 abort by sending an ABORT message to the peer (one-to-many 1211 style only). The ABORT chunk will contain an error cause 'User 1212 Initiated Abort' with cause code 12. The cause specific 1213 information of this error cause is provided in msg_iov. 1214 SCTP_EOF Setting this flag invokes the SCTP graceful shutdown 1215 procedures on the specified association. Graceful shutdown 1216 assures that all data queued by both endpoints is successfully 1217 transmitted before closing the association (one-to-many style 1218 only). 1219 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1220 socket to send the message to all associations that are 1221 currently established on this socket. For the one-to-one 1222 socket, this flag has no effect. 1223 sinfo_pr_policy: For the sending side, this specifies which PR-SCTP 1224 policy is used. Using SCTP_PR_SCTP_NONE results in a reliable 1225 transmission. When SCTP_PR_SCTP_TTL is used, the PR-SCTP policy 1226 "timed reliability" defined in [RFC3758] is used. In this case, 1227 the lifetime is provided in sinfo_pr_value. 1229 sinfo_pr_value: The meaning of this field depends of the PR-SCTP 1230 policy specified by the sinfo_pr_policy field. It is ignored when 1231 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1232 lifetime is specified. 1233 sinfo_tsn: For the receiving side, this field holds a TSN that was 1234 assigned to one of the SCTP Data Chunks. 1235 sinfo_cumtsn: This field will hold the current cumulative TSN as 1236 known by the underlying SCTP layer. Note this field is ignored 1237 when sending and only valid for a receive operation when 1238 sinfo_flags are set to SCTP_UNORDERED. 1239 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1240 the identifier for the association announced in the SCTP_COMM_UP 1241 notification. All notifications for a given association have the 1242 same identifier. Ignored for one-to-one style sockets. 1244 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1246 6.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1248 This cmsghdr structure specifies SCTP options for SCTP header 1249 information about a received message via recvmsg(). Note that this 1250 structure is an extended version of SCTP_SNDRCV (see Section 6.2.2) 1251 and will only be received if the user has set the socket option 1252 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1253 needed to receive ancillary data. Note that next message data is not 1254 valid unless the current message is completely read, i.e. the MSG_EOR 1255 is set, in other words if you have more data to read from the current 1256 message then no next message information will be available. 1258 +--------------+-------------+------------------------+ 1259 | cmsg_level | cmsg_type | cmsg_data[] | 1260 +--------------+-------------+------------------------+ 1261 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1262 +--------------+-------------+------------------------+ 1264 Here is the definition of sctp_extrcvinfo structure: 1266 struct sctp_extrcvinfo { 1267 struct sctp_sndrcvinfo serinfo_sinfo; 1268 uint16_t serinfo_next_flags; 1269 uint16_t serinfo_next_stream; 1270 uint32_t serinfo_next_aid; 1271 uint32_t serinfo_next_length; 1272 uint32_t serinfo_next_ppid; 1273 }; 1274 serinfo_sinfo: Please see Section 6.2.2 for the details for this 1275 structure. 1276 serinfo_next_flags: This bitmask will hold one or more of the 1277 following values: 1278 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1279 message information is available i.e.: next_stream, 1280 next_asocid, next_length and next_ppid fields all have valid 1281 values. If this bit is set to 0, then these fields are not 1282 valid and should be ignored. 1283 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1284 next message is completely in the receive buffer. The 1285 next_length field thus contains the entire message size. If 1286 this flag is set to 0, then the next_length field only contains 1287 part of the message size since the message is still being 1288 received (it is being partially delivered). 1289 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1290 the next message to be received was sent by the peer as 1291 unordered. If this bit is not set (i.e the bit is 0) the next 1292 message to be read is an ordered message in the stream 1293 specified. 1294 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1295 the next message to be received is not a message from the peer, 1296 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1297 serinfo_next_stream This value, when valid (see sreinfo_next_flags), 1298 contains the next stream number that will be received on a 1299 subsequent call to one of the receive message functions. 1300 serinfo_next_aid: This value, when valid (see next_flags), contains 1301 the next association identification that will be received on a 1302 subsequent call to one of the receive message functions. 1303 sreinfo_next_length: This value, when valid (see 1304 sreinfo_next_flags), contains the length of the next message that 1305 will be received on a subsequent call to one of the receive 1306 message functions. Note that this length may be a partial length 1307 depending on the settings of next_flags. 1308 sreinfo_next_ppid: This value, when valid (see sreinfo_next_flags), 1309 contains the ppid of the next message that will be received on a 1310 subsequent call to one of the receive message functions. 1312 6.3. SCTP Events and Notifications 1314 An SCTP application may need to understand and process events and 1315 errors that happen on the SCTP stack. These events include network 1316 status changes, association startups, remote operational errors and 1317 undeliverable messages. All of these can be essential for the 1318 application. 1320 When an SCTP application layer does a recvmsg() the message read is 1321 normally a data message from a peer endpoint. If the application 1322 wishes to have the SCTP stack deliver notifications of non-data 1323 events, it sets the appropriate socket option for the notifications 1324 it wants. See Section 8.4 for these socket options. When a 1325 notification arrives, recvmsg() returns the notification in the 1326 application-supplied data buffer via msg_iov, and sets 1327 MSG_NOTIFICATION in msg_flags. 1329 This section details the notification structures. Every notification 1330 structure carries some common fields which provides general 1331 information. 1333 A recvmsg() call will return only one notification at a time. Just 1334 as when reading normal data, it may return part of a notification if 1335 the msg_iov buffer is not large enough. If a single read is not 1336 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1337 reading the notification before subsequent data can arrive. 1339 6.3.1. SCTP Notification Structure 1341 The notification structure is defined as the union of all 1342 notification types. 1344 union sctp_notification { 1345 struct { 1346 uint16_t sn_type; /* Notification type. */ 1347 uint16_t sn_flags; 1348 uint32_t sn_length; 1349 } sn_header; 1350 struct sctp_assoc_change sn_assoc_change; 1351 struct sctp_paddr_change sn_paddr_change; 1352 struct sctp_remote_error sn_remote_error; 1353 struct sctp_send_failed sn_send_failed; 1354 struct sctp_shutdown_event sn_shutdown_event; 1355 struct sctp_adaptation_event sn_adaptation_event; 1356 struct sctp_pdapi_event sn_pdapi_event; 1357 struct sctp_authkey_event sn_auth_event; 1358 struct sctp_sender_dry_event sn_sender_dry_event; 1359 }; 1361 sn_type: The following list describes the SCTP notification and 1362 event types for the field sn_type. 1363 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1364 either been opened or closed. Refer to Section 6.3.2 for 1365 details. 1367 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1368 part of an existing association has experienced a change of 1369 state (e.g. a failure or return to service of the reachability 1370 of a endpoint via a specific transport address). Please see 1371 Section 6.3.3 for data structure details. 1372 SCTP_REMOTE_ERROR: The attached error message is an Operational 1373 Error received from the remote peer. It includes the complete 1374 TLV sent by the remote endpoint. See Section 6.3.4 for the 1375 detailed format. 1376 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1377 remote endpoint. This structure includes the original 1378 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1379 structure uses the sctp_sndrecvinfo per Section 6.3.5. 1380 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1381 data should be sent on this socket. 1382 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1383 indicated adaptation layer. Please see Section 6.3.7. 1384 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1385 receiver that the partial delivery has been aborted. This may 1386 indicate the association is about to be aborted. Please see 1387 Section 6.3.8 1388 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1389 receiver that either an error occurred on authentication, or a 1390 new key was made active. Section 6.3.9 1391 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1392 application that the sender has no user data queued anymore, 1393 neither for transmission or retransmission. Section 6.3.10 1394 All standard values for sn_type are greater than 2^15. Values 1395 from 2^15 and down are reserved. 1396 sn_flags: These are notification-specific flags. 1397 sn_length: This is the length of the whole sctp_notification 1398 structure including the sn_type, sn_flags, and sn_length fields. 1400 6.3.2. SCTP_ASSOC_CHANGE 1402 Communication notifications inform the ULP that an SCTP association 1403 has either begun or ended. The identifier for a new association is 1404 provided by this notification. The notification information has the 1405 following format: 1407 struct sctp_assoc_change { 1408 uint16_t sac_type; 1409 uint16_t sac_flags; 1410 uint32_t sac_length; 1411 uint16_t sac_state; 1412 uint16_t sac_error; 1413 uint16_t sac_outbound_streams; 1414 uint16_t sac_inbound_streams; 1415 sctp_assoc_t sac_assoc_id; 1416 uint8_t sac_info[]; 1417 }; 1419 sac_type: It should be SCTP_ASSOC_CHANGE. 1420 sac_flags: Currently unused. 1421 sac_length: This field is the total length of the notification data, 1422 including the notification header. 1423 sac_state: This field holds one of a number of values that 1424 communicate the event that happened to the association. They 1425 include: 1426 SCTP_COMM_UP: A new association is now ready and data may be 1427 exchanged with this peer. When an association has been 1428 established successfully, this notification should be the first 1429 one. 1430 SCTP_COMM_LOST: The association has failed. The association is 1431 now in the closed state. If SEND FAILED notifications are 1432 turned on, a SCTP_COMM_LOST is followed by a series of 1433 SCTP_SEND_FAILED events, one for each outstanding message. 1434 SCTP_RESTART: SCTP has detected that the peer has restarted. 1435 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1436 SCTP_CANT_STR_ASSOC - The association failed to setup. If non 1437 blocking mode is set and data was sent (in the udp mode), a 1438 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED 1439 events, one for each outstanding message. 1440 sac_error: If the state was reached due to a error condition (e.g. 1441 SCTP_COMM_LOST) any relevant error information is available in 1442 this field. This corresponds to the protocol error codes defined 1443 in [RFC4960]. 1444 sac_outbound_streams: 1445 sac_inbound_streams: The maximum number of streams allowed in each 1446 direction are available in sac_outbound_streams and sac_inbound 1447 streams. 1448 sac_assoc_id: The association id field, holds the identifier for the 1449 association. All notifications for a given association have the 1450 same association identifier. For one-to-one style socket, this 1451 field is ignored. 1453 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1454 received for this association, sac_info[] contains the complete 1455 ABORT chunk as defined in the SCTP specification [RFC4960] section 1456 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1457 may contain an array of features that the current association 1458 supports. Features include 1459 SCTP_PR: The both endpoints support the protocol extension 1460 described in [RFC3758]. 1461 SCTP_AUTH: The both endpoints support the protocol extension 1462 described in [RFC4895]. 1463 SCTP_ASCONF: The both endpoints support the protocol extension 1464 described in [RFC5061]. 1466 6.3.3. SCTP_PEER_ADDR_CHANGE 1468 When a destination address on a multi-homed peer encounters a change 1469 an interface details event is sent. The information has the 1470 following structure: 1472 struct sctp_paddr_change { 1473 uint16_t spc_type; 1474 uint16_t spc_flags; 1475 uint32_t spc_length; 1476 struct sockaddr_storage spc_aaddr; 1477 uint32_t spc_state; 1478 uint32_t spc_error; 1479 sctp_assoc_t spc_assoc_id; 1480 } 1482 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 1483 spc_flags: Currently unused. 1484 spc_length: This field is the total length of the notification data, 1485 including the notification header. 1486 spc_aaddr: The affected address field, holds the remote peer's 1487 address that is encountering the change of state. 1488 spc_state: This field holds one of a number of values that 1489 communicate the event that happened to the address. They include: 1490 SCTP_ADDR_AVAILABLE: This address is now reachable. 1491 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 1492 reached. Any data sent to this address is rerouted to an 1493 alternate until this address becomes reachable. 1494 SCTP_ADDR_REMOVED: The address is no longer part of the 1495 association. 1496 SCTP_ADDR_ADDED: The address is now part of the association. 1498 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 1499 primary destination address. 1500 SCTP_ADDR_CONFIRMED: This address has now been confirmed as a 1501 valid address. 1502 spc_error: If the state was reached due to any error condition (e.g. 1503 SCTP_ADDR_UNREACHABLE) any relevant error information is available 1504 in this field. 1505 spc_assoc_id: The association id field, holds the identifier for the 1506 association. All notifications for a given association have the 1507 same association identifier. For one-to-one style socket, this 1508 field is ignored. 1510 6.3.4. SCTP_REMOTE_ERROR 1512 A remote peer may send an Operational Error message to its peer. 1513 This message indicates a variety of error conditions on an 1514 association. The entire ERROR chunk as it appears on the wire is 1515 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1516 specification [RFC4960] and any extensions for a list of possible 1517 error formats. SCTP error notifications have the format: 1519 struct sctp_remote_error { 1520 uint16_t sre_type; 1521 uint16_t sre_flags; 1522 uint32_t sre_length; 1523 uint16_t sre_error; 1524 sctp_assoc_t sre_assoc_id; 1525 uint8_t sre_data[]; 1526 }; 1528 sre_type: It should be SCTP_REMOTE_ERROR. 1529 sre_flags: Currently unused. 1530 sre_length: This field is the total length of the notification data, 1531 including the notification header and the contents of sre_data. 1532 sre_error: This value represents one of the Operational Error causes 1533 defined in the SCTP specification, in network byte order. 1534 sre_assoc_id: The association id field, holds the identifier for the 1535 association. All notifications for a given association have the 1536 same association identifier. For one-to-one style socket, this 1537 field is ignored. 1538 sre_data: This contains the ERROR chunk as defined in the SCTP 1539 specification [RFC4960] section 3.3.10. 1541 6.3.5. SCTP_SEND_FAILED 1543 If SCTP cannot deliver a message it may return the message as a 1544 notification. 1546 struct sctp_send_failed { 1547 uint16_t ssf_type; 1548 uint16_t ssf_flags; 1549 uint32_t ssf_length; 1550 uint32_t ssf_error; 1551 struct sctp_sndrcvinfo ssf_info; 1552 sctp_assoc_t ssf_assoc_id; 1553 uint8_t ssf_data[]; 1554 }; 1556 ssf_type: It should be SCTP_SEND_FAILED. 1557 ssf_flags: The flag value will take one of the following values: 1558 SCTP_DATA_UNSENT: Indicates that the data was never put on the 1559 wire. 1560 SCTP_DATA_SENT: Indicates that the data was put on the wire. 1561 Note that this does not necessarily mean that the data was (or 1562 was not) successfully delivered. 1563 ssf_length: This field is the total length of the notification data, 1564 including the notification header and the payload in ssf_data. 1565 ssf_error: This value represents the reason why the send failed, and 1566 if set, will be a SCTP protocol error code as defined in [RFC4960] 1567 section 3.3.10. 1568 ssf_info: The send information associated with the undelivered 1569 message. The sinfo_flags field will also contain an indication if 1570 the beginning of the message and/or end of the message is present. 1571 In cases where no data has been sent on the wire, this field will 1572 have or'ed in the value SCTP_DATA_NOT_FRAG, which is a composition 1573 of both a "BEGIN" and "END" fragmentation bit. In cases where 1574 part of the data has been sent this field will hold an indication 1575 that just the part not sent is present SCTP_DATA_LAST_FRAG which 1576 corresponds to the "END" bit. Note that the message itself may be 1577 more than one chunk. If the sinfo_flags field holds neither of 1578 these two values then a piece that has been fragmented and sent 1579 but not acknowledged is present. This piece is from an 1580 unspecified position in the message and the application can make 1581 no assumptions about the data itself. Applications wanting to 1582 examine a recovered message should look for the 1583 SCTP_DATA_NOT_FRAG. Without this flag the application should 1584 assume part of the message arrived and take appropriate steps to 1585 audit and recover any lost or missing data. Note also that the 1586 partial reliablity information that was sent down to the SCTP 1587 stack is NOT present in the sinfo_flags field since it occupies 1588 the same bit positions as the SCTP_DATA_NOT_FRAG and the 1589 SCTP_DATA_LAST_FRAG bits. 1591 ssf_assoc_id: The association id field, sf_assoc_id, holds the 1592 identifier for the association. All notifications for a given 1593 association have the same association identifier. For one-to-one 1594 style socket, this field is ignored. 1595 ssf_data: The undelivered message or part of the undelivered message 1596 will be present in the sf_data field. Note that the sinfo_flags 1597 field as noted above should be used to determine if a complete 1598 message is present or just a piece of the message. Note that only 1599 user data is present in this field, any chunk headers or SCTP 1600 common headers must be removed by the SCTP stack. 1602 6.3.6. SCTP_SHUTDOWN_EVENT 1604 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1605 inform the application that it should cease sending data. 1607 struct sctp_shutdown_event { 1608 uint16_t sse_type; 1609 uint16_t sse_flags; 1610 uint32_t sse_length; 1611 sctp_assoc_t sse_assoc_id; 1612 }; 1614 sse_type It should be SCTP_SHUTDOWN_EVENT. 1615 sse_flags: Currently unused. 1616 sse_length: This field is the total length of the notification data, 1617 including the notification header. It will generally be sizeof 1618 (struct sctp_shutdown_event). 1619 sse_flags: Currently unused. 1620 sse_assoc_id: The association id field, holds the identifier for the 1621 association. All notifications for a given association have the 1622 same association identifier. For one-to-one style socket, this 1623 field is ignored. 1625 6.3.7. SCTP_ADAPTATION_INDICATION 1627 When a peer sends a Adaptation Layer Indication parameter , SCTP 1628 delivers this notification to inform the application that of the 1629 peers requested adaptation layer. 1631 struct sctp_adaptation_event { 1632 uint16_t sai_type; 1633 uint16_t sai_flags; 1634 uint32_t sai_length; 1635 uint32_t sai_adaptation_ind; 1636 sctp_assoc_t sai_assoc_id; 1637 }; 1638 sai_type: It should be SCTP_ADAPTATION_INDICATION. 1639 sai_flags: Currently unused. 1640 sai_length: This field is the total length of the notification data, 1641 including the notification header. It will generally be sizeof 1642 (struct sctp_adaptation_event). 1643 sai_adaptation_ind: This field holds the bit array sent by the peer 1644 in the adaptation layer indication parameter. The bits are in 1645 network byte order. 1646 sai_assoc_id: The association id field, holds the identifier for the 1647 association. All notifications for a given association have the 1648 same association identifier. For one-to-one style socket, this 1649 field is ignored. 1651 6.3.8. SCTP_PARTIAL_DELIVERY_EVENT 1653 When a receiver is engaged in a partial delivery of a message this 1654 notification will be used to indicate various events. 1656 struct sctp_pdapi_event { 1657 uint16_t pdapi_type; 1658 uint16_t pdapi_flags; 1659 uint32_t pdapi_length; 1660 uint32_t pdapi_indication; 1661 uint32_t pdapi_stream; 1662 uint32_t pdapi_seq; 1663 sctp_assoc_t pdapi_assoc_id; 1664 }; 1666 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 1667 pdapi_flags: Currently unused. 1668 pdapi_length: This field is the total length of the notification 1669 data, including the notification header. It will generally be 1670 sizeof(struct sctp_pdapi_event). 1671 pdapi_indication: This field holds the indication being sent to the 1672 application possible values include: 1673 SCTP_PARTIAL_DELIVERY_ABORTED: This notification indicates that 1674 the partial delivery of a user message has been aborted. 1675 pdapi_stream: This field holds the stream on which the partial 1676 delivery event happened. 1677 pdapi_seq: This field holds the stream sequence number which was 1678 being partially delivered. 1679 pdapi_assoc_id: The association id field, holds the identifier for 1680 the association. All notifications for a given association have 1681 the same association identifier. For one-to-one style socket, 1682 this field is ignored. 1684 6.3.9. SCTP_AUTHENTICATION_EVENT 1686 When a receiver is using authentication this message will provide 1687 notifications regarding new keys being made active as well as errors. 1689 struct sctp_authkey_event { 1690 uint16_t auth_type; 1691 uint16_t auth_flags; 1692 uint32_t auth_length; 1693 uint16_t auth_keynumber; 1694 uint16_t auth_altkeynumber; 1695 uint32_t auth_indication; 1696 sctp_assoc_t auth_assoc_id; 1697 }; 1699 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 1700 auth_flags: Currently unused. 1701 auth_length: This field is the total length of the notification 1702 data, including the notification header. It will generally be 1703 sizeof (struct sctp_authkey_event). 1704 auth_keynumber: This field holds the keynumber set by the user for 1705 the effected key. If more than one key is involved, this will 1706 contain one of the keys involved in the notification. 1707 auth_altkeynumber: This field holds an alternate keynumber which is 1708 used by some notifications. 1709 auth_indication: This field hold the error or indication being 1710 reported. The following values are currently defined: 1711 SCTP_AUTH_NEWKEY: This report indicates that a new key has been 1712 made active (used for the first time by the peer) and is now 1713 the active key. The auth_keynumber field holds the user 1714 specified key number. 1715 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 1716 support the SCTP-AUTH. 1717 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 1718 implementation will not use the key identifier specified in 1719 auth_keynumber anymore. 1720 auth_assoc_id: The association id field, holds the identifier for 1721 the association. All notifications for a given association have 1722 the same association identifier. 1724 6.3.10. SCTP_SENDER_DRY_EVENT 1726 When the SCTP implementation has no user data anymore to send or 1727 retransmit this notification is given to the user. If the user 1728 subscribes to this event and the SCTP has at this point of time no 1729 user data to send or retransmit this notification is also given to 1730 the user. 1732 struct sctp_sender_dry_event { 1733 uint16_t sender_dry_type; 1734 uint16_t sender_dry_flags; 1735 uint32_t sender_dry_length; 1736 sctp_assoc_t sender_dry_assoc_id; 1737 }; 1739 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 1740 sender_dry_flags: Currently unused. 1741 sender_dry_length: This field is the total length of the 1742 notification data, including the notification header. It will 1743 generally be sizeof (struct sctp_sender_dry_event). 1745 6.4. Ancillary Data Considerations and Semantics 1747 Programming with ancillary socket data contains some subtleties and 1748 pitfalls, which are discussed below. 1750 6.4.1. Multiple Items and Ordering 1752 Multiple ancillary data items may be included in any call to 1753 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1754 items, or both. 1756 The ordering of ancillary data items (either by SCTP or another 1757 protocol) is not significant and is implementation-dependent, so 1758 applications must not depend on any ordering. 1760 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1761 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1762 sendmsg() or recvmsg() call. 1764 6.4.2. Accessing and Manipulating Ancillary Data 1766 Applications can infer the presence of data or ancillary data by 1767 examining the msg_iovlen and msg_controllen msghdr members, 1768 respectively. 1770 Implementations may have different padding requirements for ancillary 1771 data, so portable applications should make use of the macros 1772 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1773 [RFC3542] and your SCTP implementation's documentation for more 1774 information. Following is an example, from [RFC3542], demonstrating 1775 the use of these macros to access ancillary data: 1777 struct msghdr msg; 1778 struct cmsghdr *cmsgptr; 1780 /* fill in msg */ 1782 /* call recvmsg() */ 1784 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1785 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1786 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1787 u_char *ptr; 1789 ptr = CMSG_DATA(cmsgptr); 1790 /* process data pointed to by ptr */ 1791 } 1792 } 1794 6.4.3. Control Message Buffer Sizing 1796 The information conveyed via SCTP_SNDRCV events will often be 1797 fundamental to the correct and sane operation of the sockets 1798 application. This is particularly true of the one-to-many semantics, 1799 but also of the one-ton-one semantics. For example, if an 1800 application needs to send and receive data on different SCTP streams, 1801 SCTP_SNDRCV events are indispensable. 1803 Given that some ancillary data is critical, and that multiple 1804 ancillary data items may appear in any order, applications should be 1805 carefully written to always provide a large enough buffer to contain 1806 all possible ancillary data that can be presented by recvmsg(). If 1807 the buffer is too small, and crucial data is truncated, it may pose a 1808 fatal error condition. 1810 Thus it is essential that applications be able to deterministically 1811 calculate the maximum required buffer size to pass to recvmsg(). One 1812 constraint imposed on this specification that makes this possible is 1813 that all ancillary data definitions are of a fixed length. One way 1814 to calculate the maximum required buffer size might be to take the 1815 sum the sizes of all enabled ancillary data item structures, as 1816 calculated by CMSG_SPACE. For example, if we enabled 1817 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1818 and allocate the buffer size as follows: 1820 size_t total; 1821 void *buf; 1823 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1824 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1826 buf = malloc(total); 1828 We could then use this buffer for msg_control on each call to 1829 recvmsg() and be assured that we would not lose any ancillary data to 1830 truncation. 1832 7. Common Operations for Both Styles 1834 7.1. send(), recv(), sendto(), and recvfrom() 1836 Applications can use send() and sendto() to transmit data to the peer 1837 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1838 data from the peer. 1840 The function prototypes are 1842 ssize_t send(int sd, 1843 const void *msg, 1844 size_t len, 1845 int flags); 1847 ssize_t sendto(int sd, 1848 const void *msg, 1849 size_t len, 1850 int flags, 1851 const struct sockaddr *to, 1852 socklen_t tolen); 1854 ssize_t recv(int sd, 1855 void *buf, 1856 size_t len, 1857 int flags); 1859 ssize_t recvfrom(int sd, 1860 void *buf, 1861 size_t len, 1862 int flags, 1863 struct sockaddr *from, 1864 socklen_t *fromlen); 1866 and the arguments are 1867 sd: The socket descriptor of an SCTP endpoint. 1868 msg: The message to be sent. 1869 len: the size of the message or the size of buffer. 1870 to: one of the peer addresses of the association to be used to send 1871 the message. 1872 tolen: The size of the address. 1873 buf: The buffer to store a received message. 1874 from: The buffer to store the peer address used to send the received 1875 message. 1876 fromlen: The size of the from address. 1877 flags: (described below). 1879 These calls give access to only basic SCTP protocol features. If 1880 either peer in the association uses multiple streams, or sends 1881 unordered data these calls will usually be inadequate, and may 1882 deliver the data in unpredictable ways. 1884 SCTP has the concept of multiple streams in one association. The 1885 above calls do not allow the caller to specify on which stream a 1886 message should be sent. The system uses stream 0 as the default 1887 stream for send() and sendto(). recv() and recvfrom() return data 1888 from any stream, but the caller can not distinguish the different 1889 streams. This may result in data seeming to arrive out of order. 1890 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1891 provide no indication. 1893 SCTP is message based. The msg buffer above in send() and sendto() 1894 is considered to be a single message. This means that if the caller 1895 wants to send a message which is composed by several buffers, the 1896 caller needs to combine them before calling send() or sendto(). 1897 Alternately, the caller can use sendmsg() to do that without 1898 combining them. Sending a message using send() or sendto() is atomic 1899 unless explicit EOR marking is enabled on the socket specified by sd. 1900 Using sendto() on a non-connected one-to-one style socket for 1901 implicit connection setup may or may not work depending on the SCTP 1902 implementation. recv() and recvfrom() cannot distinguish message 1903 boundaries. 1905 In receiving, if the buffer supplied is not large enough to hold a 1906 complete message, the receive call acts like a stream socket and 1907 returns as much data as will fit in the buffer. 1909 Note, the send() and recv() calls may not be used for a one-to-many 1910 style socket. 1912 Note, if an application calls a send function with no user data and 1913 no ancillary data the SCTP implementation should reject the request 1914 with an appropriate error message. An implementation is NOT allowed 1915 to send a Data chunk with no user data [RFC4960]. 1917 7.2. setsockopt() and getsockopt() 1919 Applications use setsockopt() and getsockopt() to set or retrieve 1920 socket options. Socket options are used to change the default 1921 behavior of sockets calls. They are described in Section 8. 1923 The function prototypes are 1925 int getsockopt(int sd, 1926 int level, 1927 int optname, 1928 void *optval, 1929 socklen_t *optlen); 1931 and 1933 int setsockopt(int sd, 1934 int level, 1935 int optname, 1936 const void *optval, 1937 socklen_t optlen); 1939 and the arguments are 1940 sd: The socket descriptor. 1941 level: Set to IPPROTO_SCTP for all SCTP options. 1942 optname - The option name. 1943 optval: The buffer to store the value of the option. 1944 optlen: The size of the buffer (or the length of the option 1945 returned). 1947 All socket options set on a 1-to-1 listening sockets also apply all 1948 accepted sockets. All socket options set on a 1-to-many socket using 1949 the assoc_id 0 applies for all future associations on the socket. 1951 7.3. read() and write() 1953 Applications can use read() and write() to send and receive data to 1954 and from peer. They have the same semantics as send() and recv() 1955 except that the flags parameter cannot be used. 1957 Note, these calls, when used in the one-to-many style, may only be 1958 used with branched off socket descriptors (see Section 9.2). 1960 7.4. getsockname() 1962 Applications use getsockname() to retrieve the locally-bound socket 1963 address of the specified socket. This is especially useful if the 1964 caller let SCTP chose a local port. This call is for where the 1965 endpoint is not multi-homed. It does not work well with multi-homed 1966 sockets. See Section 9.5 for a multi-homed version of the call. 1968 The function prototype is 1970 int getsockname(int sd, 1971 struct sockaddr *address, 1972 socklen_t *len); 1974 and the arguments are 1975 sd: The socket descriptor to be queried. 1976 address: On return, one locally bound address (chosen by the SCTP 1977 stack) is stored in this buffer. If the socket is an IPv4 socket, 1978 the address will be IPv4. If the socket is an IPv6 socket, the 1979 address will be either an IPv6 or IPv4 address. 1980 len: The caller should set the length of address here. On return, 1981 this is set to the length of the returned address. 1983 If the actual length of the address is greater than the length of the 1984 supplied sockaddr structure, the stored address will be truncated. 1986 If the socket has not been bound to a local name, the value stored in 1987 the object pointed to by address is unspecified. 1989 8. Socket Options 1991 The following sub-section describes various SCTP level socket options 1992 that are common to both styles. SCTP associations can be multi- 1993 homed. Therefore, certain option parameters include a 1994 sockaddr_storage structure to select which peer address the option 1995 should be applied to. 1997 For the one-to-many style sockets, an sctp_assoc_t structure 1998 (association ID) is used to identify the association instance that 1999 the operation affects. So it must be set when using this style. 2001 For the one-to-one style sockets and branched off one-to-many style 2002 sockets (see Section 9.2) this association ID parameter is ignored. 2004 Note that socket or IP level options are set or retrieved per socket. 2005 This means that for one-to-many style sockets, those options will be 2006 applied to all associations belonging to the socket. And for one-to- 2007 one style, those options will be applied to all peer addresses of the 2008 association controlled by the socket. Applications should be very 2009 careful in setting those options. 2011 For some IP stacks getsockopt() is read-only; so a new interface will 2012 be needed when information must be passed both in to and out of the 2013 SCTP stack. The syntax for sctp_opt_info() is 2015 int sctp_opt_info(int sd, 2016 sctp_assoc_t id, 2017 int opt, 2018 void *arg, 2019 socklen_t *size); 2021 The sctp_opt_info() call is a replacement for getsockopt() only and 2022 will not set any options associated with the specified socket. A 2023 setsockopt() must be used to set any writeable option. 2025 For one-to-many style sockets, id specifies the association to query. 2026 For one-to-one style sockets, id is ignored. 2028 opt specifies which SCTP socket option to get. It can get any socket 2029 option currently supported that requests information (either read/ 2030 write options or read only) such as: 2031 SCTP_RTOINFO 2032 SCTP_ASSOCINFO 2033 SCTP_DEFAULT_SEND_PARAM 2034 SCTP_GET_PEER_ADDR_INFO 2035 SCTP_PRIMARY_ADDR 2036 SCTP_PEER_ADDR_PARAMS 2037 SCTP_STATUS 2038 SCTP_CONTEXT 2039 SCTP_AUTH_ACTIVE_KEY 2040 SCTP_PEER_AUTH_CHUNKS 2041 SCTP_LOCAL_AUTH_CHUNKS 2043 arg is an option-specific structure buffer provided by the caller. 2044 See Section 9.5 subsections for more information on these options and 2045 option-specific structures. 2047 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2048 sets errno to the appropriate error code. 2050 All options that support specific settings on an association by 2051 filling in either an association id variable or a sockaddr_storage 2052 SHOULD also support setting of the same value for the entire endpoint 2053 (i.e. future associations). To accomplish this the following logic 2054 is used when setting one of these options: 2056 o If an address is specified via a sockaddr_storage that is included 2057 in the structure, the address is used to lookup the association 2058 and the settings are applied to the specific address (if 2059 appropriate) or to the entire association. 2060 o If an association identification is filled in but not a 2061 sockaddr_storage (if present), the association is found using the 2062 association identification and the settings should be applied to 2063 the entire association (since a specific address is not 2064 specified). Note this also applies to options that hold an 2065 association identification in their structure but do not have a 2066 sockaddr_storage field. 2067 o If neither the sockaddr_storage or association identification is 2068 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2069 the association identification is 0, the settings are a default 2070 and to be applied to the endpoint (all future associations). 2072 8.1. Read / Write Options 2074 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2076 The protocol parameters used to initialize and bound retransmission 2077 timeout (RTO) are tunable. See [RFC4960] for more information on how 2078 these parameters are used in RTO calculation. 2080 The following structure is used to access and modify these 2081 parameters: 2083 struct sctp_rtoinfo { 2084 sctp_assoc_t srto_assoc_id; 2085 uint32_t srto_initial; 2086 uint32_t srto_max; 2087 uint32_t srto_min; 2088 }; 2090 srto_initial: This contains the initial RTO value. 2091 srto_max and srto_min: These contain the maximum and minimum bounds 2092 for all RTOs. 2093 srto_assoc_id: This parameter is ignored for one-to-one style 2094 sockets. For one-to-many style sockets the following applies: 2095 This is filled in the application, and identifies the association 2096 for this query. If this parameter is '0', then the change affects 2097 the entire endpoint. 2099 All times are given in milliseconds. A value of 0, when modifying 2100 the parameters, indicates that the current value should not be 2101 changed. 2103 To access or modify these parameters, the application should call 2104 getsockopt or setsockopt() respectively with the option name 2105 SCTP_RTOINFO. 2107 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2109 This option is used to both examine and set various association and 2110 endpoint parameters. See [RFC4960] for more information on how this 2111 parameter is used. 2113 The following structure is used to access and modify this parameters: 2115 struct sctp_assocparams { 2116 sctp_assoc_t sasoc_assoc_id; 2117 uint16_t sasoc_asocmaxrxt; 2118 uint16_t sasoc_number_peer_destinations; 2119 uint32_t sasoc_peer_rwnd; 2120 uint32_t sasoc_local_rwnd; 2121 uint32_t sasoc_cookie_life; 2122 }; 2124 sasoc_assoc_id: This parameter is ignored for one-to-one style 2125 sockets. For one-to-many style sockets the following applies: 2126 This information may be examined for either the endpoint or a 2127 specific association. To examine a endpoints default parameters 2128 the association id (sasoc_assoc_id) should must be set to the 2129 value '0'. 2130 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2131 to make for the association. 2132 sasoc_number_peer_destinations: This is the number of destination 2133 addresses that the peer has. 2134 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2135 (reported in the last SACK) minus any outstanding data (i.e. data 2136 inflight). 2137 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2138 the peer. 2139 sasoc_cookie_life: This is the associations cookie life value used 2140 when issuing cookies. 2142 The values of the sasoc_peer_rwnd is meaningless when examining 2143 endpoint information. 2145 All time values are given in milliseconds. A value of 0, when 2146 modifying the parameters, indicates that the current value should not 2147 be changed. 2149 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2150 on either an endpoint or association basis. The rwnd and destination 2151 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2152 sasoc_local_rwnd) are NOT settable and any value placed in these is 2153 ignored. 2155 To access or modify these parameters, the application should call 2156 getsockopt or setsockopt() respectively with the option name 2157 SCTP_ASSOCINFO. 2159 The maximum number of retransmissions before an address is considered 2160 unreachable is also tunable, but is address-specific, so it is 2161 covered in a separate option. If an application attempts to set the 2162 value of the association maximum retransmission parameter to more 2163 than the sum of all maximum retransmission parameters, setsockopt() 2164 shall return an error. The reason for this, from [RFC4960] section 2165 8.2: 2167 Note: When configuring the SCTP endpoint, the user should avoid 2168 having the value of 'Association.Max.Retrans' larger than the 2169 summation of the 'Path.Max.Retrans' of all the destination addresses 2170 for the remote endpoint. Otherwise, all the destination addresses 2171 may become inactive while the endpoint still considers the peer 2172 endpoint reachable. 2174 8.1.3. Initialization Parameters (SCTP_INITMSG) 2176 Applications can specify protocol parameters for the default 2177 association initialization. The structure used to access and modify 2178 these parameters is defined in Section 6.2.1). The option name 2179 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2181 Setting initialization parameters is effective only on an unconnected 2182 socket (for one-to-many style sockets only future associations are 2183 effected by the change). With one-to-one style sockets, this option 2184 is inherited by sockets derived from a listener socket. 2186 8.1.4. SO_LINGER 2188 An application can use this option to perform the SCTP ABORT 2189 primitive. This option affects all associations related to the 2190 socket. 2192 The linger option structure is: 2194 struct linger { 2195 int l_onoff; /* option on/off */ 2196 int l_linger; /* linger time */ 2197 }; 2199 To enable the option, set l_onoff to 1. If the l_linger value is set 2200 to 0, calling close() is the same as the ABORT primitive. If the 2201 value is set to a negative value, the setsockopt() call will return 2202 an error. If the value is set to a positive value linger_time, the 2203 close() can be blocked for at most linger_time ms. If the graceful 2204 shutdown phase does not finish during this period, close() will 2205 return but the graceful shutdown phase continues in the system. 2207 Note, this is a socket level option NOT an SCTP level option. So 2208 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2209 setsockopt() call. 2211 8.1.5. SCTP_NODELAY 2213 Turn on/off any Nagle-like algorithm. This means that packets are 2214 generally sent as soon as possible and no unnecessary delays are 2215 introduced, at the cost of more packets in the network. Expects an 2216 integer boolean flag. 2218 8.1.6. SO_RCVBUF 2220 Sets receive buffer size in octets. For SCTP one-to-one style 2221 sockets, this controls the receiver window size. For one-to-many 2222 style sockets the meaning is implementation dependent. It might 2223 control the receive buffer for each association bound to the socket 2224 descriptor or it might control the receive buffer for the whole 2225 socket. The call expects an integer. 2227 8.1.7. SO_SNDBUF 2229 Sets send buffer size. For SCTP one-to-one style sockets, this 2230 controls the amount of data SCTP may have waiting in internal buffers 2231 to be sent. This option therefore bounds the maximum size of data 2232 that can be sent in a single send call. For one-to-many style 2233 sockets, the effect is the same, except that it applies to one or all 2234 associations (see Section 4.4) bound to the socket descriptor used in 2235 the setsockopt() or getsockopt() call. The option applies to each 2236 association's window size separately. The call expects an integer. 2238 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 2240 This socket option is applicable to the one-to-many style socket 2241 only. When set it will cause associations that are idle for more 2242 than the specified number of seconds to automatically close using the 2243 graceful shutdown procedure. An association being idle is defined as 2244 an association that has NOT sent or received user data. The special 2245 value of '0' indicates that no automatic close of any associations 2246 should be performed, this is the default value. The option expects 2247 an integer defining the number of seconds of idle time before an 2248 association is closed. 2250 An application using this option should enable receiving the 2251 association change notification. This is the only mechanism an 2252 application is informed about the closing of an association. After 2253 an association is closed, the association ID assigned to it can be 2254 reused. An application should be aware of this to avoid the possible 2255 problem of sending data to an incorrect peer end point. 2257 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 2259 Requests that the local SCTP stack use the enclosed peer address as 2260 the association primary. The enclosed address must be one of the 2261 association peer's addresses. 2263 The following structure is used to make a set peer primary request: 2265 struct sctp_setprim { 2266 sctp_assoc_t ssp_assoc_id; 2267 struct sockaddr_storage ssp_addr; 2268 }; 2270 ssp_addr: The address to set as primary. 2271 ssp_assoc_id: This parameter is ignored for one-to-one style 2272 sockets. For one-to-many style sockets it identifies the 2273 association for this request. 2275 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2277 Requests that the local endpoint set the specified Adaptation Layer 2278 Indication parameter for all future INIT and INIT-ACK exchanges. 2280 The following structure is used to access and modify this parameter: 2282 struct sctp_setadaptation { 2283 uint32_t ssb_adaptation_ind; 2284 }; 2286 ssb_adaptation_ind: The adaptation layer indicator that will be 2287 included in any outgoing Adaptation Layer Indication parameter. 2289 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 2291 This option is a on/off flag and is passed an integer where a non- 2292 zero is on and a zero is off. If enabled no SCTP message 2293 fragmentation will be performed. Instead if a message being sent 2294 exceeds the current PMTU size, the message will NOT be sent and 2295 instead a error will be indicated to the user. 2297 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2299 Applications can enable or disable heartbeats for any peer address of 2300 an association, modify an address's heartbeat interval, force a 2301 heartbeat to be sent immediately, and adjust the address's maximum 2302 number of retransmissions sent before an address is considered 2303 unreachable. 2305 The following structure is used to access and modify an address's 2306 parameters: 2308 struct sctp_paddrparams { 2309 sctp_assoc_t spp_assoc_id; 2310 struct sockaddr_storage spp_address; 2311 uint32_t ssp_hbinterval; 2312 uint16_t ssp_pathmaxrxt; 2313 uint32_t ssp_pathmtu; 2314 uint32_t ssp_flags; 2315 uint32_t ssp_ipv6_flowlabel; 2316 uint8_t ssp_ipv4_tos; 2317 }; 2319 spp_assoc_id: This parameter is ignored for one-to-one style 2320 sockets. For one-to-many style sockets it identifies the 2321 association for this query. 2322 spp_address: This specifies which address is of interest. 2323 ssp_hbinterval: This contains the value of the heartbeat interval, 2324 in milliseconds. Note that unless the spp_flag is set to 2325 SPP_HB_ENABLE the value of this field is ignored. Note also that 2326 a value of zero indicates the current setting should be left 2327 unchanged. To set an actual value of zero the use of the flag 2328 SPP_HB_TIME_IS_ZERO should be used. 2329 ssp_pathmaxrxt: This contains the maximum number of retransmissions 2330 before this address shall be considered unreachable. Note that a 2331 value of zero indicates the current setting should be left 2332 unchanged. 2333 ssp_pathmtu: When Path MTU discovery is disabled the value specified 2334 here will be the "fixed" path MTU (i.e. the value of the spp_flags 2335 field must include the flag SPP_PMTUD_DISABLE). Note that if the 2336 spp_address field is empty then all destinations for this 2337 association will have this fixed path MTU set upon them. If an 2338 address is specified, then only that address will be effected. 2339 Note also that this option cannot be set on the endpoint, but must 2340 be set on each individual association. Also, when disabling PMTU 2341 discovery, the implementation may disallow this behavior if the 2342 "fixed" path MTU is below the constant value SCTP_SMALLEST_PMTU. 2344 spp_ipv6_flowlabel: This field is used in conjunction with the 2345 SPP_IPV6_FLOWLABEL flag. 2346 spp_ipv4_tos: This field is used in conjunction with the 2347 SPP_IPV4_TOS flag. 2348 spp_flags: These flags are used to control various features on an 2349 association. The flag field is a bit mask which may contain zero 2350 or more of the following options: 2351 SPP_HB_ENABLE: Enable heartbeats on the specified address. Note 2352 that if the address field is empty all addresses for the 2353 association have heartbeats enabled upon them. 2354 SPP_HB_DISABLE: Disable heartbeats on the specified address. 2355 Note that if the address field is empty all addresses for the 2356 association will have their heartbeats disabled. Note also 2357 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2358 only one of these two should be specified. Enabling both 2359 fields will have undetermined results. 2360 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 2361 immediately. 2362 SPP_HB_TIME_IS_ZERO: Specify's that the time for heartbeat delay 2363 is to be set to the value of 0 milliseconds. 2364 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 2365 specified address. Note that if the address field is empty 2366 then all addresses on the association are effected. 2367 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 2368 the specified address. Note that if the address field is empty 2369 then all addresses on the association are effected. Note also 2370 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2371 exclusive. Enabling both will have undetermined results. 2372 SPP_IPV6_FLOWLABEL: Setting this flag enables setting of the IPV6 2373 flowlabel value associated with either the association or the 2374 specific address. If the address field is filled in, then the 2375 specific destination address has this value set upon it. If 2376 the association is specified, but not the address, then the 2377 flowlabel value is set for any future destination addresses 2378 that may be added. The value is obtained in the 2379 spp_ipv6_flowlabel field. 2381 Upon retrieval, this flag will be set to indicate that the 2382 spp_ipv6_flowlabel field has a valid value returned. If a 2383 specific destination addresses is set (in the spp_address 2384 field) when called then the value returned is that of the 2385 address. If just an association is specified (and no address) 2386 then the association default flowlabel is returned. If neither 2387 an association nor an destination is specified, then the 2388 sockets default flowlabel is returned. For non IPv6 sockets, 2389 then this flag will be left cleared. 2391 SPP_IPV4_TOS: Setting this flag enables setting of the IPV4 tos 2392 value associated with either the association or specific 2393 address. If the address field is filled in, then the specific 2394 destination address has this value set upon it. If the 2395 association is specified, but not the address, then the tos 2396 value is set for any future destination addresses that may be 2397 added. The value is obtained in the spp_ipv4_tos field. 2399 Upon retrieval, this flag will be set to indicate that the 2400 spp_ipv4_tos field has a valid value returned. If a specific 2401 destination addresses is set when called (in the spp_address 2402 field) then that specific destination addresses tos value is 2403 returned. If just an association is specified then the 2404 association default tos is returned. If neither an association 2405 nor an destination is specified, then the sockets default tos 2406 is returned. For non IPv4 sockets, then this flag will be left 2407 cleared. 2409 To read or modify these parameters, the application should call 2410 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2412 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 2414 Applications that wish to use the sendto() system call may wish to 2415 specify a default set of parameters that would normally be supplied 2416 through the inclusion of ancillary data. This socket option allows 2417 such an application to set the default sctp_sndrcvinfo structure. 2418 The application that wishes to use this socket option simply passes 2419 in to this call the sctp_sndrcvinfo structure defined in 2420 Section 6.2.2. The input parameters accepted by this call include 2421 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy 2422 and sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2423 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2424 specifies the association to apply the parameters to in a one-to-many 2425 style sockets. It is ignored on the one-to-one style. Note that 2426 setting the sinfo_assoc_id field to zero indicates that the users 2427 wishes to set the endpoint default send parameters for all future 2428 associations. 2430 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) 2432 This socket option is used to specify various notifications and 2433 ancillary data the user wishes to receive. Please see Section 8.4 2434 for a full description of this option and its usage. 2436 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2438 This socket option is a boolean flag which turns on or off mapped V4 2439 addresses. If this option is turned on and the socket is type 2440 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2441 If this option is turned off, then no mapping will be done of V4 2442 addresses and a user will receive both PF_INET6 and PF_INET type 2443 addresses on the socket. 2445 By default this option is turned off and expects an integer to be 2446 passed where non-zero turns on the option and zero turns off the 2447 option. 2449 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 2451 This option will get or set the maximum size to put in any outgoing 2452 SCTP DATA chunk. If a message is larger than this size it will be 2453 fragmented by SCTP into the specified size. Note that the underlying 2454 SCTP implementation may fragment into smaller sized chunks when the 2455 PMTU of the underlying association is smaller than the value set by 2456 the user. The default value for this option is '0' which indicates 2457 the user is NOT limiting fragmentation and only the PMTU will effect 2458 SCTP's choice of DATA chunk size. Note also that values set larger 2459 than the maximum size of an IP datagram will effectively let SCTP 2460 control fragmentation (i.e. the same as setting this option to 0). 2462 The following structure is used to access and modify this parameter: 2464 struct sctp_assoc_value { 2465 sctp_assoc_t assoc_id; 2466 uint32_t assoc_value; 2467 }; 2469 assoc_id: This parameter is ignored for one-to-one style sockets. 2470 For one-to-many style sockets this parameter indicates which 2471 association the user is performing an action upon. Note that if 2472 this field's value is zero then the endpoints default value is 2473 changed (effecting future associations only). 2474 assoc_value: This parameter specifies the maximum size in bytes. 2476 8.1.17. Get or Set the List of Supported HMAC Identifiers 2477 (SCTP_HMAC_IDENT) 2479 This option gets or sets the list of HMAC algorithms that the local 2480 endpoint requires the peer to use. 2482 The following structure is used to get or set these identifiers: 2484 struct sctp_hmacalgo { 2485 uint32_t shmac_number_of_idents; 2486 uint16_t shmac_idents[]; 2487 }; 2489 shmac_number_of_idents: This field gives the number of elements 2490 present in the array shmac_idents. 2491 shmac_idents: This parameter contains an array of HMAC Identifiers 2492 that the local endpoint is requesting the peer to use, in priority 2493 order. The following identifiers are valid: 2494 * SCTP_AUTH_HMAC_ID_SHA1 2495 * SCTP_AUTH_HMAC_ID_SHA256 2497 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 2498 may include any of the other values in its preferred order (lowest 2499 list position has the most preference in algorithm selection). Note 2500 also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion of an 2501 unknown HMAC identifier (including optional identifiers unknown to 2502 the implementation) will cause the set option to fail and return an 2503 error. 2505 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 2507 This option will get or set the active shared key to be used to build 2508 the association shared key. 2510 The following structure is used to access and modify these 2511 parameters: 2513 struct sctp_authkeyid { 2514 sctp_assoc_t scact_assoc_id; 2515 uint16_t scact_keynumber; 2516 }; 2518 scact_assoc_id: This parameter, if non-zero, indicates what 2519 association that the shared key identifier is being set active 2520 upon. Note that if this element contains zero, then the 2521 activation applies to the endpoint and all future associations 2522 will use the specified shared key identifier. For one-to-one 2523 sockets, this parameter is ignored. Note, however, that this 2524 option will set the active key on the association if the socket is 2525 connected, otherwise this will set the default active key for the 2526 endpoint. 2527 scact_keynumber: This parameter is the shared key identifier which 2528 the application is requesting to become the active shared key to 2529 be used for sending authenticated chunks. The key identifier MUST 2530 correspond to an existing shared key. Note that shared key 2531 identifier '0' defaults to a null key. 2533 When used with setsockopt() the SCTP implementation MUST use the 2534 indicated shared key identifier for all messages being given to an 2535 SCTP implementation via a send call after the setsockopt() call until 2536 changed again. Therefore the SCTP implementation MUST NOT bundle 2537 user messages which should be authenticated using different shared 2538 key identifiers. 2540 Initially the key with key identifier 0 is the active key. 2542 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 2544 This option will effect the way delayed acks are performed. This 2545 option allows you to get or set the delayed ack time, in 2546 milliseconds. It also allows changing the delayed ack frequency. 2547 Changing the frequency to 1 disables the delayed sack algorithm. If 2548 the sack_assoc_id is 0, then this sets or gets the endpoints default 2549 values. If the sack_assoc_id field is non-zero, then the set or get 2550 effects the specified association for the one to many model (the 2551 assoc_id field is ignored by the one to one model). Note that if 2552 sack_delay or sack_freq are 0 when setting this option, then the 2553 current values will remain unchanged. 2555 The following structure is used to access and modify these 2556 parameters: 2558 struct sctp_sack_info { 2559 sctp_assoc_t sack_assoc_id; 2560 uint32_t sack_delay; 2561 uint32_t sack_freq; 2562 }; 2564 sack_assoc_id: This parameter is ignored for one-to-one style 2565 sockets. For one-to-many style sockets this parameter indicates 2566 which association the user is performing an action upon. Note 2567 that if this field's value is zero then the endpoints default 2568 value is changed (effecting future associations only). 2569 sack_delay: This parameter contains the number of milliseconds that 2570 the user is requesting the delayed ACK timer be set to. Note that 2571 this value is defined in the standard to be between 200 and 500 2572 milliseconds. 2573 sack_freq: This parameter contains the number of packets that must 2574 be received before a sack is sent without waiting for the delay 2575 timer to expire. The default value for this is 2, setting this 2576 value to 1 will disable the delayed sack algorithm. 2578 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 2580 Fragmented interleave controls how the presentation of messages 2581 occurs for the message receiver. There are three levels of fragment 2582 interleave defined. Two of the levels effect the one-to-one model, 2583 while the one-to-many model is effected by all three levels. 2585 This option takes an integer value. It can be set to a value of 0, 1 2586 or 2. Attempting to set this level to other values will return an 2587 error. 2589 Setting the three levels provides the following receiver 2590 interactions: 2592 level 0: Prevents the interleaving of any messages. This means that 2593 when a partial delivery begins, no other messages will be received 2594 except the message being partially delivered. If another message 2595 arrives on a different stream (or association) that could be 2596 delivered, it will be blocked waiting for the user to read all of 2597 the partially delivered message. 2598 level 1: Allows interleaving of messages that are from different 2599 associations. For the one-to-one model, level 0 and level 1 thus 2600 have the same meaning since a one-to-one socket always receives 2601 messages from the same association. Note that setting the one-to- 2602 many model to this level may cause multiple partial delivers from 2603 different associations but for any given association, only one 2604 message will be delivered until all parts of a message have been 2605 delivered. This means that one large message, being read with an 2606 association identification of "X", will block other messages from 2607 association "X" from being delivered. 2608 level 2: Allows complete interleaving of messages. This level 2609 requires that the sender carefully observe not only the peer 2610 association identification (or address) but also must pay careful 2611 attention to the stream number. With this option enabled a 2612 partially delivered message may begin being delivered for 2613 association "X" stream "Y" and the next subsequent receive may 2614 return a message from association "X" stream "Z". Note that no 2615 other messages would be delivered for association "X" stream "Y" 2616 until all of stream "Y"'s partially delivered message was read. 2617 Note that this option also effects the one-to-one model. Also 2618 note that for the one-to-many model not only may another streams 2619 message from the same association be delivered from the next 2620 receive, some other associations message may be delivered upon the 2621 next receive. 2623 An implementation should default the one-to-many model to level 1. 2624 The reason for this is that otherwise it is possible that a peer 2625 could begin sending a partial message and thus block all other peers 2626 from sending data. However a setting of level 2 requires the 2627 application to not only be aware of the association (via the 2628 association id or peers address) but also the stream number. The 2629 stream number is NOT present unless the user has subscribed to the 2630 sctp_data_io_events (see Section 8.4). This is also why we recommend 2631 that the one-to-one model be defaulted to level 0 (level 1 for the 2632 one-to-one model has no effect). Note that an implementation should 2633 return an error if a application attempts to set the level to 2 and 2634 has NOT subscribed to the sctp_data_io_events. 2636 8.1.21. Set or Get the SCTP Partial Delivery Point 2637 (SCTP_PARTIAL_DELIVERY_POINT) 2639 This option will set or get the SCTP partial delivery point. This 2640 point is the size of a message where the partial delivery API will be 2641 invoked to help free up rwnd space for the peer. Setting this to a 2642 lower value will cause partial deliveries to happen more often. The 2643 calls argument is an integer that sets or gets the partial delivery 2644 point. Note also that the call will fail if the user attempts to set 2645 this value larger than the socket receive buffer size. 2647 Note that any single message having a length smaller than or equal to 2648 the SCTP partial delivery point will be delivered in one single read 2649 call as long as the user provided buffer is large enough to hold the 2650 message. 2652 8.1.22. Set or Get the Use of Extended Receive Info 2653 (SCTP_USE_EXT_RCVINFO) 2655 This option will enable or disable the use of the extended version of 2656 the sctp_sndrcvinfo structure. If this option is disabled, then the 2657 normal sctp_sndrcvinfo structure is returned in all receive message 2658 calls. If this option is enabled then the sctp_extrcvinfo structure 2659 is returned in all receive message calls. 2661 Note that the sctp_extrcvinfo structure is never used in any send 2662 call. 2664 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 2666 This option will enable or disable the use of the automatic 2667 generation of ASCONF chunks to add and delete addresses to an 2668 existing association. Note that this option has two caveats namely: 2669 a) it only effects sockets that are bound to all addresses on the 2670 machine, and b) the system administrator may have an overriding 2671 control that turns the ASCONF feature off no matter what setting the 2672 socket option may have. 2674 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 2676 This option will allow a user to change the maximum burst of packets 2677 that can be emitted by this association. Note that the default value 2678 is 4, and some implementations may restrict this setting so that it 2679 can only be lowered. 2681 To set or get this option the user fills in the following structure: 2683 struct sctp_assoc_value { 2684 sctp_assoc_t assoc_id; 2685 uint32_t assoc_value; 2686 }; 2688 assoc_id: This parameter is ignored for one-to-one style sockets. 2689 For one-to-many style sockets this parameter indicates which 2690 association the user is performing an action upon. Note that if 2691 this field's value is zero then the endpoints default value is 2692 changed (effecting future associations only). 2693 assoc_value: This parameter contains the maximum burst. 2695 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 2697 The context field in the sctp_sndrcvinfo structure is normally only 2698 used when a failed message is retrieved holding the value that was 2699 sent down on the actual send call. This option allows the setting of 2700 a default context on an association basis that will be received on 2701 reading messages from the peer. This is especially helpful in the 2702 one-2-many model for an application to keep some reference to an 2703 internal state machine that is processing messages on the 2704 association. Note that the setting of this value only effects 2705 received messages from the peer and does not effect the value that is 2706 saved with outbound messages. 2708 To set or get this option the user fills in the following structure: 2710 struct sctp_assoc_value { 2711 sctp_assoc_t assoc_id; 2712 uint32_t assoc_value; 2713 }; 2715 assoc_id: This parameter is ignored for one-to-one style sockets. 2716 For one-to-many style sockets this parameter indicates which 2717 association the user is performing an action upon. Note that if 2718 this field's value is zero then the endpoints default value is 2719 changed (effecting future associations only). 2721 assoc_value: This parameter contains the context. 2723 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 2725 This boolean flag is used to enable or disable explicit end of record 2726 (EOR) marking. When this option is enabled, a user may make multiple 2727 send system calls to send a record and must indicate that they are 2728 finished sending a particular record by including on the send the 2729 SCTP_EOR flag. If this boolean flag is disabled then each individual 2730 send system call is considered to have a SCTP_EOR indicator set on it 2731 implicitly without the user having to explicitly add this flag. 2733 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 2735 This option only supports one-to-one style SCTP sockets. If used on 2736 a one-to-many style SCTP socket an error is indicated. 2738 The setsockopt() call MUST NOT be used after calling bind() or 2739 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 2740 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 2741 SCTP sockets bound to the same port MUST have set the 2742 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 2743 having set the SCTP_REUSE_PORT option will fail if there are other 2744 sockets bound to the same port. At most one socket being bound to 2745 the same port may be listening. 2747 It should be noted that the behaviour of the socket level socket 2748 option to reuse ports and/or addresses for SCTP sockets is 2749 unspecified. 2751 8.2. Read-Only Options 2753 The options defined in this subsection are read-only. Using this 2754 option in a setsockopt() call will result in a error indicating 2755 EOPNOTSUPP. 2757 8.2.1. Association Status (SCTP_STATUS) 2759 Applications can retrieve current status information about an 2760 association, including association state, peer receiver window size, 2761 number of unacked data chunks, and number of data chunks pending 2762 receipt. This information is read-only. 2764 The following structure is used to access this information: 2766 struct sctp_status { 2767 sctp_assoc_t sstat_assoc_id; 2768 int32_t sstat_state; 2769 uint32_t sstat_rwnd; 2770 uint16_t sstat_unackdata; 2771 uint16_t sstat_penddata; 2772 uint16_t sstat_instrms; 2773 uint16_t sstat_outstrms; 2774 uint32_t sstat_fragmentation_point; 2775 struct sctp_paddrinfo sstat_primary; 2776 }; 2778 sstat_assoc_id: This parameter is ignored for one-to-one style 2779 sockets. For one-to-many style sockets it holds the identifier 2780 for the association. All notifications for a given association 2781 have the same association identifier. 2782 sstat_state: This contains the association's current state one of 2783 the following values: 2784 * SCTP_CLOSED 2785 * SCTP_BOUND 2786 * SCTP_LISTEN 2787 * SCTP_COOKIE_WAIT 2788 * SCTP_COOKIE_ECHOED 2789 * SCTP_ESTABLISHED 2790 * SCTP_SHUTDOWN_PENDING 2791 * SCTP_SHUTDOWN_SENT 2792 * SCTP_SHUTDOWN_RECEIVED 2793 * SCTP_SHUTDOWN_ACK_SENT 2794 sstat_rwnd: This contains the association peer's current receiver 2795 window size. 2796 sstat_unackdata: This is the number of unacked data chunks. 2797 sstat_penddata: This is the number of data chunks pending receipt. 2798 sstat_primary: This is information on the current primary peer 2799 address. 2800 sstat_instrms: The number of streams that the peer will be using 2801 inbound. 2802 sstat_outstrms: The number of streams that the endpoint is allowed 2803 to use outbound. 2804 sstat_fragmentation_point - The size at which SCTP fragmentation 2805 will occur. 2807 To access these status values, the application calls getsockopt() 2808 with the option name SCTP_STATUS. 2810 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2812 Applications can retrieve information about a specific peer address 2813 of an association, including its reachability state, congestion 2814 window, and retransmission timer values. This information is read- 2815 only. 2817 The following structure is used to access this information: 2819 struct sctp_paddrinfo { 2820 sctp_assoc_t spinfo_assoc_id; 2821 struct sockaddr_storage spinfo_address; 2822 int32_t spinfo_state; 2823 uint32_t spinfo_cwnd; 2824 uint32_t spinfo_srtt; 2825 uint32_t spinfo_rto; 2826 uint32_t spinfo_mtu; 2827 }; 2829 spinfo_assoc_id: This is parameter is ignored for one-to-one style 2830 sockets. For one-to-many style sockets the following applies: 2831 This is field may be filled in by the application, if so, this 2832 field will have priority in looking up the association over the 2833 address specified in spinfo_address. Note that if the address 2834 does not belong to the association specified then this call will 2835 fail. If the application does NOT fill in the spinfo_assoc_id, 2836 then the address will be used to lookup the association and on 2837 return this field will have the valid association id. In other 2838 words, this call can be used to translate a address into an 2839 association id. 2840 spinfo_address: This is filled in the application, and contains the 2841 peer address of interest. 2842 spinfo_state: This contains the peer addresses's state (either 2843 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 2844 SCTP_UNCONFIRMED). 2845 spinfo_cwnd: This contains the peer addresses's current congestion 2846 window. 2847 spinfo_srtt: This contains the peer addresses's current smoothed 2848 round-trip time calculation in milliseconds. 2849 spinfo_rto: This contains the peer addresses's current 2850 retransmission timeout value in milliseconds. 2851 spinfo_mtu: The current P-MTU of this address. 2853 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 2854 (SCTP_PEER_AUTH_CHUNKS) 2856 This option gets a list of chunks for a specified association that 2857 the peer requires to be received authenticated only. 2859 The following structure is used to access these parameters: 2861 struct sctp_authchunks { 2862 sctp_assoc_t gauth_assoc_id; 2863 guint32_t gauth_number_of_chunks 2864 uint8_t gauth_chunks[]; 2865 }; 2867 gauth_assoc_id: This parameter, indicates which association the user 2868 is requesting the list of peer authenticated chunks. For one-to- 2869 one sockets, this parameter is ignored. 2870 gauth_number_of_chunks: This parameter gives the number of elements 2871 in the array gauth_chunks. 2872 gauth_chunks: This parameter contains an array of chunks that the 2873 peer is requesting to be authenticated. 2875 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 2876 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 2878 This option gets a list of chunks for a specified association that 2879 the local endpoint requires to be received authenticated only. 2881 The following structure is used to access these parameters: 2883 struct sctp_authchunks { 2884 sctp_assoc_t gauth_assoc_id; 2885 uint32_t gauth_number_of_chunks; 2886 uint8_t gauth_chunks[]; 2887 }; 2889 gauth_assoc_id: This parameter, indicates which association the user 2890 is requesting the list of local authenticated chunks. For one-to- 2891 one sockets, this parameter is ignored. 2892 gauth_number_of_chunks: This parameter gives the number of elements 2893 in the array gauth_chunks. 2894 gauth_chunks: This parameter contains an array of chunks that the 2895 local endpoint is requesting to be authenticated. 2897 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 2899 This option gets the current number of associations that are attached 2900 to a one-to-many style socket. The option value is an uint32_t. 2902 8.2.6. Get the Current Identifiers of Associations 2903 (SCTP_GET_ASSOC_ID_LIST) 2905 This option gets the current list of SCTP association identifiers of 2906 the SCTP associations handled by a one-to-many style socket. 2908 The option value has the structure 2909 struct sctp_assoc_ids { 2910 uint32_t gaids_number_of_ids; 2911 sctp_assoc_t gaids_assoc_id[]; 2912 }; 2914 The caller MUST provide a large enough buffer to hold all association 2915 identifiers. If the buffer is too small, an error MUST be returned. 2916 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 2917 idea how large the buffer has to be. gaids_number_of_ids gives the 2918 number of elements in the array gaids_assoc_id. 2920 8.3. Write-Only Options 2922 The options defined in this subsection are write-only. Using this 2923 option in a getsockopt() or sctp_opt_info() call will result in a 2924 error indicating EOPNOTSUPP. 2926 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2928 Requests that the peer mark the enclosed address as the association 2929 primary. The enclosed address must be one of the association's 2930 locally bound addresses. 2932 The following structure is used to make a set peer primary request: 2934 struct sctp_setpeerprim { 2935 sctp_assoc_t sspp_assoc_id; 2936 struct sockaddr_storage sspp_addr; 2937 }; 2939 sspp_addr: The address to set as primary. 2940 sspp_assoc_id: This parameter is ignored for one-to-one style 2941 sockets. For one-to-many style sockets it identifies the 2942 association for this request. 2944 8.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 2946 This set option adds a chunk type that the user is requesting to be 2947 received only in an authenticated way. Changes to the list of chunks 2948 will only effect future associations on the socket. 2950 The following structure is used to add a chunk: 2952 struct sctp_authchunk { 2953 uint8_t sauth_chunk; 2954 }; 2955 sauth_chunk: This parameter contains a chunk type that the user is 2956 requesting to be authenticated. 2958 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 2959 chunks MUST NOT be used. If they are used, an error MUST be 2960 returned. The usage of this option enables SCTP-AUTH in cases where 2961 it is not required by other means (for example the use of dynamic 2962 address reconfiguration). 2964 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 2966 This option will set a shared secret key which is used to build an 2967 association shared key. 2969 The following structure is used to access and modify these 2970 parameters: 2972 struct sctp_authkey { 2973 sctp_assoc_t sca_assoc_id; 2974 uint16_t sca_keynumber; 2975 uint16_t sca_keylength; 2976 uint8_t sca_key[]; 2977 }; 2979 sca_assoc_id: This parameter, if non-zero, indicates what 2980 association that the shared key is being set upon. Note that if 2981 this element contains zero, then the shared key is set upon the 2982 endpoint and all future associations will use this key (if not 2983 changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one 2984 sockets, this parameter is ignored. Note, however, that this 2985 option will set a key on the association if the socket is 2986 connected, otherwise this will set a key on the endpoint. 2987 sca_keynumber: This parameter is the shared key identifier by which 2988 the application will refer to this key. If a key of the specified 2989 index already exists, then this new key will replace the old 2990 existing key. Note that shared key identifier '0' defaults to a 2991 null key. 2992 sca_keylength: This parameter is the length of the array sca_key. 2993 sca_key: This parameter contains an array of bytes that is to be 2994 used by the endpoint (or association) as the shared secret key. 2995 Note, if the length of this field is zero, a null key is set. 2997 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 2999 This set option indicates that the application will not send user 3000 messages anymore requiring the usage of the indicated key identifier. 3002 struct sctp_authkeyid { 3003 sctp_assoc_t scact_assoc_id; 3004 uint16_t scact_keynumber; 3005 }; 3007 scact_assoc_id: This parameter, if non-zero, indicates what 3008 association that the shared key identifier is being deactivated. 3009 Note that if this element contains zero, then the shared key is 3010 deactivated for the endpoint and all associations will no longer 3011 use the specified shared key identifier (unless otherwise set on 3012 the association using SCTP_AUTH_KEY). For one-to-one sockets, 3013 this parameter is ignored. Note, however, that this option will 3014 deactivate the key from the association if the socket is 3015 connected, otherwise this will deactivate the key from the 3016 endpoint. 3017 scact_keynumber: This parameter is the shared key identifier which 3018 the application is requesting to be deactivated. The key 3019 identifier MUST correspond to an existing shared key. Note if 3020 this parameter is zero, use of the null key identifier '0' is 3021 deactivated on the endpoint and/or association. 3023 The currently active key can not be deactivated. 3025 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3027 This set option will delete a shared secret key in the SCTP 3028 implementation. 3030 struct sctp_authkeyid { 3031 sctp_assoc_t scact_assoc_id; 3032 uint16_t scact_keynumber; 3033 }; 3035 scact_assoc_id: This parameter, if non-zero, indicates what 3036 association that the shared key identifier is being deleted from. 3037 Note that if this element contains zero, then the shared key is 3038 deleted from the endpoint and all associations will no longer use 3039 the specified shared key identifier (unless otherwise set on the 3040 association using SCTP_AUTH_KEY). For one-to-one sockets, this 3041 parameter is ignored. Note, however, that this option will delete 3042 the key from the association if the socket is connected, otherwise 3043 this will delete the key from the endpoint. 3044 scact_keynumber: This parameter is the shared key identifier which 3045 the application is requesting to be deleted. The key identifier 3046 MUST correspond to an existing shared key and MUST NOT be in use 3047 for any packet being sent by the SCTP implementation. This means 3048 in particular, that it MUST be deactivated first. Note if this 3049 parameter is zero, use of the null key identifier '0' is deleted 3050 from the endpoint and/or association. 3052 Only deactivated keys which are no longer used by the kernel can be 3053 deleted. 3055 8.4. Ancillary Data and Notification Interest Options 3057 Applications can receive per-message ancillary information and 3058 notifications of certain SCTP events with recvmsg(). 3060 The following optional information is available to the application: 3061 SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3062 stream number, TSN, SSN, etc. described in Section 6.2.2) 3063 SCTP_ASSOC_CHANGE (sctp_association_event): described in 3064 Section 6.3.2 3065 SCTP_PEER_ADDR_CHANGE (sctp_address_event): described in 3066 Section 6.3.3 3067 SCTP_SEND_FAILED (sctp_send_failure_event): described in 3068 Section 6.3.5 3069 SCTP_REMOTE_ERROR (sctp_peer_error_event): described in 3070 Section 6.3.4 3071 SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): described in 3072 Section 6.3.6 3073 SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): described 3074 in Section 6.3.8 3075 SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): described 3076 in Section 6.3.7 3077 SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event): 3078 described in Section 6.3.9) 3079 SCTP_SENDER_DRY_EVENT (sctp_sender_dry_event): described in 3080 Section 6.3.10 3082 To receive any ancillary data or notifications, first the application 3083 registers its interest by calling the SCTP_EVENTS setsockopt() with 3084 the following structure: 3086 struct sctp_event_subscribe{ 3087 uint8_t sctp_data_io_event; 3088 uint8_t sctp_association_event; 3089 uint8_t sctp_address_event; 3090 uint8_t sctp_send_failure_event; 3091 uint8_t sctp_peer_error_event; 3092 uint8_t sctp_shutdown_event; 3093 uint8_t sctp_partial_delivery_event; 3094 uint8_t sctp_adaptation_layer_event; 3095 uint8_t sctp_authentication_event; 3096 uint8_t sctp_sender_dry_event; 3097 }; 3098 sctp_data_io_event: Setting this flag to 1 will cause the reception 3099 of SCTP_SNDRCV information on a per message basis. The 3100 application will need to use the recvmsg() interface so that it 3101 can receive the event information contained in the msg_control 3102 field. Setting the flag to 0 will disable reception of the 3103 message control information. 3104 sctp_association_event: Setting this flag to 1 will enable the 3105 reception of association event notifications. Setting the flag to 3106 0 will disable association event notifications. 3107 sctp_address_event: Setting this flag to 1 will enable the reception 3108 of address event notifications. Setting the flag to 0 will 3109 disable address event notifications. 3110 sctp_send_failure_event: Setting this flag to 1 will enable the 3111 reception of send failure event notifications. Setting the flag 3112 to 0 will disable send failure event notifications. 3113 sctp_peer_error_event: Setting this flag to 1 will enable the 3114 reception of peer error event notifications. Setting the flag to 3115 0 will disable peer error event notifications. 3116 sctp_shutdown_event: Setting this flag to 1 will enable the 3117 reception of shutdown event notifications. Setting the flag to 0 3118 will disable shutdown event notifications. 3119 sctp_partial_delivery_event: Setting this flag to 1 will enable the 3120 reception of partial delivery notifications. Setting the flag to 3121 0 will disable partial delivery event notifications. 3122 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 3123 reception of adaptation layer notifications. Setting the flag to 3124 0 will disable adaptation layer event notifications. 3125 sctp_authentication_event: Setting this flag to 1 will enable the 3126 reception of authentication layer notifications. Setting the flag 3127 to 0 will disable authentication layer event notifications. 3128 sctp_sender_dry_event: Setting this flag to 1 will enable the 3129 reception of sender dry notifications. Setting the flag to 0 will 3130 disable sender dry event notifications. 3132 An example where an application would like to receive data io events 3133 and association events but no others would be as follows: 3135 { 3136 struct sctp_event_subscribe event; 3138 memset(&event,0,sizeof(event)); 3140 event.sctp_data_io_event = 1; 3141 event.sctp_association_event = 1; 3143 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3144 } 3145 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3146 receives ancillary data and notifications for ALL associations bound 3147 to the file descriptor. For one-to-one style SCTP sockets, the 3148 caller receives ancillary data and notifications for only the single 3149 association bound to the file descriptor. 3151 By default both the one-to-one style and one-to-many style socket has 3152 all options off. 3154 9. New Functions 3156 Depending on the system, the following interface can be implemented 3157 as a system call or library function. 3159 9.1. sctp_bindx() 3161 This function allows the user to bind a specific subset of addresses 3162 or, if the SCTP extension described in [RFC5061] is supported, add or 3163 delete specific addresses. 3165 The function prototype is 3167 int sctp_bindx(int sd, 3168 struct sockaddr *addrs, 3169 int addrcnt, 3170 int flags); 3172 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3173 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3174 or IPv6 addresses. 3176 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3177 Section 4.1.2 for this usage. 3179 addrs is a pointer to an array of one or more socket addresses. Each 3180 address is contained in its appropriate structure. For an IPv6 3181 socket, an array of sockaddr_in6 would be returned. For a IPv4 3182 socket, an array of sockaddr_in would be returned. The caller 3183 specifies the number of addresses in the array with addrcnt. Note 3184 that the wildcard addresses cannot be used in combination with non 3185 wildcard addresses on a socket with this function, doing so will 3186 result in an error. 3188 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3189 -1, and sets errno to the appropriate error code. 3191 For SCTP, the port given in each socket address must be the same, or 3192 sctp_bindx() will fail, setting errno to EINVAL. 3194 The flags parameter is formed from the bitwise OR of zero or more of 3195 the following currently defined flags: 3196 o SCTP_BINDX_ADD_ADDR 3197 o SCTP_BINDX_REM_ADDR 3198 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3199 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3200 addresses from the association. The two flags are mutually 3201 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3202 caller may not remove all addresses from an association; sctp_bindx() 3203 will reject such an attempt with EINVAL. 3205 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3206 additional addresses with an endpoint after calling bind(). Or use 3207 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3208 socket is associated with so that no new association accepted will be 3209 associated with those addresses. If the endpoint supports dynamic 3210 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 3211 endpoint to send the appropriate message to the peer to change the 3212 peers address lists. 3214 Adding and removing addresses from a connected association is 3215 optional functionality. Implementations that do not support this 3216 functionality should return EOPNOTSUPP. 3218 sctp_bindx() can be called on an already bound socket or on an 3219 unbound socket. If the socket is unbound and the first port number 3220 in the addrs is zero, the kernel will chose a port number. All port 3221 numbers after the first one being 0 MUST also be zero. If the first 3222 port number is not zero, the following port numbers MUST be zero or 3223 have the same value as the first one. For an already bound socket, 3224 all port numbers provided MUST be the bound one or 0. 3226 sctp_bindx() is an atomic operation. Therefore the binding will be 3227 either successful on all addresses or fail on all addresses. If 3228 multiple addresses are provided and the sctp_bindx() call fails there 3229 is no indication which address is responsible for the failure. The 3230 only way to get an specific error indication is to call sctp_bindx() 3231 with only one address sequentially. 3233 9.2. sctp_peeloff() 3235 After an association is established on a one-to-many style socket, 3236 the application may wish to branch off the association into a 3237 separate socket/file descriptor. 3239 This is particularly desirable when, for instance, the application 3240 wishes to have a number of sporadic message senders/receivers remain 3241 under the original one-to-many style socket but branch off those 3242 associations carrying high volume data traffic into their own 3243 separate socket descriptors. 3245 The application uses sctp_peeloff() call to branch off an association 3246 into a separate socket (Note the semantics are somewhat changed from 3247 the traditional one-to-one style accept() call). Note that the new 3248 socket is a one-to-one style socket. Thus it will be confined to 3249 operations allowed for a one-to-one style socket. 3251 The function prototype is 3253 int sctp_peeloff(int sd, 3254 sctp_assoc_t assoc_id); 3256 and the arguments are 3257 sd: The original one-to-many style socket descriptor returned from 3258 the socket() system call (see Section 4.1.1). 3259 assoc_id: the specified identifier of the association that is to be 3260 branched off to a separate file descriptor (Note, in a traditional 3261 one-to-one style accept() call, this would be an out parameter, 3262 but for the one-to-many style call, this is an in parameter). 3263 The function returns a non-negative file descriptor representing the 3264 branched-off association, or -1 if an error occurred. The variable 3265 errno is then set appropriately. 3267 9.3. sctp_getpaddrs() 3269 sctp_getpaddrs() returns all peer addresses in an association. 3271 The function protoype is: 3273 int sctp_getpaddrs(int sd, 3274 sctp_assoc_t id, 3275 struct sockaddr **addrs); 3277 On return, addrs will point to an array dynamically allocated 3278 sockaddr structures of the appropriate type for the socket type. The 3279 caller should use sctp_freepaddrs() to free the memory. Note that 3280 the in/out parameter addrs must not be NULL. 3282 If sd is an IPv4 socket, the addresses returned will be all IPv4 3283 addresses. If sd is an IPv6 socket, the addresses returned can be a 3284 mix of IPv4 or IPv6 addresses. 3286 For one-to-many style sockets, id specifies the association to query. 3287 For one-to-one style sockets, id is ignored. 3289 On success, sctp_getpaddrs() returns the number of peer addresses in 3290 the association. If there is no association on this socket, 3291 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3292 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3293 is undefined. 3295 9.4. sctp_freepaddrs() 3297 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 3299 The function prototype is 3301 void sctp_freepaddrs(struct sockaddr *addrs); 3303 and addrs is the array of peer addresses returned by 3304 sctp_getpaddrs(). 3306 9.5. sctp_getladdrs() 3308 sctp_getladdrs() returns all locally bound address(es) on a socket. 3310 The function prototype is 3312 int sctp_getladdrs(int sd, 3313 sctp_assoc_t id, 3314 struct sockaddr **ss); 3316 On return, addrs will point to a dynamically allocated array of 3317 sockaddr structures of the appropriate type for the socket type. The 3318 caller should use sctp_freeladdrs() to free the memory. Note that 3319 the in/out parameter addrs must not be NULL. 3321 If sd is an IPv4 socket, the addresses returned will be all IPv4 3322 addresses. If sd is an IPv6 socket, the addresses returned can be a 3323 mix of IPv4 or IPv6 addresses. 3325 For one-to-many style sockets, id specifies the association to query. 3326 For one-to-one style sockets, id is ignored. 3328 If the id field is set to the value '0' then the locally bound 3329 addresses are returned without regard to any particular association. 3331 On success, sctp_getladdrs() returns the number of local addresses 3332 bound to the socket. If the socket is unbound, sctp_getladdrs() 3333 returns 0, and the value of *addrs is undefined. If an error occurs, 3334 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3336 9.6. sctp_freeladdrs() 3338 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 3340 The function prototype is 3342 void sctp_freeladdrs(struct sockaddr *addrs); 3344 and addrs is the array of peer addresses returned by 3345 sctp_getladdrs(). 3347 9.7. sctp_sendmsg() 3349 An implementation may provide a library function (or possibly system 3350 call) to assist the user with the advanced features of SCTP. 3352 The function prototype is 3354 ssize_t sctp_sendmsg(int sd, 3355 const void *msg, 3356 size_t len, 3357 const struct sockaddr *to, 3358 socklen_t tolen, 3359 uint32_t ppid, 3360 uint32_t flags, 3361 uint16_t stream_no, 3362 uint32_t pr_value, 3363 uint32_t context); 3365 and the arguments are: 3366 sd: The socket descriptor 3367 msg: The message to be sent. 3368 len: Yhe length of the message. 3369 to: The destination address of the message. 3370 tolen: The length of the destination address. 3371 ppid: The same as sinfo_ppid (see Section 6.2.2) 3372 flags: The same as sinfo_flags (see Section 6.2.2) 3373 stream_no: The same as sinfo_stream (see Section 6.2.2) 3374 pr_value: The same as sinfo_pr_value (see Section 6.2.2). 3375 context: The same as sinfo_context (see Section 6.2.2) 3376 The call returns the number of characters sent, or -1 if an error 3377 occurred. The variable errno is then set appropriately. 3379 Sending a message using sctp_sendmsg() is atomic unless explicit EOR 3380 marking is enabled on the socket specified by sd. 3382 Using sctp_sendmsg() on a non-connected one-to-one style socket for 3383 implicit connection setup may or may not work depending on the SCTP 3384 implementation. 3386 9.8. sctp_recvmsg() 3388 An implementation may provide a library function (or possibly system 3389 call) to assist the user with the advanced features of SCTP. Note 3390 that in order for the sctp_sndrcvinfo structure to be filled in by 3391 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3392 the SCTP_EVENTS option. Note that the setting of the 3393 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the 3394 sctp_sndrcvinfo information to be extended. 3396 The function prototype is 3398 ssize_t sctp_recvmsg(int sd, 3399 void *msg, 3400 size_t len, 3401 struct sockaddr *from, 3402 socklen_t *fromlen 3403 struct sctp_sndrcvinfo *sinfo 3404 int *msg_flags); 3406 and the arguments are 3407 sd: The socket descriptor. 3408 msg: The message buffer to be filled. 3409 len: The length of the message buffer. 3410 from: A pointer to a address to be filled with the sender of this 3411 messages address. 3412 fromlen: An in/out parameter describing the from length. 3413 sinfo: A pointer to a sctp_sndrcvinfo structure to be filled upon 3414 receipt of the message. 3415 msg_flags: A pointer to a integer to be filled with any message 3416 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 3417 field. Options for the receive may also be passed into the value 3418 (e.g. MSG_PEEK). On return from the call, the msg_flags value 3419 will be different than what was sent in to the call. If 3420 implemented via a recvmsg() call, the msg_flags should only 3421 contain the value of the flags from the recvmsg() call. 3422 The call returns the number of bytes received, or -1 if an error 3423 occurred. The variable errno is then set appropriately. 3425 9.9. sctp_connectx() 3427 An implementation may provide a library function (or possibly system 3428 call) to assist the user with associating to an endpoint that is 3429 multi-homed. Much like sctp_bindx() this call allows a caller to 3430 specify multiple addresses at which a peer can be reached. The way 3431 the SCTP stack uses the list of addresses to set up the association 3432 is implementation dependent. This function only specifies that the 3433 stack will try to make use of all the addresses in the list when 3434 needed. 3436 Note that the list of addresses passed in is only used for setting up 3437 the association. It does not necessarily equal the set of addresses 3438 the peer uses for the resulting association. If the caller wants to 3439 find out the set of peer addresses, it must use sctp_getpaddrs() to 3440 retrieve them after the association has been set up. 3442 The function prototype is 3444 int sctp_connectx(int sd, 3445 struct sockaddr *addrs, 3446 int addrcnt, 3447 sctp_assoc_t *id); 3449 and the arguments are: 3450 sd: The socket descriptor. 3451 addrs: An (packed) array of addresses. 3452 addrcnt: The number of addresses in the array. 3453 id: An output parameter that if passed in as a non-NULL will return 3454 the association identification for the newly created association 3455 (if successful). 3457 The call returns 0 on success or -1 if an error occurred. The 3458 variable errno is then set appropriately. 3460 9.10. sctp_send() 3462 An implementation may provide another alternative function or system 3463 call to assist an application with the sending of data without the 3464 use of the CMSG header structures. 3466 The function prototype is 3468 ssize_t sctp_send(int sd, 3469 const void *msg, 3470 size_t len, 3471 const struct sctp_sndrcvinfo *sinfo, 3472 int flags); 3474 and the arguments are 3475 sd: The socket descriptor. 3477 msg: The message to be sent. 3478 len: The length of the message. 3479 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3480 Section 6.2.2 for a sendmsg call. 3481 flags: The same flags as used by the sendmsg call flags (e.g. 3482 MSG_DONTROUTE). 3483 The call returns the number of bytes sent, or -1 if an error 3484 occurred. The variable errno is then set appropriately. 3486 This function call may also be used to terminate an association using 3487 an association identification by setting the sinfo.sinfo_flags to 3488 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3489 to be terminated. In such a case the len of the message would be 3490 zero. 3492 Using sctp_send() on a non-connected one-to-one style socket for 3493 implicit connection setup may or may not work depending on the SCTP 3494 implementation. 3496 Sending a message using sctp_send() is atomic unless explicit EOR 3497 marking is enabled on the socket specified by sd. 3499 9.11. sctp_sendx() 3501 An implementation may provide another alternative function or system 3502 call to assist an application with the sending of data without the 3503 use of the CMSG header structures that also gives a list of 3504 addresses. The list of addresses is provided for implicit 3505 association setup. In such a case the list of addresses serves the 3506 same purpose as the addresses given in sctp_connectx() (see 3507 Section 9.9). 3509 The function prototype is 3511 ssize_t sctp_sendx(int sd, 3512 const void *msg, 3513 size_t len, 3514 struct sockaddr *addrs, 3515 int addrcnt, 3516 struct sctp_sndrcvinfo *sinfo, 3517 int flags); 3519 and the arguments are: 3520 sd: The socket descriptor. 3522 msg: The message to be sent. 3523 len: The length of the message. 3524 addrs: is an array of addresses. 3525 addrcnt: The number of addresses in the array. 3526 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3527 Section 6.2.2 for a sendmsg call. 3528 flags: The same flags as used by the sendmsg call flags (e.g. 3529 MSG_DONTROUTE). 3530 The call returns the number of bytes sent, or -1 if an error 3531 occurred. The variable errno is then set appropriately. 3533 Note that on return from this call the sinfo structure will have 3534 changed in that the sinfo_assoc_id will be filled in with the new 3535 association id. 3537 This function call may also be used to terminate an association using 3538 an association identification by setting the sinfo.sinfo_flags to 3539 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3540 to be terminated. In such a case the len of the message would be 3541 zero. 3543 Sending a message using sctp_send() is atomic unless explicit EOR 3544 marking is enabled on the socket specified by sd. 3546 Using sctp_sendx() on a non-connected one-to-one style socket for 3547 implicit connection setup may or may not work depending on the SCTP 3548 implementation. 3550 9.12. sctp_getaddrlen() 3552 For application binary portability it is sometimes desirable to know 3553 what the kernel thinks is the length of a socket address family. 3555 The function prototype is: 3557 int sctp_getaddrlen(sa_family_t family); 3559 This function, when called with a valid family type returns the 3560 length that the operating system uses in the specified family's 3561 socket address structure. In case of an error, -1 is returned an the 3562 variable errno is then set appropriately 3564 10. IANA Considerations 3566 This document requires no actions from IANA. 3568 11. Security Considerations 3570 Many TCP and UDP implementations reserve port numbers below 1024 for 3571 privileged users. If the target platform supports privileged users, 3572 the SCTP implementation SHOULD restrict the ability to call bind() or 3573 sctp_bindx() on these port numbers to privileged users. 3575 Similarly unprivileged users should not be able to set protocol 3576 parameters which could result in the congestion control algorithm 3577 being more aggressive than permitted on the public Internet. These 3578 parameters are: 3579 o struct sctp_rtoinfo 3581 If an unprivileged user inherits a one-to-many style socket with open 3582 associations on a privileged port, it MAY be permitted to accept new 3583 associations, but it SHOULD NOT be permitted to open new 3584 associations. This could be relevant for the r* family of protocols. 3586 Applications using the one-to-many style sockets and using the 3587 interleave level if 0 are subject to denial of service attacks as 3588 described in Section 8.1.20. 3590 12. Acknowledgments 3592 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 3593 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 3594 early formation of this document. 3596 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3597 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 3598 Jonathan Leighton, and many others on the TSVWG mailing list for 3599 contributing valuable comments. 3601 A special thanks to Phillip Conrad, for his suggested text, quick and 3602 constructive insights, and most of all his persistent fighting to 3603 keep the interface to SCTP usable for the application programmer. 3605 13. Normative References 3607 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3608 RFC 793, September 1981. 3610 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3611 August 1980. 3613 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3614 Functional Specification", RFC 1644, July 1994. 3616 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3617 Requirement Levels", BCP 14, RFC 2119, March 1997. 3619 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 3620 Stevens, "Basic Socket Interface Extensions for IPv6", 3621 RFC 3493, February 2003. 3623 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3624 "Advanced Sockets Application Program Interface (API) for 3625 IPv6", RFC 3542, May 2003. 3627 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 3628 Conrad, "Stream Control Transmission Protocol (SCTP) 3629 Partial Reliability Extension", RFC 3758, May 2004. 3631 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 3632 "Authenticated Chunks for the Stream Control Transmission 3633 Protocol (SCTP)", RFC 4895, August 2007. 3635 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 3636 RFC 4960, September 2007. 3638 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 3639 Kozuka, "Stream Control Transmission Protocol (SCTP) 3640 Dynamic Address Reconfiguration", RFC 5061, 3641 September 2007. 3643 Appendix A. One-to-One Style Code Example 3645 The following code is a simple implementation of an echo server over 3646 SCTP. The example shows how to use some features of one-to-one style 3647 IPv4 SCTP sockets, including: 3648 o Opening, binding, and listening for new associations on a socket 3649 o Enabling ancillary data 3650 o Enabling notifications 3651 o Using ancillary data with sendmsg() and recvmsg() 3652 o Using MSG_EOR to determine if an entire message has been read 3653 o Handling notifications 3655 #include 3656 #include 3657 #include 3658 #include 3659 #include 3660 #include 3661 #include 3662 #include 3663 #include 3665 #define BUFLEN 100 3667 static void 3668 handle_event(void *buf) 3669 { 3670 struct sctp_assoc_change *sac; 3671 struct sctp_send_failed *ssf; 3672 struct sctp_paddr_change *spc; 3673 struct sctp_remote_error *sre; 3674 union sctp_notification *snp; 3675 char addrbuf[INET6_ADDRSTRLEN]; 3676 const char *ap; 3677 struct sockaddr_in *sin; 3678 struct sockaddr_in6 *sin6; 3680 snp = buf; 3682 switch (snp->sn_header.sn_type) { 3683 case SCTP_ASSOC_CHANGE: 3684 sac = &snp->sn_assoc_change; 3685 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3686 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3687 sac->sac_inbound_streams, sac->sac_outbound_streams); 3688 break; 3689 case SCTP_SEND_FAILED: 3690 ssf = &snp->sn_send_failed; 3691 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3692 ssf->ssf_error); 3693 break; 3695 case SCTP_PEER_ADDR_CHANGE: 3696 spc = &snp->sn_paddr_change; 3697 if (spc->spc_aaddr.ss_family == AF_INET) { 3698 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3699 ap = inet_ntop(AF_INET, &sin->sin_addr, 3700 addrbuf, INET6_ADDRSTRLEN); 3701 } else { 3702 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3703 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3704 addrbuf, INET6_ADDRSTRLEN); 3705 } 3706 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3707 spc->spc_state, spc->spc_error); 3708 break; 3710 case SCTP_REMOTE_ERROR: 3711 sre = &snp->sn_remote_error; 3712 printf("^^^ remote_error: err=%hu len=%hu\n", 3713 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3714 break; 3715 case SCTP_SHUTDOWN_EVENT: 3716 printf("^^^ shutdown event\n"); 3717 break; 3718 default: 3719 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3720 break; 3721 }; 3722 } 3724 static void * 3725 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3726 ssize_t *nrp, size_t cmsglen) 3727 { 3728 ssize_t nr = 0, nnr = 0; 3729 struct iovec iov[1]; 3731 *nrp = 0; 3732 iov->iov_base = buf; 3733 iov->iov_len = *buflen; 3734 msg->msg_iov = iov; 3735 msg->msg_iovlen = 1; 3737 for (;;) { 3738 #ifndef MSG_XPG4_2 3739 #define MSG_XPG4_2 0 3740 #endif 3741 msg->msg_flags = MSG_XPG4_2; 3742 msg->msg_controllen = cmsglen; 3744 nnr = recvmsg(fd, msg, 0); 3745 if (nnr <= 0) { 3746 /* EOF or error */ 3747 *nrp = nr; 3748 return (NULL); 3749 } 3750 nr += nnr; 3752 if ((msg->msg_flags & MSG_EOR) != 0) { 3753 *nrp = nr; 3754 return (buf); 3755 } 3756 /* Realloc the buffer? */ 3757 if (*buflen == (size_t)nr) { 3758 buf = realloc(buf, *buflen * 2); 3759 if (buf == 0) { 3760 fprintf(stderr, "out of memory\n"); 3761 exit(1); 3762 } 3763 *buflen *= 2; 3764 } 3765 /* Set the next read offset */ 3766 iov->iov_base = (char *)buf + nr; 3767 iov->iov_len = *buflen - nr; 3768 } 3769 } 3771 static void 3772 echo(int fd, int socketModeone_to_many) 3773 { 3774 ssize_t nr; 3775 struct sctp_sndrcvinfo *sri; 3776 struct msghdr msg[1]; 3777 struct cmsghdr *cmsg; 3778 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3779 char *buf; 3780 size_t buflen; 3781 struct iovec iov[1]; 3782 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3783 /* Allocate the initial data buffer */ 3784 buflen = BUFLEN; 3785 if (!(buf = malloc(BUFLEN))) { 3786 fprintf(stderr, "out of memory\n"); 3787 exit(1); 3788 } 3790 /* Set up the msghdr structure for receiving */ 3791 memset(msg, 0, sizeof (*msg)); 3792 msg->msg_control = cbuf; 3793 msg->msg_controllen = cmsglen; 3794 msg->msg_flags = 0; 3795 cmsg = (struct cmsghdr *)cbuf; 3796 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3798 /* Wait for something to echo */ 3799 while (buf = mysctp_recvmsg(fd, msg, 3800 buf, &buflen, &nr, cmsglen)) { 3802 /* Intercept notifications here */ 3803 if (msg->msg_flags & MSG_NOTIFICATION) { 3804 handle_event(buf); 3805 continue; 3806 } 3808 iov->iov_base = buf; 3809 iov->iov_len = nr; 3810 msg->msg_iov = iov; 3811 msg->msg_iovlen = 1; 3813 printf("got %u bytes on stream %hu:\n", nr, 3814 sri->sinfo_stream); 3815 write(0, buf, nr); 3817 /* Echo it back */ 3818 msg->msg_flags = MSG_XPG4_2; 3819 if (sendmsg(fd, msg, 0) < 0) { 3820 perror("sendmsg"); 3821 exit(1); 3822 } 3823 } 3825 if (nr < 0) { 3826 perror("recvmsg"); 3827 } 3828 if(socketModeone_to_many == 0) 3829 close(fd); 3830 } 3832 int main() 3833 { 3834 struct sctp_event_subscribe event; 3835 int lfd, cfd; 3836 int onoff = 1; 3837 struct sockaddr_in sin[1]; 3838 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3839 perror("socket"); 3840 exit(1); 3841 } 3843 sin->sin_family = AF_INET; 3844 sin->sin_port = htons(7); 3845 sin->sin_addr.s_addr = INADDR_ANY; 3846 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3847 perror("bind"); 3848 exit(1); 3849 } 3851 if (listen(lfd, 1) == -1) { 3852 perror("listen"); 3853 exit(1); 3854 } 3856 /* Wait for new associations */ 3857 for (;;) { 3858 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3859 perror("accept"); 3860 exit(1); 3861 } 3863 /* Enable all events */ 3864 event.sctp_data_io_event = 1; 3865 event.sctp_association_event = 1; 3866 event.sctp_address_event = 1; 3867 event.sctp_send_failure_event = 1; 3868 event.sctp_peer_error_event = 1; 3869 event.sctp_shutdown_event = 1; 3870 event.sctp_partial_delivery_event = 1; 3871 event.sctp_adaptation_layer_event = 1; 3872 if (setsockopt(cfd, IPPROTO_SCTP, 3873 SCTP_EVENTS, &event, 3874 sizeof(event)) != 0) { 3875 perror("setevent failed"); 3876 exit(1); 3877 } 3878 /* Echo back any and all data */ 3879 echo(cfd,0); 3880 } 3881 } 3883 Appendix B. One-to-Many Style Code Example 3885 The following code is a simple implementation of an echo server over 3886 SCTP. The example shows how to use some features of one-to-many 3887 style IPv4 SCTP sockets, including: 3888 o Opening and binding of a socket 3889 o Enabling ancillary data 3890 o Enabling notifications 3891 o Using ancillary data with sendmsg() and recvmsg() 3892 o Using MSG_EOR to determine if an entire message has been read 3893 o Handling notifications 3895 Note most functions defined in Appendix A are reused in this example. 3897 int main() 3898 { 3899 int fd; 3900 int idleTime = 2; 3901 struct sockaddr_in sin[1]; 3902 struct sctp_event_subscribe event; 3904 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3905 perror("socket"); 3906 exit(1); 3907 } 3909 sin->sin_family = AF_INET; 3910 sin->sin_port = htons(7); 3911 sin->sin_addr.s_addr = INADDR_ANY; 3912 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3913 perror("bind"); 3914 exit(1); 3915 } 3917 /* Enable all notifications and events */ 3918 event.sctp_data_io_event = 1; 3919 event.sctp_association_event = 1; 3920 event.sctp_address_event = 1; 3921 event.sctp_send_failure_event = 1; 3922 event.sctp_peer_error_event = 1; 3923 event.sctp_shutdown_event = 1; 3924 event.sctp_partial_delivery_event = 1; 3925 event.sctp_adaptation_layer_event = 1; 3926 if (setsockopt(fd, IPPROTO_SCTP, 3927 SCTP_EVENTS, &event, 3928 sizeof(event)) != 0) { 3929 perror("setevent failed"); 3930 exit(1); 3931 } 3932 /* Set associations to auto-close in 2 seconds of 3933 * inactivity 3934 */ 3935 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3936 &idleTime, 4) < 0) { 3937 perror("setsockopt SCTP_AUTOCLOSE"); 3938 exit(1); 3939 } 3941 /* Allow new associations to be accepted */ 3942 if (listen(fd, 1) < 0) { 3943 perror("listen"); 3944 exit(1); 3945 } 3946 /* Wait for new associations */ 3947 while(1){ 3948 /* Echo back any and all data */ 3949 echo(fd,1); 3950 } 3951 } 3953 Authors' Addresses 3955 Randall R. Stewart 3956 The Resource Group 3957 1700 Pennsylvania Ave NW 3958 Suite 56 3959 Washington, DC 20006 3960 USA 3962 Email: randall.stewart@trgworld.com 3964 Kacheong Poon 3965 Sun Microsystems, Inc. 3966 4150 Network Circle 3967 Santa Clara, CA 95054 3968 USA 3970 Email: kacheong.poon@sun.com 3972 Michael Tuexen 3973 Univ. of Applied Sciences Muenster 3974 Stegerwaldstr. 39 3975 48565 Steinfurt 3976 Germany 3978 Email: tuexen@fh-muenster.de 3980 Vladislav Yasevich 3981 HP 3982 110 Spitrook Rd 3983 Nashua, NH, 03062 3984 USA 3986 Email: vladislav.yasevich@hp.com 3987 Peter Lei 3988 Cisco Systems, Inc. 3989 8735 West Higgins Road 3990 Suite 300 3991 Chicago, IL 60631 3992 USA 3994 Email: peterlei@cisco.com 3996 Full Copyright Statement 3998 Copyright (C) The IETF Trust (2008). 4000 This document is subject to the rights, licenses and restrictions 4001 contained in BCP 78, and except as set forth therein, the authors 4002 retain all their rights. 4004 This document and the information contained herein are provided on an 4005 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4006 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4007 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4008 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4009 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4010 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4012 Intellectual Property 4014 The IETF takes no position regarding the validity or scope of any 4015 Intellectual Property Rights or other rights that might be claimed to 4016 pertain to the implementation or use of the technology described in 4017 this document or the extent to which any license under such rights 4018 might or might not be available; nor does it represent that it has 4019 made any independent effort to identify any such rights. Information 4020 on the procedures with respect to rights in RFC documents can be 4021 found in BCP 78 and BCP 79. 4023 Copies of IPR disclosures made to the IETF Secretariat and any 4024 assurances of licenses to be made available, or the result of an 4025 attempt made to obtain a general license or permission for the use of 4026 such proprietary rights by implementers or users of this 4027 specification can be obtained from the IETF on-line IPR repository at 4028 http://www.ietf.org/ipr. 4030 The IETF invites any interested party to bring to its attention any 4031 copyrights, patents or patent applications, or other proprietary 4032 rights that may cover technology that may be required to implement 4033 this standard. Please address the information to the IETF at 4034 ietf-ipr@ietf.org.