idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-24.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 25, 2010) is 4932 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 ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 1644 (Obsoleted by RFC 6247) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Huawei 4 Intended status: Informational K. Poon 5 Expires: April 28, 2011 Oracle Corporation 6 M. Tuexen 7 Muenster Univ. of Applied Sciences 8 V. Yasevich 9 HP 10 P. Lei 11 Cisco Systems, Inc. 12 October 25, 2010 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-24.txt 17 Abstract 19 This document describes a mapping of the Stream Control Transmission 20 Protocol SCTP into a sockets API. The benefits of this mapping 21 include compatibility for TCP applications, access to new SCTP 22 features and a consolidated error and event notification scheme. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 28, 2011. 41 Copyright Notice 43 Copyright (c) 2010 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 This document may contain material from IETF Documents or IETF 57 Contributions published or made publicly available before November 58 10, 2008. The person(s) controlling the copyright in some of this 59 material may not have granted the IETF Trust the right to allow 60 modifications of such material outside the IETF Standards Process. 61 Without obtaining an adequate license from the person(s) controlling 62 the copyright in such materials, this document may not be modified 63 outside the IETF Standards Process, and derivative works of it may 64 not be created outside the IETF Standards Process, except to format 65 it for publication as an RFC or to translate it into languages other 66 than English. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8 73 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 74 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 9 75 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 10 76 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 11 77 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 11 78 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 13 79 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 14 80 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 81 3.3. Special considerations . . . . . . . . . . . . . . . . . . 15 82 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 17 83 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 84 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 18 85 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18 86 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19 87 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 20 88 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20 89 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21 90 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 22 91 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22 92 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 23 93 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 23 94 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 95 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 24 96 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 25 97 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 26 98 5.2.3. Extended SCTP Header Information Structure 99 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28 100 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . . 30 101 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31 102 5.2.6. SCTP Next Receive Information Structure 103 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 33 104 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 33 105 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 34 106 5.2.9. SCTP Destination Address Structure (IPv4) 107 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . . 34 108 5.2.10. SCTP Destination Address Structure (IPv6) 109 (SCTP_DSTADDRV6) . . . . . . . . . . . . . . . . . . . 34 110 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 35 111 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 35 112 5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 37 113 5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 38 114 5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 39 115 5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 40 116 5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 41 117 5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 42 118 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 42 119 5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 43 120 5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 44 121 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 45 122 5.3.12. SCTP_SEND_FAILED_EVENT . . . . . . . . . . . . . . . . 45 123 5.4. Ancillary Data Considerations and Semantics . . . . . . . 46 124 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 46 125 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 47 126 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 47 127 6. Common Operations for Both Styles . . . . . . . . . . . . . . 48 128 6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 48 129 6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 50 130 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 51 131 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 51 132 6.5. Implicit Association Setup . . . . . . . . . . . . . . . . 52 133 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 52 134 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 54 135 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 54 136 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 55 137 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 57 138 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 57 139 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 57 140 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 58 141 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 58 142 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 58 143 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 58 144 7.1.10. Set Adaptation Layer Indicator 145 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 59 146 7.1.11. Enable/Disable Message Fragmentation 147 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 59 148 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 59 149 7.1.13. Set Default Send Parameters 150 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 61 151 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 62 152 7.1.15. Set/Clear IPv4 Mapped Addresses 153 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 62 154 7.1.16. Get or Set the Maximum Fragmentation Size 155 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 62 156 7.1.17. Get or Set the List of Supported HMAC Identifiers 157 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 63 158 7.1.18. Get or Set the Active Shared Key 159 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 64 160 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 64 161 7.1.20. Get or Set Fragmented Interleave 162 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 65 163 7.1.21. Set or Get the SCTP Partial Delivery Point 164 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 66 165 7.1.22. Set or Get the Use of Extended Receive Info 166 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 67 167 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 67 168 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 67 169 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 68 170 7.1.26. Enable or Disable Explicit EOR Marking 171 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 68 172 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 68 173 7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 69 174 7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 175 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 69 176 7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 177 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 69 178 7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . . 69 179 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 70 180 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 70 181 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 71 182 7.2.3. Get the List of Chunks the Peer Requires to be 183 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 72 184 7.2.4. Get the List of Chunks the Local Endpoint Requires 185 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 72 186 7.2.5. Get the Current Number of Associations 187 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 73 188 7.2.6. Get the Current Identifiers of Associations 189 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 73 190 7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 74 191 7.3.1. Set Peer Primary Address 192 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 74 193 7.3.2. Add a Chunk That Must Be Authenticated 194 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 74 195 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 75 196 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 75 197 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 76 198 7.4. Ancillary Data and Notification Interest Options . . . . . 76 199 8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 79 200 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 79 201 8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 81 202 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 82 203 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 82 204 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 83 205 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 83 206 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 83 207 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 84 208 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 85 209 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 86 210 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 87 211 8.12. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . . 88 212 8.13. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . . 89 213 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 90 214 10. Security Considerations . . . . . . . . . . . . . . . . . . . 90 215 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 91 216 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 91 217 12.1. Normative References . . . . . . . . . . . . . . . . . . . 91 218 12.2. Informative References . . . . . . . . . . . . . . . . . . 92 219 Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 92 220 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 97 221 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 99 223 1. Introduction 225 The sockets API has provided a standard mapping of the Internet 226 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 227 [RFC0768] have benefited from this standard representation and access 228 method across many diverse platforms. SCTP is a new protocol that 229 provides many of the characteristics of TCP but also incorporates 230 semantics more akin to UDP. This document defines a method to map 231 the existing sockets API for use with SCTP, providing both a base for 232 access to new features and compatibility so that most existing TCP 233 applications can be migrated to SCTP with few (if any) changes. 235 There are three basic design objectives: 236 1. Maintain consistency with existing sockets APIs: We define a 237 sockets mapping for SCTP that is consistent with other sockets 238 API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). 239 2. Support a one-to-many style interface: This set of semantics is 240 similar to that defined for connection-less protocols, such as 241 UDP. A one-to-many style SCTP socket should be able to control 242 multiple SCTP associations. This is similar to a UDP socket, 243 which can communicate with many peer endpoints. Each of these 244 associations is assigned an association ID so that an application 245 can use the ID to differentiate them. Note that SCTP is 246 connection-oriented in nature, and it does not support broadcast 247 or multicast communications, as UDP does. 248 3. Support a one-to-one style interface: This interface supports a 249 similar semantics as sockets for connection-oriented protocols, 250 such as TCP. A one-to-one style SCTP socket should only control 251 one SCTP association. One purpose of defining this interface is 252 to allow existing applications built on other connection-oriented 253 protocols be ported to use SCTP with very little effort. 254 Developers familiar with these semantics can easily adapt to 255 SCTP. Another purpose is to make sure that existing mechanisms 256 in most operating systems that support sockets, such as select(), 257 should continue to work with this style of socket. Extensions 258 are added to this mapping to provide mechanisms to exploit new 259 features of SCTP. 261 Goals 2 and 3 are not compatible, so this document defines two modes 262 of mapping, namely the one-to-many style mapping and the one-to-one 263 style mapping. These two modes share some common data structures and 264 operations, but will require the use of two different application 265 programming styles. Note that all new SCTP features can be used with 266 both styles of socket. The decision on which one to use depends 267 mainly on the nature of applications. 269 A mechanism is defined to extract a one-to-many style SCTP 270 association into a one-to-one style socket. 272 Some of the SCTP mechanisms cannot be adequately mapped to an 273 existing socket interface. In some cases, it is more desirable to 274 have a new interface instead of using existing socket calls. 275 Section 8 of this document describes these new interfaces. 277 2. Data Types 279 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 280 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 281 (e.g. uint16_t). This document also assumes the argument data types 282 from 1003.1g when possible (e.g. the final argument to setsockopt() 283 is a size_t value). Whenever buffer sizes are specified, the POSIX 284 1003.1 size_t data type is used. 286 3. One-to-Many Style Interface 288 In the one-to-many style interface there is a 1 to many relationship 289 between sockets and associations. 291 3.1. Basic Operation 293 A typical server in this style uses the following socket calls in 294 sequence to prepare an endpoint for servicing requests: 295 o socket() 296 o bind() 297 o listen() 298 o recvmsg() 299 o sendmsg() 300 o close() 302 A typical client uses the following calls in sequence to setup an 303 association with a server to request services: 304 o socket() 305 o sendmsg() 306 o recvmsg() 307 o close() 309 In this style, by default, all the associations connected to the 310 endpoint are represented with a single socket. Each association is 311 assigned an association ID (type is sctp_assoc_t) so that an 312 application can use it to differentiate between them. In some 313 implementations, the peer endpoints' addresses can also be used for 314 this purpose. But this is not required for performance reasons. If 315 an implementation does not support using addresses to differentiate 316 between different associations, the sendto() call can only be used to 317 setup an association implicitly. It cannot be used to send data to 318 an established association as the association ID cannot be specified. 320 Once an association ID is assigned to an SCTP association, that ID 321 will not be reused until the application explicitly terminates the 322 association. The resources belonging to that association will not be 323 freed until that happens. This is similar to the close() operation 324 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 325 option (section 7.1.8) is set. In this case, after the association 326 is terminated gracefully and automatically, the association ID 327 assigned to it can be reused. All applications using this option 328 should be aware of this to avoid the possible problem of sending data 329 to an incorrect peer endpoint. 331 If the server or client wishes to branch an existing association off 332 to a separate socket, it is required to call sctp_peeloff() and to 333 specify the association identifier. The sctp_peeloff() call will 334 return a new socket which can then be used with recv() and send() 335 functions for message passing. See Section 8.2 for more on branched- 336 off associations. The returned socket is a one-to-one style socket. 338 Once an association is branched off to a separate socket, it becomes 339 completely separated from the original socket. All subsequent 340 control and data operations to that association must be done through 341 the new socket. For example, the close operation on the original 342 socket will not terminate any associations that have been branched 343 off to a different socket. 345 One-to-many style socket calls are discussed in more detail in the 346 following subsections. 348 3.1.1. socket() 350 Applications use socket() to create a socket descriptor to represent 351 an SCTP endpoint. 353 The function prototype is 355 int socket(int domain, 356 int type, 357 int protocol); 359 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 360 type and IPPROTO_SCTP as the protocol. 362 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 363 socket. 365 The function returns a socket descriptor or -1 in case of an error. 367 Using the PF_INET domain indicates the creation of an endpoint which 368 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 369 can use both IPv6 and IPv4 addresses. 371 3.1.2. bind() 373 Applications use bind() to specify which local address and port the 374 SCTP endpoint should associate itself with. 376 An SCTP endpoint can be associated with multiple addresses. To do 377 this, sctp_bindx() is introduced in Section 8.1 to help applications 378 do the job of associating multiple addresses. But note that an 379 endpoint can only be associated with one local port. 381 These addresses associated with a socket are the eligible transport 382 addresses for the endpoint to send and receive data. The endpoint 383 will also present these addresses to its peers during the association 384 initialization process, see [RFC4960]. 386 After calling bind(), if the endpoint wishes to accept new 387 associations on the socket, it must call listen() (see 388 Section 3.1.3). 390 The function prototype of bind() is 392 int bind(int sd, 393 struct sockaddr *addr, 394 socklen_t addrlen); 396 and the arguments are 397 sd: The socket descriptor returned by socket(). 398 addr: The address structure (struct sockaddr_in for an IPv4 address 399 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 400 addrlen: The size of the address structure. 401 It returns 0 on success and -1 in case of an error. 403 If sd is an IPv4 socket, the address passed must be an IPv4 address. 404 If the sd is an IPv6 socket, the address passed can either be an IPv4 405 or an IPv6 address. 407 Applications cannot call bind() multiple times to associate multiple 408 addresses to an endpoint. After the first call to bind(), all 409 subsequent calls will return an error. 411 If the IP address part of addr is specified as a wildcard (INADDR_ANY 412 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 413 IPv6 address), the operating system will associate the endpoint with 414 an optimal address set of the available interfaces. If the IPv4 415 sin_port or IPv6 sin6_port is set to 0, the operating system will 416 choose an ephemeral port for the endpoint. 418 If a bind() is not called prior to a sendmsg() call that initiates a 419 new association, the system picks an ephemeral port and will choose 420 an address set equivalent to binding with a wildcard address. One of 421 those addresses will be the primary address for the association. 422 This automatically enables the multi-homing capability of SCTP. 424 3.1.3. listen() 426 By default, a one-to-many style socket does not accept new 427 association requests. An application uses listen() to mark a socket 428 as being able to accept new associations. 430 The function prototype is 432 int listen(int sd, 433 int backlog); 435 and the arguments are 436 sd: The socket descriptor of the endpoint. 437 backlog: If backlog is non-zero, enable listening else disable 438 listening. 439 It returns 0 on success and -1 in case of an error. 441 Note that one-to-many style socket consumers do not need to call 442 accept to retrieve new associations. Calling accept() on a one-to- 443 many style socket should return EOPNOTSUPP. Rather, new associations 444 are accepted automatically, and notifications of the new associations 445 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 446 these notifications are enabled). Clients will typically not call 447 listen(), so that they can be assured that only actively initiated 448 associations are on the socket. Server or peer-to-peer sockets, on 449 the other hand, will always accept new associations, so a well- 450 written application using server one-to-many style sockets must be 451 prepared to handle new associations from unwanted peers. 453 Also note that the SCTP_ASSOC_CHANGE event provides the association 454 ID for a new association, so if applications wish to use the 455 association ID as input to other socket calls, they should ensure 456 that the SCTP_ASSOC_CHANGE event is enabled. 458 3.1.4. sendmsg() and recvmsg() 460 An application uses the sendmsg() and recvmsg() call to transmit data 461 to and receive data from its peer. 463 The function prototypes are 465 ssize_t sendmsg(int sd, 466 const struct msghdr *message, 467 int flags); 469 and 471 ssize_t recvmsg(int sd, 472 struct msghdr *message, 473 int flags); 475 using the arguments: 476 sd: The socket descriptor of the endpoint. 477 message: Pointer to the msghdr structure which contains a single 478 user message and possibly some ancillary data. See Section 5 for 479 complete description of the data structures. 480 flags: No new flags are defined for SCTP at this level. See 481 Section 5 for SCTP specific flags used in the msghdr structure. 482 sendmsg() returns the number of bytes accepted by the kernel or -1 in 483 case of an error. recvmsg() returns the number of bytes received or 484 -1 in case of an error. 486 As described in Section 5, different types of ancillary data can be 487 sent and received along with user data. When sending, the ancillary 488 data is used to specify the sent behavior, such as the SCTP stream 489 number to use. When receiving, the ancillary data is used to 490 describe the received data, such as the SCTP stream sequence number 491 of the message. 493 When sending user data with sendmsg(), the msg_name field in the 494 msghdr structure will be filled with one of the transport addresses 495 of the intended receiver. If there is no existing association 496 between the sender and the intended receiver, the sender's SCTP stack 497 will set up a new association and then send the user data (see 498 Section 6.5 for more on implicit association setup). If sendmsg() is 499 called with no data and there is no existing association, a new one 500 will be established. The SCTP_INIT type ancillary data can be used 501 to change some of the parameters used to set up a new association. 502 If sendmsg() is called with NULL data, and there is no existing 503 association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is 504 returned and errno is set to EINVAL. Sending a message using 505 sendmsg() is atomic unless explicit EOR marking is enabled on the 506 socket specified by sd (see Section 7.1.26). 508 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 509 be delivered if that notification has been enabled, and no more data 510 can be sent to that association. Any attempt to send more data will 511 cause sendmsg() to return with an ESHUTDOWN error. Note that the 512 socket is still open for reading at this point so it is possible to 513 retrieve notifications. 515 When receiving a user message with recvmsg(), the msg_name field in 516 the msghdr structure will be populated with the source transport 517 address of the user data. The caller of recvmsg() can use this 518 address information to determine to which association the received 519 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 520 disabled, applications must use the peer transport address provided 521 in the msg_name field by recvmsg() to perform correlation to an 522 association, since they will not have the association ID. 524 If all data in a single message has been delivered, MSG_EOR will be 525 set in the msg_flags field of the msghdr structure (see Section 5.1). 527 If the application does not provide enough buffer space to completely 528 receive a data message, MSG_EOR will not be set in msg_flags. 529 Successive reads will consume more of the same message until the 530 entire message has been delivered, and MSG_EOR will be set. 532 If the SCTP stack is running low on buffers, it may partially deliver 533 a message. In this case, MSG_EOR will not be set, and more calls to 534 recvmsg() will be necessary to completely consume the message. Only 535 one message at a time can be partially delivered in any stream. The 536 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 537 what interlacing of messages occurs for both the one-to-one and the 538 one-to-many model sockets. Please consult Section 7.1.20 for further 539 details on message delivery options. 541 3.1.5. close() 543 Applications use close() to perform graceful shutdown (as described 544 in Section 10.1 of [RFC4960]) on all the associations currently 545 represented by a one-to-many style socket. 547 The function prototype is 549 int close(int sd); 551 and the argument is 552 sd: The socket descriptor of the associations to be closed. 553 0 is returned on success and -1 in case of an error. 555 To gracefully shutdown a specific association represented by the one- 556 to-many style socket, an application should use the sendmsg() call, 557 and include the SCTP_EOF flag. A user may optionally terminate an 558 association non-gracefully by sending with the SCTP_ABORT flag set 559 and possibly passing a user specified abort code in the data field. 560 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 561 (see Section 5.2.2) in the sendmsg() call. 563 If sd in the close() call is a branched-off socket representing only 564 one association, the shutdown is performed on that association only. 566 3.1.6. connect() 568 An application may use the connect() call in the one-to-many style to 569 initiate an association without sending data. 571 The function prototype is 573 int connect(int sd, 574 const struct sockaddr *nam, 575 socklen_t len); 577 and the arguments are 578 sd: The socket descriptor to have a new association added to. 579 nam: The address structure (struct sockaddr_in for an IPv4 address 580 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 581 len: The size of the address. 582 0 is returned on success and -1 in case of an error. 584 Multiple connect() calls can be made on the same socket to create 585 multiple associations. This is different from the semantics of 586 connect() on a UDP socket. 588 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 589 during the association set up phase. If an application wants to do 590 this, it cannot use the connect() call. Instead, it should use 591 sendto() or sendmsg() to initiate an association. If it uses 592 sendto() and it wants to change the initialization behavior, it needs 593 to use the SCTP_INITMSG socket option before calling sendto(). Or it 594 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 595 association without calling setsockopt(). Note that the implicit 596 setup is supported for the one-to-many style sockets. 598 SCTP does not support half close semantics. This means that unlike 599 T/TCP, MSG_EOF should not be set in the flags parameter when calling 600 sendto() or sendmsg() when the call is used to initiate a connection. 601 MSG_EOF is not an acceptable flag with an SCTP socket. 603 3.2. Non-blocking mode 605 Some SCTP application may wish to avoid being blocked when calling a 606 socket interface function. 608 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 609 one-to-many style socket, an application may set the non-blocking 610 option by a fcntl() (such as O_NONBLOCK). After setting the socket 611 to non-blocking mode, the sendmsg() function returns immediately. 612 The success or failure of sending the data message (with possible 613 SCTP_INITMSG ancillary data) will be signaled by the 614 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or CANT_START_ASSOC. If 615 user data could not be sent (due to a CANT_START_ASSOC), the sender 616 will also receive an SCTP_SEND_FAILED event. Events can be received 617 by the user calling recvmsg(). A server (having called listen()) is 618 also notified of an association up event by the reception of an 619 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 620 possibly the reception of the first data message. 622 To shutdown the association gracefully, the user must call sendmsg() 623 with no data and with the SCTP_EOF flag set. The function returns 624 immediately, and completion of the graceful shutdown is indicated by 625 an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see 626 Section 5.3.2). Note that this can also be done using the 627 sctp_send() call described in Section 8.10. 629 An application is recommended to use caution when using select() (or 630 poll()) for writing on a one-to-many style socket. The reason being 631 that the interpretation of select on write is implementation 632 specific. Generally a positive return on a select on write would 633 only indicate that one of the associations represented by the one-to- 634 many socket is writable. An application that writes after the 635 select() returns may still block since the association that was 636 writeable is not the destination association of the write call. 637 Likewise select() (or poll()) for reading from a one-to-many socket 638 will only return an indication that one of the associations 639 represented by the socket has data to be read. 641 An application that wishes to know that a particular association is 642 ready for reading or writing should either use the one-to-one style 643 or use the sctp_peeloff() (see Section 8.2) function to separate the 644 association of interest from the one-to-many socket. 646 Note some implementations may have an extended select call such as 647 epoll or kqueue that may escape this limitation and allow a select on 648 a specific association of a one-to-many socket, but this is an 649 implementation specific detail that a portable application cannot 650 count on. 652 3.3. Special considerations 654 The fact that a one-to-many style socket can provide access to many 655 SCTP associations through a single socket descriptor has important 656 implications for both application programmers and system programmers 657 implementing this API. A key issue is how buffer space inside the 658 sockets layer is managed. Because this implementation detail 659 directly affects how application programmers must write their code to 660 ensure correct operation and portability, this section provides some 661 guidance to both implementers and application programmers. 663 An important feature that SCTP shares with TCP is flow control. 664 Specifically, a sender may not send data faster than the receiver can 665 consume it. 667 For TCP, flow control is typically provided for in the sockets API as 668 follows. If the reader stops reading, the sender queues messages in 669 the socket layer until it uses all of its socket buffer space 670 allocation creating a "stalled connection". Further attempts to 671 write to the socket will block or return the error EAGAIN or 672 EWOULDBLOCK for a non-blocking socket. At some point, either the 673 connection is closed, or the receiver begins to read again freeing 674 space in the output queue. 676 For one-to-one style SCTP sockets (this includes sockets descriptors 677 that were separated from a one-to-many style socket with 678 sctp_peeloff()) the behavior is identical. For one-to-many style 679 SCTP sockets there are multiple associations for a single socket, 680 which makes the situation more complicated. If the implementation 681 uses a single buffer space allocation shared by all associations, a 682 single stalled association can prevent the further sending of data on 683 all associations active on a particular one-to-many style socket. 685 For a blocking socket, it should be clear that a single stalled 686 association can block the entire socket. For this reason, 687 application programmers may want to use non-blocking one-to-many 688 style sockets. The application should at least be able to send 689 messages to the non-stalled associations. 691 But a non-blocking socket is not sufficient if the API implementer 692 has chosen a single shared buffer allocation for the socket. A 693 single stalled association would eventually cause the shared 694 allocation to fill, and it would become impossible to send even to 695 non-stalled associations. 697 The API implementer can solve this problem by providing each 698 association with its own allocation of outbound buffer space. Each 699 association should conceptually have as much buffer space as it would 700 have if it had its own socket. As a bonus, this simplifies the 701 implementation of sctp_peeloff(). 703 To ensure that a given stalled association will not prevent other 704 non-stalled associations from being writable, application programmers 705 should either: 706 o demand that the underlying implementation dedicates independent 707 buffer space reservation to each association (as suggested above), 708 or 709 o verify that their application layer protocol does not permit large 710 amounts of unread data at the receiver (this is true of some 711 request-response protocols, for example), or 712 o use one-to-one style sockets for association which may potentially 713 stall (either from the beginning, or by using sctp_peeloff before 714 sending large amounts of data that may cause a stalled condition). 716 4. One-to-One Style Interface 718 The goal of this style is to follow as closely as possible the 719 current practice of using the sockets interface for a connection 720 oriented protocol, such as TCP. This style enables existing 721 applications using connection oriented protocols to be ported to SCTP 722 with very little effort. 724 One-to-one style sockets can be connected (explicitly or implicitly) 725 at most once, similar to TCP sockets. 727 Note that some new SCTP features and some new SCTP socket options can 728 only be utilized through the use of sendmsg() and recvmsg() calls, 729 see Section 4.1.8. 731 4.1. Basic Operation 733 A typical server in one-to-one style uses the following system call 734 sequence to prepare an SCTP endpoint for servicing requests: 735 o socket() 736 o bind() 737 o listen() 738 o accept() 740 The accept() call blocks until a new association is set up. It 741 returns with a new socket descriptor. The server then uses the new 742 socket descriptor to communicate with the client, using recv() and 743 send() calls to get requests and send back responses. 745 Then it calls 746 o close() 747 to terminate the association. 749 A typical client uses the following system call sequence to setup an 750 association with a server to request services: 752 o socket() 753 o connect() 755 After returning from connect(), the client uses send()/sendmsg() and 756 recv()/recvmsg() calls to send out requests and receive responses 757 from the server. 759 The client calls 760 o close() 761 to terminate this association when done. 763 4.1.1. socket() 765 Applications call socket() to create a socket descriptor to represent 766 an SCTP endpoint. 768 The function prototype is 770 int socket(int domain, 771 int type, 772 int protocol); 774 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 775 type and IPPROTO_SCTP as the protocol. 777 Here, SOCK_STREAM indicates the creation of a one-to-one style 778 socket. 780 Using the PF_INET domain indicates the creation of an endpoint which 781 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 782 can use both IPv6 and IPv4 addresses. 784 4.1.2. bind() 786 Applications use bind() to specify which local address and port the 787 SCTP endpoint should associate itself with. 789 An SCTP endpoint can be associated with multiple addresses. To do 790 this, sctp_bindx() is introduced in Section 8.1 to help applications 791 do the job of associating multiple addresses. But note that an 792 endpoint can only be associated with one local port. 794 These addresses associated with a socket are the eligible transport 795 addresses for the endpoint to send and receive data. The endpoint 796 will also present these addresses to its peers during the association 797 initialization process, see [RFC4960]. 799 The function prototype of bind() is 800 int bind(int sd, 801 struct sockaddr *addr, 802 socklen_t addrlen); 804 and the arguments are 805 sd: The socket descriptor returned by socket(). 806 addr: The address structure (struct sockaddr_in for an IPv4 address 807 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 808 addrlen: The size of the address structure. 810 If sd is an IPv4 socket, the address passed must be an IPv4 address. 811 If sd is an IPv6 socket, the address passed can either be an IPv4 or 812 an IPv6 address. 814 Applications cannot call bind() multiple times to associate multiple 815 addresses to the endpoint. After the first call to bind(), all 816 subsequent calls will return an error. 818 If the IP address part of addr is specified as a wildcard (INADDR_ANY 819 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 820 IPv6 address), the operating system will associate the endpoint with 821 an optimal address set of the available interfaces. If the IPv4 822 sin_port or IPv6 sin6_port is set to 0, the operating system will 823 choose an ephemeral port for the endpoint. 825 If a bind() is not called prior to the connect() call, the system 826 picks an ephemeral port and will choose an address set equivalent to 827 binding with a wildcard address. One of these addresses will be the 828 primary address for the association. This automatically enables the 829 multi-homing capability of SCTP. 831 The completion of this bind() process does not allow the SCTP 832 endpoint to accept inbound SCTP association requests. Until a 833 listen() system call, described below, is performed on the socket, 834 the SCTP endpoint will promptly reject an inbound SCTP INIT request 835 with an SCTP ABORT. 837 4.1.3. listen() 839 Applications use listen() to allow the SCTP endpoint to accept 840 inbound associations. 842 The function prototype is 844 int listen(int sd, 845 int backlog); 847 and the arguments are 848 sd: the socket descriptor of the SCTP endpoint. 849 backlog: this specifies the max number of outstanding associations 850 allowed in the socket's accept queue. These are the associations 851 that have finished the four-way initiation handshake (see Section 852 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 853 of '0' indicates that the caller no longer wishes to receive new 854 associations. 855 It returns 0 on success an -1 in case of an error. 857 4.1.4. accept() 859 Applications use the accept() call to remove an established SCTP 860 association from the accept queue of the endpoint. A new socket 861 descriptor will be returned from accept() to represent the newly 862 formed association. 864 The function prototype is 866 int accept(int sd, 867 struct sockaddr *addr, 868 socklen_t *addrlen); 870 and the arguments are 871 sd: The listening socket descriptor. 872 addr: On return, addr (struct sockaddr_in for an IPv4 address or 873 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 874 contain the primary address of the peer endpoint. 875 addrlen: On return, addrlen will contain the size of addr. 876 The function returns the socket descriptor for the newly formed 877 association on success and -1 in case of an error. 879 4.1.5. connect() 881 Applications use connect() to initiate an association to a peer. 883 The function prototype is 885 int connect(int sd, 886 const struct sockaddr *addr, 887 socklen_t addrlen); 889 and the arguments are 890 sd: The socket descriptor of the endpoint. 891 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 892 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 894 addrlen: The size of the address. 895 It returns 0 on success and -1 on error. 897 This operation corresponds to the ASSOCIATE primitive described in 898 Section 10.1 of [RFC4960]. 900 The number of outbound streams the new association has is stack 901 dependent. Applications can use the SCTP_INITMSG option described in 902 Section 7.1.3 before connecting to change the number of outbound 903 streams. 905 If a bind() is not called prior to the connect() call, the system 906 picks an ephemeral port and will choose an address set equivalent to 907 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 908 respectively. One of the addresses will be the primary address for 909 the association. This automatically enables the multi-homing 910 capability of SCTP. 912 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 913 during the association set up phase. If an application wants to do 914 this, it cannot use the connect() call. Instead, it should use 915 sendto() or sendmsg() to initiate an association. If it uses 916 sendto() and it wants to change the initialization behavior, it needs 917 to use the SCTP_INITMSG socket option before calling sendto(). Or it 918 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 919 association without calling setsockopt(). Note that the implicit 920 setup is supported for the one-to-one style sockets. 922 SCTP does not support half close semantics. This means that unlike 923 T/TCP, MSG_EOF should not be set in the flags parameter when calling 924 sendto() or sendmsg() when the call is used to initiate a connection. 925 MSG_EOF is not an acceptable flag with an SCTP socket. 927 4.1.6. close() 929 Applications use close() to gracefully close down an association. 931 The function prototype is 933 int close(int sd); 935 and the argument is 936 sd: The socket descriptor of the association to be closed. 937 It returns 0 on success and -1 in case of an error. 939 After an application calls close() on a socket descriptor, no further 940 socket operations will succeed on that descriptor. 942 4.1.7. shutdown() 944 SCTP differs from TCP in that it does not have half closed semantics. 945 Hence the shutdown() call for SCTP is an approximation of the TCP 946 shutdown() call, and solves some different problems. Full TCP- 947 compatibility is not provided, so developers porting TCP applications 948 to SCTP may need to recode sections that use shutdown(). (Note that 949 it is possible to achieve the same results as half close in SCTP 950 using SCTP streams.) 952 The function prototype is 954 int shutdown(int sd, 955 int how); 957 and the arguments are 958 sd: The socket descriptor of the association to be closed. 959 how: Specifies the type of shutdown. The values are as follows: 960 SHUT_RD: Disables further receive operations. No SCTP protocol 961 action is taken. 962 SHUT_WR: Disables further send operations, and initiates the SCTP 963 shutdown sequence. 964 SHUT_RDWR: Disables further send and receive operations and 965 initiates the SCTP shutdown sequence. 966 It returns 0 on success and -1 in case of an error. 968 The major difference between SCTP and TCP shutdown() is that SCTP 969 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 970 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 971 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 972 the SCTP association while still leaving the socket descriptor open. 973 This allows the caller to receive back any data which SCTP is unable 974 to deliver (see Section 5.3.5 for more information) and receive event 975 notifications. 977 To perform the ABORT operation described in [RFC4960] Section 10.1, 978 an application can use the socket option SO_LINGER. It is described 979 in Section 7.1.4. 981 4.1.8. sendmsg() and recvmsg() 983 With a one-to-one style socket, the application can also use 984 sendmsg() and recvmsg() to transmit data to and receive data from its 985 peer. The semantics is similar to those used in the one-to-many 986 style (see Section 3.1.3), with the following differences: 987 1. When sending, the msg_name field in the msghdr is not used to 988 specify the intended receiver, rather it is used to indicate a 989 preferred peer address if the sender wishes to discourage the 990 stack from sending the message to the primary address of the 991 receiver. If the socket is connected and the transport address 992 given is not part of the current association, the data will not 993 be sent and an SCTP_SEND_FAILED event will be delivered to the 994 application if send failure events are enabled. 995 2. Using sendmsg() on a non-connected one-to-one style socket for 996 implicit connection setup may or may not work depending on the 997 SCTP implementation. 999 4.1.9. getpeername() 1001 Applications use getpeername() to retrieve the primary socket address 1002 of the peer. This call is for TCP compatibility, and is not multi- 1003 homed. It may not work with one-to-many style sockets depending on 1004 the implementation. See Section 8.3 for a multi-homed style version 1005 of the call. 1007 The function prototype is 1009 int getpeername(int sd, 1010 struct sockaddr *address, 1011 socklen_t *len); 1013 and the arguments are: 1014 sd: The socket descriptor to be queried. 1015 address: On return, the peer primary address is stored in this 1016 buffer. If the socket is an IPv4 socket, the address will be 1017 IPv4. If the socket is an IPv6 socket, the address will be either 1018 an IPv6 or IPv4 address. 1019 len: The caller should set the length of address here. On return, 1020 this is set to the length of the returned address. 1021 It returns 0 on success and -1 in case of an error. 1023 If the actual length of the address is greater than the length of the 1024 supplied sockaddr structure, the stored address will be truncated. 1026 5. Data Structures 1028 This section discusses important data structures which are specific 1029 to SCTP and are used with sendmsg() and recvmsg() calls to control 1030 SCTP endpoint operations and to access ancillary information and 1031 notifications. 1033 5.1. The msghdr and cmsghdr Structures 1035 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1036 well as the ancillary data carried in the structure, is the key for 1037 the application to set and get various control information from the 1038 SCTP endpoint. 1040 The msghdr and the related cmsghdr structures are defined and 1041 discussed in detail in [RFC3542]. They are defined as: 1043 struct msghdr { 1044 void *msg_name; /* ptr to socket address structure */ 1045 socklen_t msg_namelen; /* size of socket address structure */ 1046 struct iovec *msg_iov; /* scatter/gather array */ 1047 size_t msg_iovlen; /* # elements in msg_iov */ 1048 void *msg_control; /* ancillary data */ 1049 socklen_t msg_controllen; /* ancillary data buffer length */ 1050 int msg_flags; /* flags on received message */ 1051 }; 1053 struct cmsghdr { 1054 socklen_t cmsg_len; /* #bytes, including this header */ 1055 int cmsg_level; /* originating protocol */ 1056 int cmsg_type; /* protocol-specific type */ 1057 /* followed by unsigned char cmsg_data[]; */ 1058 }; 1060 In the msghdr structure, the usage of msg_name has been discussed in 1061 previous sections (see Section 3.1.3 and Section 4.1.8). 1063 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1064 field) are treated by SCTP as a single user message for both 1065 sendmsg() and recvmsg(). 1067 The msg_flags are not used when sending a message with sendmsg(). 1069 If a notification has arrived, recvmsg() will return the notification 1070 with the MSG_NOTIFICATION flag set in msg_flags. If the 1071 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1072 Section 5.3 for more information about notifications. 1074 If all portions of a data frame or notification have been read, 1075 recvmsg() will return with MSG_EOR set in msg_flags. 1077 5.2. SCTP msg_control Structures 1079 A key element of all SCTP specific socket extensions is the use of 1080 ancillary data to specify and access SCTP specific data via the 1081 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1082 Fine-grained control over initialization and sending parameters are 1083 handled with ancillary data. 1085 Each ancillary data item is proceeded by a struct cmsghdr (see 1086 Section 5.1), which defines the function and purpose of the data 1087 contained in the cmsg_data[] member. 1089 By default on either style socket, SCTP will pass no ancillary data; 1090 Specific ancillary data items can be enabled with socket options 1091 defined for SCTP; see Section 7.4. 1093 Note that all ancillary types are fixed length; see Section 5.4 for 1094 further discussion on this. These data structures use struct 1095 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1096 address format. 1098 Other protocols may also provide ancillary data to the socket layer 1099 consumer. These ancillary data items from other protocols may 1100 intermingle with SCTP data. For example, the IPv6 socket API 1101 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1102 data items. If a socket API consumer enables delivery of both SCTP 1103 and IPv6 ancillary data, they both may appear in the same msg_control 1104 buffer in any order. An application may thus need to handle other 1105 types of ancillary data besides those passed by SCTP. 1107 The sockets application must provide a buffer large enough to 1108 accommodate all ancillary data provided via recvmsg(). If the buffer 1109 is not large enough, the ancillary data will be truncated and the 1110 msghdr's msg_flags will include MSG_CTRUNC. 1112 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1114 This cmsghdr structure provides information for initializing new SCTP 1115 associations with sendmsg(). The SCTP_INITMSG socket option uses 1116 this same data structure. This structure is not used for recvmsg(). 1118 +--------------+-----------+---------------------+ 1119 | cmsg_level | cmsg_type | cmsg_data[] | 1120 +--------------+-----------+---------------------+ 1121 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1122 +--------------+-----------+---------------------+ 1124 The sctp_initmsg structure is defined below: 1126 struct sctp_initmsg { 1127 uint16_t sinit_num_ostreams; 1128 uint16_t sinit_max_instreams; 1129 uint16_t sinit_max_attempts; 1130 uint16_t sinit_max_init_timeo; 1131 }; 1132 sinit_num_ostreams: This is an integer number representing the 1133 number of streams that the application wishes to be able to send 1134 to. This number is confirmed in the SCTP_COMM_UP notification and 1135 must be verified since it is a negotiated number with the remote 1136 endpoint. The default value of 0 indicates to use the endpoint 1137 default value. 1138 sinit_max_instreams: This value represents the maximum number of 1139 inbound streams the application is prepared to support. This 1140 value is bounded by the actual implementation. In other words the 1141 user may be able to support more streams than the Operating 1142 System. In such a case, the Operating System limit overrides the 1143 value requested by the user. The default value of 0 indicates to 1144 use the endpoints default value. 1145 sinit_max_attempts: This integer specifies how many attempts the 1146 SCTP endpoint should make at resending the INIT. This value 1147 overrides the system SCTP 'Max.Init.Retransmits' value. The 1148 default value of 0 indicates to use the endpoints default value. 1149 This is normally set to the system's default 'Max.Init.Retransmit' 1150 value. 1151 sinit_max_init_timeo: This value represents the largest Time-Out or 1152 RTO value (in milliseconds) to use in attempting an INIT. 1153 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1154 upon timeout. For the INIT message this value may override 1155 'RTO.Max'. This value must not influence 'RTO.Max' during data 1156 transmission and is only used to bound the initial setup time. A 1157 default value of 0 indicates to use the endpoints default value. 1158 This is normally set to the system's 'RTO.Max' value (60 seconds). 1160 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1162 This cmsghdr structure specifies SCTP options for sendmsg() and 1163 describes SCTP header information about a received message through 1164 recvmsg(). This structure mixes the send and receive path. 1165 SCTP_SNDINFO described in Section 5.2.4 and SCTP_RCVINFO described in 1166 Section 5.2.5 split this information. These structures should be 1167 used, when possible, since SCTP_SNDRCV is deprecated. 1169 +--------------+-------------+------------------------+ 1170 | cmsg_level | cmsg_type | cmsg_data[] | 1171 +--------------+-------------+------------------------+ 1172 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1173 +--------------+-------------+------------------------+ 1175 The sctp_sndrcvinfo structure is defined below: 1177 struct sctp_sndrcvinfo { 1178 uint16_t sinfo_stream; 1179 uint16_t sinfo_ssn; 1180 uint16_t sinfo_flags; 1181 uint32_t sinfo_ppid; 1182 uint32_t sinfo_context; 1183 uint32_t sinfo_pr_value; 1184 uint32_t sinfo_tsn; 1185 uint32_t sinfo_cumtsn; 1186 sctp_assoc_t sinfo_assoc_id; 1187 }; 1189 sinfo_stream: For recvmsg() the SCTP stack places the message's 1190 stream number in this value. For sendmsg() this value holds the 1191 stream number that the application wishes to send this message to. 1192 If a sender specifies an invalid stream number an error indication 1193 is returned and the call fails. 1194 sinfo_ssn: For recvmsg() this value contains the stream sequence 1195 number that the remote endpoint placed in the DATA chunk. For 1196 fragmented messages this is the same number for all deliveries of 1197 the message (if more than one recvmsg() is needed to read the 1198 message). The sendmsg() call will ignore this parameter. 1199 sinfo_flags: This field may contain any of the following flags and 1200 is composed of a bitwise OR of these values. 1201 recvmsg() flags: 1202 SCTP_UNORDERED: This flag is present when the message was sent 1203 un-ordered. 1204 sendmsg() flags: 1205 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1206 the message. If this flag is clear the datagram is 1207 considered an ordered send. 1208 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1209 the SCTP stack to override the primary destination address 1210 with the address found with the sendto/sendmsg call. 1211 SCTP_ABORT: Setting this flag causes the specified association 1212 to abort by sending an ABORT message to the peer (one-to- 1213 many style only). The ABORT chunk will contain an error 1214 cause 'User Initiated Abort' with cause code 12. The cause 1215 specific information of this error cause is provided in 1216 msg_iov. 1217 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1218 procedure on the specified association. Graceful shutdown 1219 assures that all data queued by both endpoints is 1220 successfully transmitted before closing the association 1221 (one-to-many style only). 1223 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1224 model socket to send the message to all associations that 1225 are currently established on this socket. For the one-to- 1226 one socket, this flag has no effect. 1227 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1228 passed to the remote end in each user message. In recvmsg() this 1229 value is the same information that was passed by the upper layer 1230 in the peer application. Please note that the SCTP stack performs 1231 no byte order modification of this field. For example, if the 1232 DATA chunk has to contain a given value in network byte order, the 1233 SCTP user has to perform the htonl() computation. 1234 sinfo_context: This value is an opaque 32 bit context datum that is 1235 used in the sendmsg() function. This value is passed back to the 1236 upper layer if an error occurs on the send of a message and is 1237 retrieved with each undelivered message (Note: if an endpoint has 1238 done multiple sends, all of which fail, multiple different 1239 sinfo_context values will be returned. One with each user data 1240 message). 1241 sinfo_pr_value: The meaning of this field depends on the PR-SCTP 1242 policy specified by the sinfo_pr_policy field. It is ignored when 1243 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1244 lifetime is specified. 1245 sinfo_tsn: For the receiving side, this field holds a TSN that was 1246 assigned to one of the SCTP Data Chunks. For the sending side it 1247 is ignored. 1248 sinfo_cumtsn: This field will hold the current cumulative TSN as 1249 known by the underlying SCTP layer. Note this field is ignored 1250 when sending. 1251 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1252 the identifier for the association announced in the SCTP_COMM_UP 1253 notification. All notifications for a given association have the 1254 same identifier. Ignored for one-to-one style sockets. 1256 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1258 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1260 This cmsghdr structure specifies SCTP options for SCTP header 1261 information about a received message via recvmsg(). Note that this 1262 structure is an extended version of SCTP_SNDRCV (see Section 5.2.2) 1263 and will only be received if the user has set the socket option 1264 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1265 needed to receive ancillary data. See Section 7.1.22 on this socket 1266 option. Note that next message data is not valid unless the current 1267 message is completely read, i.e. the MSG_EOR is set, in other words 1268 if the application has more data to read from the current message 1269 then no next message information will be available. 1271 SCTP_NXTINFO described in Section 5.2.6 should be used when possible, 1272 since SCTP_EXTRCV is considered deprecated. 1274 +--------------+-------------+------------------------+ 1275 | cmsg_level | cmsg_type | cmsg_data[] | 1276 +--------------+-------------+------------------------+ 1277 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1278 +--------------+-------------+------------------------+ 1280 The sctp_extrcvinfo structure is defined below: 1282 struct sctp_extrcvinfo { 1283 uint16_t sinfo_stream; 1284 uint16_t sinfo_ssn; 1285 uint16_t sinfo_flags; 1286 uint32_t sinfo_ppid; 1287 uint32_t sinfo_context; 1288 uint32_t sinfo_pr_value; 1289 uint32_t sinfo_tsn; 1290 uint32_t sinfo_cumtsn; 1291 uint16_t serinfo_next_flags; 1292 uint16_t serinfo_next_stream; 1293 uint32_t serinfo_next_aid; 1294 uint32_t serinfo_next_length; 1295 uint32_t serinfo_next_ppid; 1296 sctp_assoc_t sinfo_assoc_id; 1297 }; 1299 sinfo_*: Please see Section 5.2.2 for the details for these fields. 1300 serinfo_next_flags: This bitmask will hold one or more of the 1301 following values: 1302 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1303 message information is available i.e.: next_stream, 1304 next_asocid, next_length and next_ppid fields all have valid 1305 values. If this bit is set to 0, then these fields are not 1306 valid and should be ignored. 1307 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1308 next message is completely in the receive buffer. The 1309 next_length field thus contains the entire message size. If 1310 this flag is set to 0, then the next_length field only contains 1311 part of the message size since the message is still being 1312 received (it is being partially delivered). 1313 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1314 the next message to be received was sent by the peer as 1315 unordered. If this bit is not set (i.e the bit is 0) the next 1316 message to be read is an ordered message in the stream 1317 specified. 1319 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1320 the next message to be received is not a message from the peer, 1321 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1322 serinfo_next_stream: This value, when valid (see 1323 serinfo_next_flags), contains the next stream number that will be 1324 received on a subsequent call to one of the receive message 1325 functions. 1326 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1327 contains the next association identification that will be received 1328 on a subsequent call to one of the receive message functions. 1329 serinfo_next_length: This value, when valid (see 1330 serinfo_next_flags), contains the length of the next message that 1331 will be received on a subsequent call to one of the receive 1332 message functions. Note that this length may be a partial length 1333 depending on the settings of next_flags. 1334 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1335 contains the ppid of the next message that will be received on a 1336 subsequent call to one of the receive message functions. 1338 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) 1340 This cmsghdr structure specifies SCTP options for sendmsg(). 1342 +--------------+--------------+---------------------+ 1343 | cmsg_level | cmsg_type | cmsg_data[] | 1344 +--------------+--------------+---------------------+ 1345 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1346 +--------------+--------------+---------------------+ 1348 The sctp_sndinfo structure is defined below: 1350 struct sctp_sndinfo { 1351 uint16_t snd_sid; 1352 uint16_t snd_flags; 1353 uint32_t snd_ppid; 1354 uint32_t snd_context; 1355 sctp_assoc_t snd_assoc_id; 1356 }; 1358 snd_sid: This value holds the stream number that the application 1359 wishes to send this message to. If a sender specifies an invalid 1360 stream number an error indication is returned and the call fails. 1361 snd_flags: This field may contain any of the following flags and is 1362 composed of a bitwise OR of these values. 1364 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1365 message. If this flag is clear the datagram is considered an 1366 ordered send. 1367 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1368 SCTP stack to override the primary destination address with the 1369 address found with the sendto()/sendmsg call. 1370 SCTP_ABORT: Setting this flag causes the specified association to 1371 abort by sending an ABORT message to the peer (one-to-many 1372 style only). The ABORT chunk will contain an error cause 'User 1373 Initiated Abort' with cause code 12. The cause specific 1374 information of this error cause is provided in msg_iov. 1375 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1376 procedures on the specified association. Graceful shutdown 1377 assures that all data queued by both endpoints is successfully 1378 transmitted before closing the association (one-to-many style 1379 only). 1380 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1381 socket to send the message to all associations that are 1382 currently established on this socket. For the one-to-one 1383 socket, this flag has no effect. 1384 snd_ppid: This value in sendmsg() is an unsigned integer that is 1385 passed to the remote end in each user message. Please note that 1386 the SCTP stack performs no byte order modification of this field. 1387 For example, if the DATA chunk has to contain a given value in 1388 network byte order, the SCTP user has to perform the htonl() 1389 computation. 1390 snd_context: This value is an opaque 32 bit context datum that is 1391 used in the sendmsg() function. This value is passed back to the 1392 upper layer if an error occurs on the send of a message and is 1393 retrieved with each undelivered message (Note: if an endpoint has 1394 done multiple sends, all of which fail, multiple different 1395 sinfo_context values will be returned. One with each user data 1396 message). 1397 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1398 the identifier for the association announced in the SCTP_COMM_UP 1399 notification. All notifications for a given association have the 1400 same identifier. Ignored for one-to-one style sockets. 1402 An sctp_sndinfo item always corresponds to the data in msg_iov. 1404 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1406 This cmsghdr structure describes SCTP receive information about a 1407 received message through recvmsg(). 1409 To enable the delivery of this information an application must use 1410 the SCTP_RECVRCVINFO socket option (see Section 7.1.29). 1412 +--------------+--------------+---------------------+ 1413 | cmsg_level | cmsg_type | cmsg_data[] | 1414 +--------------+--------------+---------------------+ 1415 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1416 +--------------+--------------+---------------------+ 1418 The sctp_rcvinfo structure is defined below: 1420 struct sctp_rcvinfo { 1421 uint16_t rcv_sid; 1422 uint16_t rcv_ssn; 1423 uint16_t rcv_flags; 1424 uint32_t rcv_ppid; 1425 uint32_t rcv_tsn; 1426 uint32_t rcv_cumtsn; 1427 sctp_assoc_t rcv_assoc_id; 1428 }; 1430 rcv_sid: The SCTP stack places the message's stream number in this 1431 value. 1432 rcv_ssn: This value contains the stream sequence number that the 1433 remote endpoint placed in the DATA chunk. For fragmented messages 1434 this is the same number for all deliveries of the message (if more 1435 than one recvmsg() is needed to read the message). 1436 rcv_flags: This field may contain any of the following flags and is 1437 composed of a bitwise OR of these values. 1439 SCTP_UNORDERED: This flag is present when the message was sent 1440 un-ordered. 1441 rcv_ppid: This value is the same information that was passed by the 1442 upper layer in the peer application. Please note that the SCTP 1443 stack performs no byte order modification of this field. For 1444 example, if the DATA chunk has to contain a given value in network 1445 byte order, the SCTP user has to perform the htonl() computation. 1446 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1447 Data Chunks. 1448 rcv_cumtsn: This field will hold the current cumulative TSN as known 1449 by the underlying SCTP layer. 1450 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1451 the identifier for the association announced in the SCTP_COMM_UP 1452 notification. All notifications for a given association have the 1453 same identifier. Ignored for one-to-one style sockets. 1455 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1457 5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1459 This cmsghdr structure describes SCTP receive information of the next 1460 message which will be delivered through recvmsg() if this information 1461 is already available when delivering the current message. 1463 It uses the same structure as the SCTP Receive Information Structure. 1465 To enable the delivery of this information an application must use 1466 the SCTP_RECVNXTINFO socket option (see Section 7.1.30). 1468 +--------------+--------------+---------------------+ 1469 | cmsg_level | cmsg_type | cmsg_data[] | 1470 +--------------+--------------+---------------------+ 1471 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo | 1472 +--------------+--------------+---------------------+ 1474 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1476 This cmsghdr structure specifies SCTP options for sendmsg(). 1478 +--------------+-------------+--------------------+ 1479 | cmsg_level | cmsg_type | cmsg_data[] | 1480 +--------------+-------------+--------------------+ 1481 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1482 +--------------+-------------+--------------------+ 1484 The sctp_prinfo structure is defined below: 1486 struct sctp_prinfo { 1487 uint16_t pr_policy; 1488 uint32_t pr_value; 1489 }; 1491 pr_policy: This specifies which PR-SCTP policy is used. Using 1492 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1493 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1494 defined in [RFC3758] is used. In this case, the lifetime is 1495 provided in pr_value. 1496 pr_value: The meaning of this field depends on the PR-SCTP policy 1497 specified by the pr_policy field. It is ignored when 1498 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1499 lifetime in milliseconds is specified. 1501 An sctp_prinfo item always corresponds to the data in msg_iov. 1503 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1505 This cmsghdr structure specifies SCTP options for sendmsg(). 1507 +--------------+---------------+----------------------+ 1508 | cmsg_level | cmsg_type | cmsg_data[] | 1509 +--------------+---------------+----------------------+ 1510 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1511 +--------------+---------------+----------------------+ 1513 The sctp_authinfo structure is defined below: 1515 struct sctp_authinfo { 1516 uint16_t auth_keyid; 1517 }; 1519 auth_keyid: This specifies the shared key identifier used for 1520 sending the user message. 1522 An sctp_authinfo item always corresponds to the data in msg_iov. 1523 Please note that the SCTP implementation must not bundle user 1524 messages that needs to be authenticated using different shared key 1525 identifiers. 1527 5.2.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4) 1529 This cmsghdr structure specifies SCTP options for sendmsg(). 1531 +--------------+----------------+----------------+ 1532 | cmsg_level | cmsg_type | cmsg_data[] | 1533 +--------------+----------------+----------------+ 1534 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1535 +--------------+----------------+----------------+ 1537 This ancillary data can be used to provide more than one destination 1538 address to sendmsg(). It can be used to implement sctp_sendv() using 1539 send_msg(). 1541 5.2.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 1543 This cmsghdr structure specifies SCTP options for sendmsg(). 1545 +--------------+----------------+-----------------+ 1546 | cmsg_level | cmsg_type | cmsg_data[] | 1547 +--------------+----------------+-----------------+ 1548 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1549 +--------------+----------------+-----------------+ 1551 This ancillary data can be used to provide more than one destination 1552 address to sendmsg(). It can be used to implement sctp_sendv() using 1553 send_msg(). 1555 5.3. SCTP Events and Notifications 1557 An SCTP application may need to understand and process events and 1558 errors that happen on the SCTP stack. These events include network 1559 status changes, association startups, remote operational errors and 1560 undeliverable messages. All of these can be essential for the 1561 application. 1563 When an SCTP application layer does a recvmsg() the message read is 1564 normally a data message from a peer endpoint. If the application 1565 wishes to have the SCTP stack deliver notifications of non-data 1566 events, it sets the appropriate socket option for the notifications 1567 it wants. See Section 7.4 for these socket options. When a 1568 notification arrives, recvmsg() returns the notification in the 1569 application-supplied data buffer via msg_iov, and sets 1570 MSG_NOTIFICATION in msg_flags. 1572 This section details the notification structures. Every notification 1573 structure carries some common fields which provide general 1574 information. 1576 A recvmsg() call will return only one notification at a time. Just 1577 as when reading normal data, it may return part of a notification if 1578 the msg_iov buffer is not large enough. If a single read is not 1579 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1580 reading the notification before subsequent data can arrive. 1582 5.3.1. SCTP Notification Structure 1584 The notification structure is defined as the union of all 1585 notification types. 1587 union sctp_notification { 1588 struct sctp_tlv { 1589 uint16_t sn_type; /* Notification type. */ 1590 uint16_t sn_flags; 1591 uint32_t sn_length; 1592 } sn_header; 1593 struct sctp_assoc_change sn_assoc_change; 1594 struct sctp_paddr_change sn_paddr_change; 1595 struct sctp_remote_error sn_remote_error; 1596 struct sctp_send_failed sn_send_failed; 1597 struct sctp_shutdown_event sn_shutdown_event; 1598 struct sctp_adaptation_event sn_adaptation_event; 1599 struct sctp_pdapi_event sn_pdapi_event; 1600 struct sctp_authkey_event sn_auth_event; 1601 struct sctp_sender_dry_event sn_sender_dry_event; 1602 }; 1604 sn_type: The following list describes the SCTP notification and 1605 event types for the field sn_type. 1606 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1607 either been opened or closed. Refer to Section 5.3.2 for 1608 details. 1609 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1610 part of an existing association has experienced a change of 1611 state (e.g. a failure or return to service of the reachability 1612 of an endpoint via a specific transport address). Please see 1613 Section 5.3.3 for data structure details. 1614 SCTP_REMOTE_ERROR: The attached error message is an Operational 1615 Error received from the remote peer. It includes the complete 1616 TLV sent by the remote endpoint. See Section 5.3.4 for the 1617 detailed format. 1618 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1619 remote endpoint. This structure includes the original 1620 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1621 structure uses the sctp_sndrcvinfo per Section 5.3.5. 1622 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1623 data should be sent on this socket. 1624 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1625 indicated adaptation layer. Please see Section 5.3.7. 1626 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1627 receiver that the partial delivery has been aborted. This may 1628 indicate the association is about to be aborted. Please see 1629 Section 5.3.8. 1630 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1631 receiver that either an error occurred on authentication, or a 1632 new key was made active. See Section 5.3.9. 1634 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1635 application that the sender has no user data queued anymore, 1636 neither for transmission nor retransmission. See 1637 Section 5.3.10. 1638 sn_flags: These are notification-specific flags. 1639 sn_length: This is the length of the whole sctp_notification 1640 structure including the sn_type, sn_flags, and sn_length fields. 1642 5.3.2. SCTP_ASSOC_CHANGE 1644 Communication notifications inform the ULP that an SCTP association 1645 has either begun or ended. The identifier for a new association is 1646 provided by this notification. The notification information has the 1647 following format: 1649 struct sctp_assoc_change { 1650 uint16_t sac_type; 1651 uint16_t sac_flags; 1652 uint32_t sac_length; 1653 uint16_t sac_state; 1654 uint16_t sac_error; 1655 uint16_t sac_outbound_streams; 1656 uint16_t sac_inbound_streams; 1657 sctp_assoc_t sac_assoc_id; 1658 uint8_t sac_info[]; 1659 }; 1661 sac_type: It should be SCTP_ASSOC_CHANGE. 1662 sac_flags: Currently unused. 1663 sac_length: This field is the total length of the notification data, 1664 including the notification header. 1665 sac_state: This field holds one of a number of values that 1666 communicate the event that happened to the association. They 1667 include: 1668 SCTP_COMM_UP: A new association is now ready and data may be 1669 exchanged with this peer. When an association has been 1670 established successfully, this notification should be the first 1671 one. 1672 SCTP_COMM_LOST: The association has failed. The association is 1673 now in the closed state. If SEND_FAILED notifications are 1674 turned on, an SCTP_COMM_LOST is accompanied by a series of 1675 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1676 message. 1677 SCTP_RESTART: SCTP has detected that the peer has restarted. 1679 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1680 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1681 blocking mode is set and data was sent (on a one-to-many style 1682 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1683 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1684 message. 1685 sac_error: If the state was reached due to an error condition (e.g. 1686 SCTP_COMM_LOST) any relevant error information is available in 1687 this field. This corresponds to the protocol error codes defined 1688 in [RFC4960]. 1689 sac_outbound_streams: 1690 sac_inbound_streams: The maximum number of streams allowed in each 1691 direction are available in sac_outbound_streams and sac_inbound 1692 streams. 1693 sac_assoc_id: The association id field holds the identifier for the 1694 association. All notifications for a given association have the 1695 same association identifier. For a one-to-one style socket, this 1696 field is ignored. 1697 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1698 received for this association, sac_info[] contains the complete 1699 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1700 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1701 may contain an array of uint8_t describing the features that the 1702 current association supports. Features may include 1703 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1704 extension described in [RFC3758]. 1705 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1706 extension described in [RFC4895]. 1707 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1708 extension described in [RFC5061]. 1709 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 1710 local endpoints use separate send and/or receive buffers for 1711 each SCTP association. 1713 5.3.3. SCTP_PEER_ADDR_CHANGE 1715 When a destination address of a multi-homed peer encounters a state 1716 change a peer address change event is sent. The notification has the 1717 following format: 1719 struct sctp_paddr_change { 1720 uint16_t spc_type; 1721 uint16_t spc_flags; 1722 uint32_t spc_length; 1723 struct sockaddr_storage spc_aaddr; 1724 uint32_t spc_state; 1725 uint32_t spc_error; 1726 sctp_assoc_t spc_assoc_id; 1728 } 1730 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 1731 spc_flags: Currently unused. 1732 spc_length: This field is the total length of the notification data, 1733 including the notification header. 1734 spc_aaddr: The affected address field holds the remote peer's 1735 address that is encountering the change of state. 1736 spc_state: This field holds one of a number of values that 1737 communicate the event that happened to the address. They include: 1738 SCTP_ADDR_AVAILABLE: This address is now reachable. This 1739 notification is provided whenever an address becomes reachable 1740 and was unreachable. 1741 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 1742 reached. Any data sent to this address is rerouted to an 1743 alternate until this address becomes reachable. This 1744 notification is provided whenever an address becomes 1745 unreachable and was reachable. 1746 SCTP_ADDR_REMOVED: The address is no longer part of the 1747 association. 1748 SCTP_ADDR_ADDED: The address is now part of the association. 1749 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 1750 primary destination address. 1751 SCTP_ADDR_CONFIRMED: This address has now been confirmed as a 1752 valid address. This notification is provided once for each 1753 address as soon as the address is confirmed. 1754 spc_error: If the state was reached due to any error condition (e.g. 1755 SCTP_ADDR_UNREACHABLE) any relevant error information is available 1756 in this field. 1757 spc_assoc_id: The association id field holds the identifier for the 1758 association. All notifications for a given association have the 1759 same association identifier. For a one-to-one style socket, this 1760 field is ignored. 1762 5.3.4. SCTP_REMOTE_ERROR 1764 A remote peer may send an Operational Error message to its peer. 1765 This message indicates a variety of error conditions on an 1766 association. The entire ERROR chunk as it appears on the wire is 1767 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 1768 specification [RFC4960] and any extensions for a list of possible 1769 error formats. An SCTP error notification has the following format: 1771 struct sctp_remote_error { 1772 uint16_t sre_type; 1773 uint16_t sre_flags; 1774 uint32_t sre_length; 1775 uint16_t sre_error; 1776 sctp_assoc_t sre_assoc_id; 1777 uint8_t sre_data[]; 1778 }; 1780 sre_type: It should be SCTP_REMOTE_ERROR. 1781 sre_flags: Currently unused. 1782 sre_length: This field is the total length of the notification data, 1783 including the notification header and the contents of sre_data. 1784 sre_error: This value represents one of the Operational Error causes 1785 defined in the SCTP specification, in network byte order. 1786 sre_assoc_id: The association id field holds the identifier for the 1787 association. All notifications for a given association have the 1788 same association identifier. For a one-to-one style socket, this 1789 field is ignored. 1790 sre_data: This contains the ERROR chunk as defined in the SCTP 1791 specification [RFC4960] Section 3.3.10. 1793 5.3.5. SCTP_SEND_FAILED 1795 Please note that this notification is deprecated. Use 1796 SCTP_SEND_FAILED_EVENT instead. 1798 If SCTP cannot deliver a message, it can return back the message as a 1799 notification if the SCTP_SEND_FAILED event is enabled. The 1800 notification has the following format: 1802 struct sctp_send_failed { 1803 uint16_t ssf_type; 1804 uint16_t ssf_flags; 1805 uint32_t ssf_length; 1806 uint32_t ssf_error; 1807 struct sctp_sndrcvinfo ssf_info; 1808 sctp_assoc_t ssf_assoc_id; 1809 uint8_t ssf_data[]; 1810 }; 1812 ssf_type: It should be SCTP_SEND_FAILED. 1813 ssf_flags: The flag value will take one of the following values: 1814 SCTP_DATA_UNSENT: Indicates that the data was never put on the 1815 wire. 1817 SCTP_DATA_SENT: Indicates that the data was put on the wire. 1818 Note that this does not necessarily mean that the data was (or 1819 was not) successfully delivered. 1820 ssf_length: This field is the total length of the notification data, 1821 including the notification header and the payload in ssf_data. 1822 ssf_error: This value represents the reason why the send failed, and 1823 if set, will be an SCTP protocol error code as defined in 1824 [RFC4960] Section 3.3.10. 1825 ssf_info: The send information associated with the undelivered 1826 message. The ssf_info.sinfo_flags field will also contain an 1827 indication if the beginning of the message and/or end of the 1828 message is present. In cases where no data has been sent on the 1829 wire, this field will have or'ed-in the value SCTP_DATA_NOT_FRAG, 1830 which is a composition of both a "BEGIN" and "END" fragmentation 1831 bit. In cases where only part of the data has been sent, this 1832 field will have or'ed in the value SCTP_DATA_LAST_FRAG, which 1833 corresponds to the "END" bit. Note that the message itself may be 1834 more than one chunk. If the ssf_info.sinfo_flags field holds 1835 neither of these two values then a piece that has been fragmented 1836 and sent but not acknowledged is present. This piece is from an 1837 unspecified position in the message and the application can make 1838 no assumptions about the data itself. Applications wanting to 1839 examine a recovered message should look for the 1840 SCTP_DATA_NOT_FRAG. Without this flag the application should 1841 assume part of the message arrived and take appropriate steps to 1842 audit and recover any lost or missing data. 1843 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 1844 identifier for the association. All notifications for a given 1845 association have the same association identifier. For a one-to- 1846 one style socket, this field is ignored. 1847 ssf_data: The undelivered message or part of the undelivered message 1848 will be present in the ssf_data field. Note that the 1849 ssf_info.sinfo_flags field as noted above should be used to 1850 determine if a complete message is present or just a piece of the 1851 message. Note that only user data is present in this field, any 1852 chunk headers or SCTP common headers must be removed by the SCTP 1853 stack. 1855 5.3.6. SCTP_SHUTDOWN_EVENT 1857 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1858 inform the application that it should cease sending data. 1860 struct sctp_shutdown_event { 1861 uint16_t sse_type; 1862 uint16_t sse_flags; 1863 uint32_t sse_length; 1864 sctp_assoc_t sse_assoc_id; 1866 }; 1868 sse_type: It should be SCTP_SHUTDOWN_EVENT. 1869 sse_flags: Currently unused. 1870 sse_length: This field is the total length of the notification data, 1871 including the notification header. It will generally be sizeof 1872 (struct sctp_shutdown_event). 1873 sse_flags: Currently unused. 1874 sse_assoc_id: The association id field holds the identifier for the 1875 association. All notifications for a given association have the 1876 same association identifier. For a one-to-one style socket, this 1877 field is ignored. 1879 5.3.7. SCTP_ADAPTATION_INDICATION 1881 When a peer sends an Adaptation Layer Indication parameter as 1882 described in [RFC5061], SCTP delivers this notification to inform the 1883 application about the peer's adaptation layer indication. 1885 struct sctp_adaptation_event { 1886 uint16_t sai_type; 1887 uint16_t sai_flags; 1888 uint32_t sai_length; 1889 uint32_t sai_adaptation_ind; 1890 sctp_assoc_t sai_assoc_id; 1891 }; 1893 sai_type: It should be SCTP_ADAPTATION_INDICATION. 1894 sai_flags: Currently unused. 1895 sai_length: This field is the total length of the notification data, 1896 including the notification header. It will generally be sizeof 1897 (struct sctp_adaptation_event). 1898 sai_adaptation_ind: This field holds the bit array sent by the peer 1899 in the adaptation layer indication parameter. The bits are in 1900 network byte order. 1901 sai_assoc_id: The association id field holds the identifier for the 1902 association. All notifications for a given association have the 1903 same association identifier. For a one-to-one style socket, this 1904 field is ignored. 1906 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT 1908 When a receiver is engaged in a partial delivery of a message this 1909 notification will be used to indicate various events. 1911 struct sctp_pdapi_event { 1912 uint16_t pdapi_type; 1913 uint16_t pdapi_flags; 1914 uint32_t pdapi_length; 1915 uint32_t pdapi_indication; 1916 uint32_t pdapi_stream; 1917 uint32_t pdapi_seq; 1918 sctp_assoc_t pdapi_assoc_id; 1919 }; 1921 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 1922 pdapi_flags: Currently unused. 1923 pdapi_length: This field is the total length of the notification 1924 data, including the notification header. It will generally be 1925 sizeof(struct sctp_pdapi_event). 1926 pdapi_indication: This field holds the indication being sent to the 1927 application. Currently there is only one defined value: 1928 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 1929 delivery of a user message has been aborted. This happens, for 1930 example, if an association is aborted while a partial delivery 1931 is going on or the user message gets abandoned using PR-SCTP 1932 while the partial delivery of this message is going on. 1933 pdapi_stream: This field holds the stream on which the partial 1934 delivery event happened. 1935 pdapi_seq: This field holds the stream sequence number which was 1936 being partially delivered. 1937 pdapi_assoc_id: The association id field holds the identifier for 1938 the association. All notifications for a given association have 1939 the same association identifier. For a one-to-one style socket 1940 this field is ignored. 1942 5.3.9. SCTP_AUTHENTICATION_EVENT 1944 [RFC4895] defines an extension to authenticate SCTP messages. The 1945 following notification is used to report different events relating to 1946 the use of this extension. 1948 struct sctp_authkey_event { 1949 uint16_t auth_type; 1950 uint16_t auth_flags; 1951 uint32_t auth_length; 1952 uint16_t auth_keynumber; 1953 uint32_t auth_indication; 1954 sctp_assoc_t auth_assoc_id; 1955 }; 1956 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 1957 auth_flags: Currently unused. 1958 auth_length: This field is the total length of the notification 1959 data, including the notification header. It will generally be 1960 sizeof (struct sctp_authkey_event). 1961 auth_keynumber: This field holds the keynumber for the affected key 1962 indicated in the event (depends on auth_indication). 1963 auth_indication: This field holds the error or indication being 1964 reported. The following values are currently defined: 1965 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 1966 made active (used for the first time by the peer) and is now 1967 the active key. The auth_keynumber field holds the user 1968 specified key number. 1969 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 1970 support SCTP AUTH as defined in [RFC4895]. 1971 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 1972 implementation will not use the key identifier specified in 1973 auth_keynumber anymore. 1974 auth_assoc_id: The association id field holds the identifier for the 1975 association. All notifications for a given association have the 1976 same association identifier. For a one-to-one style socket this 1977 field is ignored. 1979 5.3.10. SCTP_SENDER_DRY_EVENT 1981 When the SCTP implementation has no user data anymore to send or 1982 retransmit, this notification is given to the user. If the user 1983 subscribes to this event and SCTP has no user data to send or 1984 retransmit at this point of time, this notification is also given to 1985 the user. 1987 struct sctp_sender_dry_event { 1988 uint16_t sender_dry_type; 1989 uint16_t sender_dry_flags; 1990 uint32_t sender_dry_length; 1991 sctp_assoc_t sender_dry_assoc_id; 1992 }; 1994 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 1995 sender_dry_flags: Currently unused. 1996 sender_dry_length: This field is the total length of the 1997 notification data, including the notification header. It will 1998 generally be sizeof(struct sctp_sender_dry_event). 1999 sender_dry_assoc_id: The association id field holds the identifier 2000 for the association. All notifications for a given association 2001 have the same association identifier. For a one-to-one style 2002 socket this field is ignored. 2004 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT 2006 Notifications, when subscribed to, are reliable. They are always 2007 delivered as long as there is space in the socket receive buffer. 2008 However, if an implementation experiences a notification storm, it 2009 may run out of socket buffer space. When this occurs it may wish to 2010 disable notifications. If the implementation chooses to do this, it 2011 will append a final notification SCTP_NOTIFICATIONS_STOPPED_EVENT. 2012 This notification is a union sctp_notification, where only the struct 2013 sctp_tlv (see the union above) is used. It only contains this type 2014 in the sn_type field, the sn_length field set to the sizeof an 2015 sctp_tlv structure and the sn_flags set to 0. If an application 2016 receives this notification, it will need to resubscribe to any 2017 notifications of interest to it, except for the data io event. 2019 An endpoint is automatically subscribed to this event as soon as it 2020 is subscribed to any event other than data io events. 2022 5.3.12. SCTP_SEND_FAILED_EVENT 2024 If SCTP cannot deliver a message, it can return back the message as a 2025 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2026 notification has the following format: 2028 struct sctp_send_failed { 2029 uint16_t ssf_type; 2030 uint16_t ssf_flags; 2031 uint32_t ssf_length; 2032 uint32_t ssf_error; 2033 struct sctp_sndinfo ssf_info; 2034 sctp_assoc_t ssf_assoc_id; 2035 uint8_t ssf_data[]; 2036 }; 2038 ssf_type: It should be SCTP_SEND_FAILED_EVENT. 2039 ssf_flags: The flag value will take one of the following values: 2040 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2041 wire. 2042 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2043 Note that this does not necessarily mean that the data was (or 2044 was not) successfully delivered. 2045 ssf_length: This field is the total length of the notification data, 2046 including the notification header and the payload in ssf_data. 2047 ssf_error: This value represents the reason why the send failed, and 2048 if set, will be an SCTP protocol error code as defined in 2049 [RFC4960] Section 3.3.10. 2051 ssf_info: The send information associated with the undelivered 2052 message. The ssf_info.snd_flags field will also contain an 2053 indication if the beginning of the message and/or end of the 2054 message is present. In cases where no data has been sent on the 2055 wire, this field will have or'ed in the value SCTP_DATA_NOT_FRAG, 2056 which is a composition of both a "BEGIN" and "END" fragmentation 2057 bit. In cases where only part of the data has been sent, this 2058 field will have or'ed in the value SCTP_DATA_LAST_FRAG, which 2059 corresponds to the "END" bit. Note that the message itself may be 2060 more than one chunk. If the ssf_info.snd_flags field holds 2061 neither of these two values then a piece that has been fragmented 2062 and sent but not acknowledged is present. This piece is from an 2063 unspecified position in the message and the application can make 2064 no assumptions about the data itself. Applications wanting to 2065 examine a recovered message should look for the 2066 SCTP_DATA_NOT_FRAG. Without this flag the application should 2067 assume part of the message arrived and take appropriate steps to 2068 audit and recover any lost or missing data. 2069 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 2070 identifier for the association. All notifications for a given 2071 association have the same association identifier. For a one-to- 2072 one style socket, this field is ignored. 2073 ssf_data: The undelivered message or part of the undelivered message 2074 will be present in the ssf_data field. Note that the 2075 ssf_info.sinfo_flags field as noted above should be used to 2076 determine if a complete message is present or just a piece of the 2077 message. Note that only user data is present in this field, any 2078 chunk headers or SCTP common headers must be removed by the SCTP 2079 stack. 2081 5.4. Ancillary Data Considerations and Semantics 2083 Programming with ancillary socket data contains some subtleties and 2084 pitfalls, which are discussed below. 2086 5.4.1. Multiple Items and Ordering 2088 Multiple ancillary data items may be included in any call to 2089 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 2090 items, or both. 2092 The ordering of ancillary data items (either by SCTP or another 2093 protocol) is not significant and is implementation-dependent, so 2094 applications must not depend on any ordering. 2096 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 2097 correspond to the data in the msghdr's msg_iov member. There can be 2098 only one single such type ancillary data for each sendmsg() or 2099 recvmsg() call. 2101 5.4.2. Accessing and Manipulating Ancillary Data 2103 Applications can infer the presence of data or ancillary data by 2104 examining the msg_iovlen and msg_controllen msghdr members, 2105 respectively. 2107 Implementations may have different padding requirements for ancillary 2108 data, so portable applications should make use of the macros 2109 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 2110 [RFC3542] and the SCTP implementation's documentation for more 2111 information. The following is an example, from [RFC3542], 2112 demonstrating the use of these macros to access ancillary data: 2114 struct msghdr msg; 2115 struct cmsghdr *cmsgptr; 2117 /* fill in msg */ 2119 /* call recvmsg() */ 2121 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 2122 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 2123 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 2124 u_char *ptr; 2126 ptr = CMSG_DATA(cmsgptr); 2127 /* process data pointed to by ptr */ 2128 } 2129 } 2131 5.4.3. Control Message Buffer Sizing 2133 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2134 ancillary data will often be fundamental to the correct and sane 2135 operation of the sockets application. This is particularly true of 2136 the one-to-many semantics, but also of the one-to-one semantics. For 2137 example, if an application needs to send and receive data on 2138 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2139 ancillary data is indispensable. 2141 Given that some ancillary data is critical, and that multiple 2142 ancillary data items may appear in any order, applications should be 2143 carefully written to always provide a large enough buffer to contain 2144 all possible ancillary data that can be presented by recvmsg(). If 2145 the buffer is too small, and crucial data is truncated, it may pose a 2146 fatal error condition. 2148 Thus, it is essential that applications be able to deterministically 2149 calculate the maximum required buffer size to pass to recvmsg(). One 2150 constraint imposed on this specification that makes this possible is 2151 that all ancillary data definitions are of a fixed length. One way 2152 to calculate the maximum required buffer size might be to take the 2153 sum the sizes of all enabled ancillary data item structures, as 2154 calculated by CMSG_SPACE. For example, if we enabled 2155 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 2156 and allocate the buffer size as follows: 2158 size_t total; 2159 void *buf; 2161 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 2162 CMSG_SPACE(sizeof (struct in6_pktinfo)); 2164 buf = malloc(total); 2166 We could then use this buffer (buf) for msg_control on each call to 2167 recvmsg() and be assured that we would not lose any ancillary data to 2168 truncation. 2170 6. Common Operations for Both Styles 2172 6.1. send(), recv(), sendto(), and recvfrom() 2174 Applications can use send() and sendto() to transmit data to the peer 2175 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2176 data from the peer. 2178 The function prototypes are 2180 ssize_t send(int sd, 2181 const void *msg, 2182 size_t len, 2183 int flags); 2185 ssize_t sendto(int sd, 2186 const void *msg, 2187 size_t len, 2188 int flags, 2189 const struct sockaddr *to, 2190 socklen_t tolen); 2192 ssize_t recv(int sd, 2193 void *buf, 2194 size_t len, 2195 int flags); 2197 ssize_t recvfrom(int sd, 2198 void *buf, 2199 size_t len, 2200 int flags, 2201 struct sockaddr *from, 2202 socklen_t *fromlen); 2204 and the arguments are 2205 sd: The socket descriptor of an SCTP endpoint. 2206 msg: The message to be sent. 2207 len: the size of the message or the size of the buffer. 2208 to: one of the peer addresses of the association to be used to send 2209 the message. 2210 tolen: The size of the address. 2211 buf: The buffer to store a received message. 2212 from: The buffer to store the peer address used to send the received 2213 message. 2214 fromlen: The size of the from address. 2215 flags: (described below). 2217 These calls give access to only basic SCTP protocol features. If 2218 either peer in the association uses multiple streams, or sends 2219 unordered data, these calls will usually be inadequate, and may 2220 deliver the data in unpredictable ways. 2222 SCTP has the concept of multiple streams in one association. The 2223 above calls do not allow the caller to specify on which stream a 2224 message should be sent. The system uses stream 0 as the default 2225 stream for send() and sendto(). recv() and recvfrom() return data 2226 from any stream, but the caller can not distinguish the different 2227 streams. This may result in data seeming to arrive out of order. 2228 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2229 provide no indication. 2231 SCTP is message based. The msg buffer above in send() and sendto() 2232 is considered to be a single message. This means that if the caller 2233 wants to send a message that is composed by several buffers, the 2234 caller needs to combine them before calling send() or sendto(). 2235 Alternately, the caller can use sendmsg() to do that without 2236 combining them. Sending a message using send() or sendto() is atomic 2237 unless explicit EOR marking is enabled on the socket specified by sd. 2238 Using sendto() on a non-connected one-to-one style socket for 2239 implicit connection setup may or may not work depending on the SCTP 2240 implementation. recv() and recvfrom() cannot distinguish message 2241 boundaries. 2243 In receiving, if the buffer supplied is not large enough to hold a 2244 complete message, the receive call acts like a stream socket and 2245 returns as much data as will fit in the buffer. 2247 Note, the send() and recv() calls may not be used for a one-to-many 2248 style socket. 2250 Note, if an application calls a send() or sendto() function with no 2251 user data the SCTP implementation should reject the request with an 2252 appropriate error message. An implementation is not allowed to send 2253 a DATA chunk with no user data [RFC4960]. 2255 6.2. setsockopt() and getsockopt() 2257 Applications use setsockopt() and getsockopt() to set or retrieve 2258 socket options. Socket options are used to change the default 2259 behavior of socket calls. They are described in Section 7. 2261 The function prototypes are 2263 int getsockopt(int sd, 2264 int level, 2265 int optname, 2266 void *optval, 2267 socklen_t *optlen); 2269 and 2271 int setsockopt(int sd, 2272 int level, 2273 int optname, 2274 const void *optval, 2275 socklen_t optlen); 2277 and the arguments are 2278 sd: The socket descriptor. 2279 level: Set to IPPROTO_SCTP for all SCTP options. 2280 optname: The option name. 2281 optval: The buffer to store the value of the option. 2282 optlen: The size of the buffer (or the length of the option 2283 returned). 2284 They return 0 on success and -1 in case of an error. 2286 All socket options set on a one-to-one style listening socket also 2287 apply to all accepted sockets. For one-to-many style sockets often a 2288 socket option will pass a structure that includes an assoc_id field. 2289 This field can be filled with the association id of a particular 2290 association and unless otherwise specified can be filled with one of 2291 the following constants: 2292 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2293 after this socket option will be affected by this call. 2294 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2295 associations will be affected by this call, future associations 2296 will still receive the previous default value. 2297 SCTP_ALL_ASSOC: Specifies that all current and future associations 2298 will be affected by this call. 2300 6.3. read() and write() 2302 Applications can use read() and write() to send and receive data to 2303 and from a peer. They have the same semantics as send() and recv() 2304 except that the flags parameter cannot be used. 2306 6.4. getsockname() 2308 Applications use getsockname() to retrieve the locally-bound socket 2309 address of the specified socket. This is especially useful if the 2310 caller let SCTP choose a local port. This call is for single homed 2311 endpoints. It does not work well with multi-homed endpoints. See 2312 Section 8.5 for a multi-homed version of the call. 2314 The function prototype is 2316 int getsockname(int sd, 2317 struct sockaddr *address, 2318 socklen_t *len); 2320 and the arguments are 2321 sd: The socket descriptor to be queried. 2322 address: On return, one locally bound address (chosen by the SCTP 2323 stack) is stored in this buffer. If the socket is an IPv4 socket, 2324 the address will be IPv4. If the socket is an IPv6 socket, the 2325 address will be either an IPv6 or IPv4 address. 2326 len: The caller should set the length of the address here. On 2327 return, this is set to the length of the returned address. 2328 It returns 0 on success and -1 in case of an error. 2330 If the actual length of the address is greater than the length of the 2331 supplied sockaddr structure, the stored address will be truncated. 2333 If the socket has not been bound to a local name, the value stored in 2334 the object pointed to by address is unspecified. 2336 6.5. Implicit Association Setup 2338 The application can begin sending and receiving data using the 2339 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2340 through any explicit association setup procedures (i.e., no connect() 2341 calls required). 2343 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2344 sender finds that no association exists between the sender and the 2345 intended receiver (identified by the address passed either in the 2346 msg_name field of msghdr structure in the sendmsg() call or the 2347 dest_addr field in the sendto() call), the SCTP stack will 2348 automatically setup an association to the intended receiver. 2350 Upon the successful association setup an SCTP_COMM_UP notification 2351 will be dispatched to the socket at both the sender and receiver 2352 side. This notification can be read by the recvmsg() system call 2353 (see Section 3.1.3). 2355 Note, if the SCTP stack at the sender side supports bundling, the 2356 first user message may be bundled with the COOKIE ECHO message 2357 [RFC4960]. 2359 When the SCTP stack sets up a new association implicitly, the 2360 SCTP_INIT type ancillary data may also be passed along (see 2361 Section 5.2.1 for details of the data structures) to change some 2362 parameters used in setting up a new association. 2364 If this information is not present in the sendmsg() call, or if the 2365 implicit association setup is triggered by a sendto() call, the 2366 default association initialization parameters will be used. These 2367 default association parameters may be set with respective 2368 setsockopt() calls or be left to the system defaults. 2370 Implicit association setup cannot be initiated by send() calls. 2372 7. Socket Options 2374 The following sub-section describes various SCTP level socket options 2375 that are common to both styles. SCTP associations can be multi- 2376 homed. Therefore, certain option parameters include a 2377 sockaddr_storage structure to select which peer address the option 2378 should be applied to. 2380 For the one-to-many style sockets, an sctp_assoc_t (association ID) 2381 parameter is used to identify the association instance that the 2382 operation affects. So it must be set when using this style. 2384 For the one-to-one style sockets and branched off one-to-many style 2385 sockets (see Section 8.2) this association ID parameter is ignored. 2387 Note that socket or IP level options are set or retrieved per socket. 2388 This means that for one-to-many style sockets, the options will be 2389 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2390 association ID) belonging to the socket. For one-to-one style, these 2391 options will be applied to all peer addresses of the association 2392 controlled by the socket. Applications should be careful in setting 2393 those options. 2395 For some IP stacks getsockopt() is read-only; so a new interface will 2396 be needed when information must be passed both into and out of the 2397 SCTP stack. The syntax for sctp_opt_info() is 2399 int sctp_opt_info(int sd, 2400 sctp_assoc_t id, 2401 int opt, 2402 void *arg, 2403 socklen_t *size); 2405 The sctp_opt_info() call is a replacement for getsockopt() only and 2406 will not set any options associated with the specified socket. A 2407 setsockopt() must be used to set any writeable option. 2409 For one-to-many style sockets, id specifies the association to query. 2410 For one-to-one style sockets, id is ignored. For one-to-many 2411 sockets, any association identifier in the structure provided as arg 2412 is ignored and id takes precedence. 2414 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used here. 2415 Using them will result in an error (returning -1 and errno set to 2416 EINVAL). SCTP_FUTURE_ASSOC can be used to query information for 2417 future associations. 2419 The field opt specifies which SCTP socket option to get. It can get 2420 any socket option currently supported that requests information 2421 (either read/write options or read only) such as: 2422 SCTP_RTOINFO 2423 SCTP_ASSOCINFO 2424 SCTP_DEFAULT_SEND_PARAM 2425 SCTP_GET_PEER_ADDR_INFO 2426 SCTP_PRIMARY_ADDR 2427 SCTP_PEER_ADDR_PARAMS 2428 SCTP_STATUS 2429 SCTP_CONTEXT 2430 SCTP_AUTH_ACTIVE_KEY 2431 SCTP_PEER_AUTH_CHUNKS 2432 SCTP_LOCAL_AUTH_CHUNKS 2434 The arg field is an option-specific structure buffer provided by the 2435 caller. See Section 8.5 subsections for more information on these 2436 options and option-specific structures. 2438 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2439 sets errno to the appropriate error code. 2441 All options that support specific settings on an association by 2442 filling in either an association id variable or a sockaddr_storage 2443 should also support the setting of the same value for the entire 2444 endpoint (i.e. future associations). To accomplish this the 2445 following logic is used when setting one of these options: 2446 o If an address is specified via a sockaddr_storage that is included 2447 in the structure, the address is used to lookup the association, 2448 and the settings are applied to the specific address (if 2449 appropriate) or to the entire association. 2450 o If an association identification is filled in but not a 2451 sockaddr_storage (if present), the association is found using the 2452 association identification and the settings should be applied to 2453 the specified association (since a specific address is not 2454 specified). Note this also applies to options that hold an 2455 association identification in their structure but do not have a 2456 sockaddr_storage field. 2457 o If neither the sockaddr_storage nor association identification is 2458 set, i.e. the sockaddr_storage is set to all 0 (INADDR_ANY) and 2459 the association identification is SCTP_FUTURE_ASSOC, the settings 2460 are a default and to be applied to the endpoint. 2462 7.1. Read / Write Options 2464 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2466 The protocol parameters used to initialize and limit the 2467 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2468 information on how these parameters are used in RTO calculation. 2470 The following structure is used to access and modify these 2471 parameters: 2473 struct sctp_rtoinfo { 2474 sctp_assoc_t srto_assoc_id; 2475 uint32_t srto_initial; 2476 uint32_t srto_max; 2477 uint32_t srto_min; 2478 }; 2480 srto_initial: This contains the initial RTO value. 2481 srto_max and srto_min: These contain the maximum and minimum bounds 2482 for all RTOs. 2483 srto_assoc_id: This parameter is ignored for one-to-one style 2484 sockets. For one-to-many style sockets the application may fill 2485 in an association identification or SCTP_FUTURE_ASSOC. It is an 2486 error to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2488 All times are given in milliseconds. A value of 0, when modifying 2489 the parameters, indicates that the current value should not be 2490 changed. 2492 To access or modify these parameters, the application should call 2493 getsockopt() or setsockopt() respectively with the option name 2494 SCTP_RTOINFO. 2496 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2498 This option is used to both examine and set various association and 2499 endpoint parameters. See [RFC4960] for more information on how this 2500 parameter is used. 2502 The following structure is used to access and modify these 2503 parameters: 2505 struct sctp_assocparams { 2506 sctp_assoc_t sasoc_assoc_id; 2507 uint16_t sasoc_asocmaxrxt; 2508 uint16_t sasoc_number_peer_destinations; 2509 uint32_t sasoc_peer_rwnd; 2510 uint32_t sasoc_local_rwnd; 2511 uint32_t sasoc_cookie_life; 2512 }; 2514 sasoc_assoc_id: This parameter is ignored for one-to-one style 2515 sockets. For one-to-many style sockets the application may fill 2516 in an association identification or SCTP_FUTURE_ASSOC. It is an 2517 error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2519 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2520 to make for the association. 2521 sasoc_number_peer_destinations: This is the number of destination 2522 addresses that the peer has. 2523 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2524 (reported in the last SACK) minus any outstanding data (i.e. data 2525 in flight). 2526 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2527 the peer. 2528 sasoc_cookie_life: This is the association's cookie life value used 2529 when issuing cookies. 2531 The values of the sasoc_peer_rwnd is meaningless when examining 2532 endpoint information. 2534 All time values are given in milliseconds. A value of 0, when 2535 modifying the parameters, indicates that the current value should not 2536 be changed. 2538 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2539 on either an endpoint or association basis. The rwnd and destination 2540 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2541 sasoc_local_rwnd) are not settable and any value placed in these is 2542 ignored. 2544 To access or modify these parameters, the application should call 2545 getsockopt() or setsockopt() respectively with the option name 2546 SCTP_ASSOCINFO. 2548 The maximum number of retransmissions before an address is considered 2549 unreachable is also tunable, but is address-specific, so it is 2550 covered in a separate option. If an application attempts to set the 2551 value of the association maximum retransmission parameter to more 2552 than the sum of all maximum retransmission parameters, setsockopt() 2553 may return an error. The reason for this, from [RFC4960] Section 2554 8.2: 2556 Note: When configuring the SCTP endpoint, the user should avoid 2557 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2558 option) larger than the summation of the 'Path.Max.Retrans' (see 2559 Section 7.1.2 on spp_pathmaxrxt) of all the destination addresses for 2560 the remote endpoint. Otherwise, all the destination addresses may 2561 become inactive while the endpoint still considers the peer endpoint 2562 reachable. 2564 7.1.3. Initialization Parameters (SCTP_INITMSG) 2566 Applications can specify protocol parameters for the default 2567 association initialization. The structure used to access and modify 2568 these parameters is defined in Section 5.2.1. The option name 2569 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2571 Setting initialization parameters is effective only on an unconnected 2572 socket (for one-to-many style sockets only future associations are 2573 affected by the change). With one-to-one style sockets, this option 2574 is inherited by sockets derived from a listening socket. 2576 7.1.4. SO_LINGER 2578 An application can use this option to perform the SCTP ABORT 2579 primitive. This option affects all associations related to the 2580 socket. 2582 The linger option structure is: 2584 struct linger { 2585 int l_onoff; /* option on/off */ 2586 int l_linger; /* linger time */ 2587 }; 2589 To enable the option, set l_onoff to 1. If the l_linger value is set 2590 to 0, calling close() is the same as the ABORT primitive. If the 2591 value is set to a negative value, the setsockopt() call will return 2592 an error. If the value is set to a positive value linger_time, the 2593 close() can be blocked for at most linger_time ms. If the graceful 2594 shutdown phase does not finish during this period, close() will 2595 return but the graceful shutdown phase will continue in the system. 2597 Note, this is a socket level option not an SCTP level option. So 2598 when setting SO_LINGER an application must specify a level of 2599 SOL_SOCKET in the setsockopt() call. 2601 7.1.5. SCTP_NODELAY 2603 Turn on/off any Nagle-like algorithm. This means that packets are 2604 generally sent as soon as possible and no unnecessary delays are 2605 introduced, at the cost of more packets in the network. Expects an 2606 integer boolean flag. Turning this option on disables any Nagle-like 2607 algorithm. 2609 7.1.6. SO_RCVBUF 2611 Sets the receive buffer size in octets. For SCTP one-to-one style 2612 sockets, this controls the receiver window size. For one-to-many 2613 style sockets the meaning is implementation dependent. It might 2614 control the receive buffer for each association bound to the socket 2615 descriptor or it might control the receive buffer for the whole 2616 socket. The call expects an integer. 2618 7.1.7. SO_SNDBUF 2620 Sets the send buffer size. For SCTP one-to-one style sockets, this 2621 controls the amount of data SCTP may have waiting in internal buffers 2622 to be sent. This option therefore bounds the maximum size of data 2623 that can be sent in a single send call. For one-to-many style 2624 sockets, the effect is the same, except that it applies to one or all 2625 associations (see Section 3.3) bound to the socket descriptor used in 2626 the setsockopt() or getsockopt() call. The option applies to each 2627 association's window size separately. The call expects an integer. 2629 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 2631 This socket option is applicable to the one-to-many style socket 2632 only. When set it will cause associations that are idle for more 2633 than the specified number of seconds to automatically close using the 2634 graceful shutdown procedure. An association being idle is defined as 2635 an association that has not sent or received user data. The special 2636 value of '0' indicates that no automatic close of any association 2637 should be performed, this is the default value. The option expects 2638 an integer defining the number of seconds of idle time before an 2639 association is closed. 2641 An application using this option should enable receiving the 2642 association change notification. This is the only mechanism an 2643 application is informed about the closing of an association. After 2644 an association is closed, the association ID assigned to it can be 2645 reused. An application should be aware of this to avoid the possible 2646 problem of sending data to an incorrect peer endpoint. 2648 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 2650 Requests that the local SCTP stack uses the enclosed peer address as 2651 the association's primary. The enclosed address must be one of the 2652 association peer's addresses. 2654 The following structure is used to make a set peer primary request: 2656 struct sctp_setprim { 2657 sctp_assoc_t ssp_assoc_id; 2658 struct sockaddr_storage ssp_addr; 2659 }; 2661 ssp_addr: The address to set as primary. No wildcard address is 2662 allowed. 2663 ssp_assoc_id: This parameter is ignored for one-to-one style 2664 sockets. For one-to-many style sockets it identifies the 2665 association for this request. Note that the special sctp_assoc_t 2666 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 2668 7.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2670 Requests that the local endpoint set the specified Adaptation Layer 2671 Indication parameter for all future INIT and INIT-ACK exchanges. 2673 The following structure is used to access and modify this parameter: 2675 struct sctp_setadaptation { 2676 uint32_t ssb_adaptation_ind; 2677 }; 2679 ssb_adaptation_ind: The adaptation layer indicator that will be 2680 included in any outgoing Adaptation Layer Indication parameter. 2682 7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 2684 This option is a on/off flag and is passed as an integer where a non- 2685 zero is on and a zero is off. If enabled no SCTP message 2686 fragmentation will be performed. If disabled, if a message being 2687 sent exceeds the current PMTU size, the message will not be sent and 2688 instead an error will be indicated to the user. 2690 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2692 Applications can enable or disable heartbeats for any peer address of 2693 an association, modify an address's heartbeat interval, force a 2694 heartbeat to be sent immediately, and adjust the address's maximum 2695 number of retransmissions sent before an address is considered 2696 unreachable. 2698 The following structure is used to access and modify an address's 2699 parameters: 2701 struct sctp_paddrparams { 2702 sctp_assoc_t spp_assoc_id; 2703 struct sockaddr_storage spp_address; 2704 uint32_t spp_hbinterval; 2705 uint16_t spp_pathmaxrxt; 2706 uint32_t spp_pathmtu; 2707 uint32_t spp_flags; 2708 uint32_t spp_ipv6_flowlabel; 2709 uint8_t spp_ipv4_tos; 2710 }; 2712 spp_assoc_id: This parameter is ignored for one-to-one style 2713 sockets. For one-to-many style sockets it identifies the 2714 association for this query. Note that the predefined constants 2715 are not allowed. 2716 spp_address: This specifies which address is of interest. If a 2717 wildcard address is provided it applies to all current and future 2718 paths. 2719 spp_hbinterval: This contains the value of the heartbeat interval, 2720 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 2721 spp_flag is set to SPP_HB_ENABLE the value of this field is 2722 ignored. Note also that a value of zero indicates the current 2723 setting should be left unchanged. To set an actual value of zero 2724 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 2725 it is set to 0, it does not mean that SCTP will continuously send 2726 out heartbeat since the actual interval also includes the current 2727 RTO and jitter (see Section 8.3 in [RFC4960]). 2728 spp_pathmaxrxt: This contains the maximum number of retransmissions 2729 before this address shall be considered unreachable. Note that a 2730 value of zero indicates the current setting should be left 2731 unchanged. 2732 spp_ipv6_flowlabel: This field is used in conjunction with the 2733 SPP_IPV6_FLOWLABEL flag. This setting has precedence over any 2734 IPv6 layer setting. 2735 spp_ipv4_tos: This field is used in conjunction with the 2736 SPP_IPV4_TOS flag. This setting has precedence over any IPv4 2737 layer setting. 2738 spp_flags: These flags are used to control various features on an 2739 association. The flag field is a bit mask which may contain zero 2740 or more of the following options: 2741 SPP_HB_ENABLE: Enable heartbeats on the specified address. 2742 SPP_HB_DISABLE: Disable heartbeats on the specified address. 2743 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 2744 exclusive, only one of these two should be specified. Enabling 2745 both fields will have undetermined results. 2747 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 2748 immediately. This must not be used in conjunction with a 2749 wildcard address. 2750 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 2751 is to be set to the value of 0 milliseconds. 2752 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 2753 specified address. 2754 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 2755 the specified address. Note that if the address field is empty 2756 then all addresses on the association are affected. Note also 2757 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2758 exclusive. Enabling both will have undetermined results. 2759 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 2760 IPV6 flowlabel value. The value is obtained in the 2761 spp_ipv6_flowlabel field. 2763 Upon retrieval, this flag will be set to indicate that the 2764 spp_ipv6_flowlabel field has a valid value returned. If a 2765 specific destination address is set (in the spp_address field), 2766 then the value returned is that of the address. If just an 2767 association is specified (and no address), then the 2768 association's default flowlabel is returned. If neither an 2769 association nor a destination is specified, then the socket's 2770 default flowlabel is returned. For non IPv6 sockets, this flag 2771 will be left cleared. 2772 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 2773 TOS value associated with either the association or a specific 2774 address. The value is obtained in the spp_ipv4_tos field. 2776 Upon retrieval, this flag will be set to indicate that the 2777 spp_ipv4_tos field has a valid value returned. If a specific 2778 destination address is set when called (in the spp_address 2779 field) then that specific destination address' TOS value is 2780 returned. If just an association is specified then the 2781 association default TOS is returned. If neither an association 2782 nor a destination is specified, then the sockets default TOS is 2783 returned. 2785 To read or modify these parameters, the application should call 2786 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2788 7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 2790 Please note that this options is deprecated. Section 7.1.31 should 2791 be used instead. 2793 Applications that wish to use the sendto() system call may wish to 2794 specify a default set of parameters that would normally be supplied 2795 through the inclusion of ancillary data. This socket option allows 2796 such an application to set the default sctp_sndrcvinfo structure. 2797 The application that wishes to use this socket option simply passes 2798 the sctp_sndrcvinfo structure defined in Section 5.2.2 to this call. 2799 The input parameters accepted by this call include sinfo_stream, 2800 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy and 2801 sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2802 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2803 specifies the association to apply the parameters to. For a one-to- 2804 many style socket any of the predefined constants are also allowed in 2805 this field. The field is ignored on the one-to-one style. 2807 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) 2809 This socket option is used to specify various notifications and 2810 ancillary data the user wishes to receive. Please see Section 7.4 2811 for a full description of this option and its usage. Note that this 2812 option is considered deprecated and present for backward 2813 compatibility. New applications should use the SCTP_SET_EVENT 2814 option. See Section 7.4 for a full description of that option as 2815 well. 2817 7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2819 This socket option is a boolean flag which turns on or off the 2820 mapping of IPv4 addresses. If this option is turned on, then IPv4 2821 addresses will be mapped to V6 representation. If this option is 2822 turned off, then no mapping will be done of V4 addresses and a user 2823 will receive both PF_INET6 and PF_INET type addresses on the socket. 2824 See [RFC3542] for more details on mapped V6 addresses. 2826 If this socket option is used on a socket of type PF_INET an error is 2827 returned. 2829 By default this option is turned off and expects an integer to be 2830 passed where non-zero turns on the option and zero turns off the 2831 option. 2833 7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 2835 This option will get or set the maximum size to put in any outgoing 2836 SCTP DATA chunk. If a message is larger than this size it will be 2837 fragmented by SCTP into the specified size. Note that the underlying 2838 SCTP implementation may fragment into smaller sized chunks when the 2839 PMTU of the underlying association is smaller than the value set by 2840 the user. The default value for this option is '0' which indicates 2841 the user is not limiting fragmentation and only the PMTU will affect 2842 SCTP's choice of DATA chunk size. Note also that values set larger 2843 than the maximum size of an IP datagram will effectively let SCTP 2844 control fragmentation (i.e. the same as setting this option to 0). 2846 The following structure is used to access and modify this parameter: 2848 struct sctp_assoc_value { 2849 sctp_assoc_t assoc_id; 2850 uint32_t assoc_value; 2851 }; 2853 assoc_id: This parameter is ignored for one-to-one style sockets. 2854 For one-to-many style sockets this parameter indicates which 2855 association the user is performing an action upon. It is an error 2856 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 2857 assoc_value: This parameter specifies the maximum size in bytes. 2859 7.1.17. Get or Set the List of Supported HMAC Identifiers 2860 (SCTP_HMAC_IDENT) 2862 This option gets or sets the list of HMAC algorithms that the local 2863 endpoint requires the peer to use. 2865 The following structure is used to get or set these identifiers: 2867 struct sctp_hmacalgo { 2868 uint32_t shmac_number_of_idents; 2869 uint16_t shmac_idents[]; 2870 }; 2872 shmac_number_of_idents: This field gives the number of elements 2873 present in the array shmac_idents. 2874 shmac_idents: This parameter contains an array of HMAC identifiers 2875 that the local endpoint is requesting the peer to use, in priority 2876 order. The following identifiers are valid: 2877 * SCTP_AUTH_HMAC_ID_SHA1 2878 * SCTP_AUTH_HMAC_ID_SHA256 2880 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 2881 may include any of the other values in its preferred order (lowest 2882 list position has the highest preference in algorithm selection). 2883 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 2884 of an unknown HMAC identifier (including optional identifiers unknown 2885 to the implementation) will cause the set option to fail and return 2886 an error. 2888 7.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 2890 This option will get or set the active shared key to be used to build 2891 the association shared key. 2893 The following structure is used to access and modify these 2894 parameters: 2896 struct sctp_authkeyid { 2897 sctp_assoc_t scact_assoc_id; 2898 uint16_t scact_keynumber; 2899 }; 2901 scact_assoc_id: This parameter sets the active key of the specified 2902 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 2903 used. For one-to-one sockets, this parameter is ignored. Note, 2904 however, that this option will set the active key on the 2905 association if the socket is connected, otherwise this will set 2906 the default active key for the endpoint. 2907 scact_keynumber: This parameter is the shared key identifier which 2908 the application is requesting to become the active shared key to 2909 be used for sending authenticated chunks. The key identifier must 2910 correspond to an existing shared key. Note that shared key 2911 identifier '0' defaults to a null key. 2913 When used with setsockopt() the SCTP implementation must use the 2914 indicated shared key identifier for all messages being given to an 2915 SCTP implementation via a send call after the setsockopt() call until 2916 changed again. Therefore, the SCTP implementation must not bundle 2917 user messages which should be authenticated using different shared 2918 key identifiers. 2920 Initially the key with key identifier 0 is the active key. 2922 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 2924 This option will affect the way delayed sacks are performed. This 2925 option allows the application to get or set the delayed sack time, in 2926 milliseconds. It also allows changing the delayed sack frequency. 2927 Changing the frequency to 1 disables the delayed sack algorithm. 2928 Note that if sack_delay or sack_freq are 0 when setting this option, 2929 the current values will remain unchanged. 2931 The following structure is used to access and modify these 2932 parameters: 2934 struct sctp_sack_info { 2935 sctp_assoc_t sack_assoc_id; 2936 uint32_t sack_delay; 2937 uint32_t sack_freq; 2938 }; 2940 sack_assoc_id: This parameter is ignored for one-to-one style 2941 sockets. For one-to-many style sockets this parameter indicates 2942 which association the user is performing an action upon. The 2943 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 2944 sack_delay: This parameter contains the number of milliseconds that 2945 the user is requesting the delayed SACK timer to be set to. Note 2946 that this value is defined in the standard to be between 200 and 2947 500 milliseconds. 2948 sack_freq: This parameter contains the number of packets that must 2949 be received before a sack is sent without waiting for the delay 2950 timer to expire. The default value is 2, setting this value to 1 2951 will disable the delayed sack algorithm. 2953 7.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 2955 Fragmented interleave controls how the presentation of messages 2956 occurs for the message receiver. There are three levels of fragment 2957 interleave defined. Two of the levels affect the one-to-one model, 2958 while the one-to-many model is affected by all three levels. 2960 This option takes an integer value. It can be set to a value of 0, 1 2961 or 2. Attempting to set this level to other values will return an 2962 error. 2964 Setting the three levels provides the following receiver 2965 interactions: 2967 level 0: Prevents the interleaving of any messages. This means that 2968 when a partial delivery begins, no other messages will be received 2969 except the message being partially delivered. If another message 2970 arrives on a different stream (or association) that could be 2971 delivered, it will be blocked waiting for the user to read all of 2972 the partially delivered message. 2973 level 1: Allows interleaving of messages that are from different 2974 associations. For the one-to-one model, level 0 and level 1 thus 2975 have the same meaning since a one-to-one socket always receives 2976 messages from the same association. Note that setting the one-to- 2977 many model to this level may cause multiple partial deliveries 2978 from different associations but for any given association, only 2979 one message will be delivered until all parts of a message have 2980 been delivered. This means that one large message, being read 2981 with an association identification of "X", will block other 2982 messages from association "X" from being delivered. 2983 level 2: Allows complete interleaving of messages. This level 2984 requires that the sender carefully observes not only the peer 2985 association identification (or address) but must also pay careful 2986 attention to the stream number. With this option enabled a 2987 partially delivered message may begin being delivered for 2988 association "X" stream "Y" and the next subsequent receive may 2989 return a message from association "X" stream "Z". Note that no 2990 other messages would be delivered for association "X" stream "Y" 2991 until all of stream "Y"'s partially delivered message was read. 2992 Note that this option also affects the one-to-one model. Also 2993 note that for the one-to-many model not only another stream's 2994 message from the same association may be delivered upon the next 2995 receive, some other association's message may be delivered upon 2996 the next receive. 2998 An implementation should default the one-to-many model to level 1. 2999 The reason for this is that otherwise it is possible that a peer 3000 could begin sending a partial message and thus block all other peers 3001 from sending data. However a setting of level 2 requires the 3002 application to not only be aware of the association (via the 3003 association id or peer's address) but also the stream number. The 3004 stream number is not present unless the user has subscribed to the 3005 sctp_data_io_events (see Section 7.4). This is also why we recommend 3006 that the one-to-one model be defaulted to level 0 (level 1 for the 3007 one-to-one model has no effect). Note that an implementation should 3008 return an error if an application attempts to set the level to 2 and 3009 has not subscribed to the sctp_data_io_events. 3011 For applications that have subscribed to events those events appear 3012 in the normal socket buffer data stream. This means that unless the 3013 user has set the fragmentation interleave level to 0, notifications 3014 may also be interleaved with partially delivered messages. 3016 7.1.21. Set or Get the SCTP Partial Delivery Point 3017 (SCTP_PARTIAL_DELIVERY_POINT) 3019 This option will set or get the SCTP partial delivery point. This 3020 point is the size of a message where the partial delivery API will be 3021 invoked to help free up rwnd space for the peer. Setting this to a 3022 lower value will cause partial deliveries to happen more often. The 3023 call's argument is an integer that sets or gets the partial delivery 3024 point in bytes. Note also that the call will fail if the user 3025 attempts to set this value larger than the socket receive buffer 3026 size. 3028 Note that any single message having a length smaller than or equal to 3029 the SCTP partial delivery point will be delivered in one single read 3030 call as long as the user provided buffer is large enough to hold the 3031 message. 3033 7.1.22. Set or Get the Use of Extended Receive Info 3034 (SCTP_USE_EXT_RCVINFO) 3036 This option will enable or disable the use of the extended version of 3037 the sctp_sndrcvinfo structure. If this option is disabled, then the 3038 normal sctp_sndrcvinfo structure is returned in all receive message 3039 calls. If this option is enabled then the sctp_extrcvinfo structure 3040 is returned in all receive message calls. The default is off. 3042 Note that the sctp_extrcvinfo structure is never used in any send 3043 call. 3045 This option is present for compatibility with older applications and 3046 is deprecated. Future applications should use SCTP_NXTINFO to 3047 retrieve this same information via ancillary data. 3049 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3051 This option will enable or disable the use of the automatic 3052 generation of ASCONF chunks to add and delete addresses to an 3053 existing association. Note that this option has two caveats namely: 3054 a) it only affects sockets that are bound to all addresses on the 3055 machine, and b) the system administrator may have an overriding 3056 control that turns the ASCONF feature off no matter what setting the 3057 socket option may have. 3059 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3061 This option will allow a user to change the maximum burst of packets 3062 that can be emitted by this association. Note that the default value 3063 is 4, and some implementations may restrict this setting so that it 3064 can only be lowered to positive values. 3066 To set or get this option the user fills in the following structure: 3068 struct sctp_assoc_value { 3069 sctp_assoc_t assoc_id; 3070 uint32_t assoc_value; 3071 }; 3073 assoc_id: This parameter is ignored for one-to-one style sockets. 3074 For one-to-many style sockets this parameter indicates which 3075 association the user is performing an action upon. The special 3076 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3078 assoc_value: This parameter contains the maximum burst. Setting the 3079 value to 0 disables burst mitigation. 3081 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3083 The context field in the sctp_sndrcvinfo structure is normally only 3084 used when a failed message is retrieved holding the value that was 3085 sent down on the actual send call. This option allows the setting of 3086 a default context on an association basis that will be received on 3087 reading messages from the peer. This is especially helpful in the 3088 one-to-many model for an application to keep some reference to an 3089 internal state machine that is processing messages on the 3090 association. Note that the setting of this value only affects 3091 received messages from the peer and does not affect the value that is 3092 saved with outbound messages. 3094 To set or get this option the user fills in the following structure: 3096 struct sctp_assoc_value { 3097 sctp_assoc_t assoc_id; 3098 uint32_t assoc_value; 3099 }; 3101 assoc_id: This parameter is ignored for one-to-one style sockets. 3102 For one-to-many style sockets this parameter indicates which 3103 association the user is performing an action upon. The special 3104 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3105 assoc_value: This parameter contains the context. 3107 7.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3109 This boolean flag is used to enable or disable explicit end of record 3110 (EOR) marking. When this option is enabled, a user may make multiple 3111 send system calls to send a record and must indicate that they are 3112 finished sending a particular record by including the SCTP_EOR flag. 3113 If this boolean flag is disabled then each individual send system 3114 call is considered to have an SCTP_EOR indicator set on it implicitly 3115 without the user having to explicitly add this flag. The default is 3116 off. 3118 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3120 This option only supports one-to-one style SCTP sockets. If used on 3121 a one-to-many style SCTP socket an error is indicated. 3123 This setsockopt() call must not be used after calling bind() or 3124 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3125 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3126 SCTP sockets bound to the same port must have set the 3127 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3128 having set the SCTP_REUSE_PORT option will fail if there are other 3129 sockets bound to the same port. At most one socket being bound to 3130 the same port may be listening. 3132 It should be noted that the behavior of the socket level socket 3133 option to reuse ports and/or addresses for SCTP sockets is 3134 unspecified. 3136 7.1.28. Set Notification Event (SCTP_EVENT) 3138 This socket option is used to set a specific notification option. 3139 Please see Section 7.4 for a full description of this option and its 3140 usage. 3142 7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3143 Data (SCTP_RECVRCVINFO) 3145 Setting this option specifies that SCTP_RCVINFO defined in 3146 Section 5.2.5 is returned as ancillary data by recvmsg(). The call 3147 expects an integer. 3149 7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3150 Data (SCTP_RECVNXTINFO) 3152 Setting this option specifies that SCTP_NXTINFO defined in 3153 Section 5.2.6 is returned as ancillary data by recvmsg(). The call 3154 expects an integer. 3156 7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3158 Applications that wish to use the sendto() system call may wish to 3159 specify a default set of parameters that would normally be supplied 3160 through the inclusion of ancillary data. This socket option allows 3161 such an application to set the default sctp_sndrcvinfo structure. 3162 The application that wishes to use this socket option simply passes 3163 the sctp_sndinfo structure defined in Section 5.2.4 to this call. 3164 The input parameters accepted by this call include snd_sid, 3165 snd_flags, snd_ppid, snd_context. The snd_flags is composed of a 3166 bitwise OR of SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The 3167 snd_assoc_id field specifies the association to apply the parameters 3168 to. For a one-to-many style socket any of the predefined constants 3169 are also allowed in this field. The field is ignored on the one-to- 3170 one style. 3172 7.2. Read-Only Options 3174 The options defined in this subsection are read-only. Using this 3175 option in a setsockopt() call will result in an error indicating 3176 EOPNOTSUPP. 3178 7.2.1. Association Status (SCTP_STATUS) 3180 Applications can retrieve current status information about an 3181 association, including association state, peer receiver window size, 3182 number of unacked data chunks, and number of data chunks pending 3183 receipt. This information is read-only. 3185 The following structure is used to access this information: 3187 struct sctp_status { 3188 sctp_assoc_t sstat_assoc_id; 3189 int32_t sstat_state; 3190 uint32_t sstat_rwnd; 3191 uint16_t sstat_unackdata; 3192 uint16_t sstat_penddata; 3193 uint16_t sstat_instrms; 3194 uint16_t sstat_outstrms; 3195 uint32_t sstat_fragmentation_point; 3196 struct sctp_paddrinfo sstat_primary; 3197 }; 3199 sstat_assoc_id: This parameter is ignored for one-to-one style 3200 sockets. For one-to-many style sockets it holds the identifier 3201 for the association. All notifications for a given association 3202 have the same association identifier. The special SCTP_{FUTURE| 3203 CURRENT|ALL}_ASSOC cannot be used. 3204 sstat_state: This contains the association's current state, i.e. one 3205 of the following values: 3206 * SCTP_CLOSED 3207 * SCTP_BOUND 3208 * SCTP_LISTEN 3209 * SCTP_COOKIE_WAIT 3210 * SCTP_COOKIE_ECHOED 3211 * SCTP_ESTABLISHED 3212 * SCTP_SHUTDOWN_PENDING 3213 * SCTP_SHUTDOWN_SENT 3214 * SCTP_SHUTDOWN_RECEIVED 3215 * SCTP_SHUTDOWN_ACK_SENT 3217 sstat_rwnd: This contains the association peer's current receiver 3218 window size. 3219 sstat_unackdata: This is the number of unacked data chunks. 3220 sstat_penddata: This is the number of data chunks pending receipt. 3221 sstat_instrms: The number of streams that the peer will be using 3222 outbound. 3223 sstat_outstrms: The number of streams that the endpoint is allowed 3224 to use outbound. 3225 sstat_fragmentation_point: The size at which SCTP fragmentation will 3226 occur. 3227 sstat_primary: This is information on the current primary peer 3228 address. 3230 To access these status values, the application calls getsockopt() 3231 with the option name SCTP_STATUS. 3233 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3235 Applications can retrieve information about a specific peer address 3236 of an association, including its reachability state, congestion 3237 window, and retransmission timer values. This information is read- 3238 only. 3240 The following structure is used to access this information: 3242 struct sctp_paddrinfo { 3243 sctp_assoc_t spinfo_assoc_id; 3244 struct sockaddr_storage spinfo_address; 3245 int32_t spinfo_state; 3246 uint32_t spinfo_cwnd; 3247 uint32_t spinfo_srtt; 3248 uint32_t spinfo_rto; 3249 uint32_t spinfo_mtu; 3250 }; 3252 spinfo_assoc_id: This parameter is ignored for one-to-one style 3253 sockets. For one-to-many style sockets the following applies: 3254 This field may be filled by the application, if so, this field 3255 will have priority in looking up the association using the address 3256 specified in spinfo_address. Note that if the address does not 3257 belong to the association specified then this call will fail. If 3258 the application does not fill in the spinfo_assoc_id, then the 3259 address will be used to lookup the association and on return this 3260 field will have the valid association id. In other words, this 3261 call can be used to translate an address into an association id. 3262 Note that the predefined constants are not allowed on this option. 3264 spinfo_address: This is filled by the application, and contains the 3265 peer address of interest. 3266 spinfo_state: This contains the peer address' state (either 3267 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 3268 SCTP_UNCONFIRMED). 3269 spinfo_cwnd: This contains the peer address' current congestion 3270 window. 3271 spinfo_srtt: This contains the peer address' current smoothed round- 3272 trip time calculation in milliseconds. 3273 spinfo_rto: This contains the peer address' current retransmission 3274 timeout value in milliseconds. 3275 spinfo_mtu: The current P-MTU of this address. 3277 7.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3278 (SCTP_PEER_AUTH_CHUNKS) 3280 This option gets a list of chunk types (see [RFC4960]) for a 3281 specified association that the peer requires to be received 3282 authenticated only. 3284 The following structure is used to access these parameters: 3286 struct sctp_authchunks { 3287 sctp_assoc_t gauth_assoc_id; 3288 uint32_t gauth_number_of_chunks 3289 uint8_t gauth_chunks[]; 3290 }; 3292 gauth_assoc_id: This parameter indicates for which association the 3293 user is requesting the list of peer authenticated chunks. For 3294 one-to-one sockets, this parameter is ignored. Note that the 3295 predefined constants are not allowed with this option. 3296 gauth_number_of_chunks: This parameter gives the number of elements 3297 in the array gauth_chunks. 3298 gauth_chunks: This parameter contains an array of chunk types that 3299 the peer is requesting to be authenticated. 3301 7.2.4. Get the List of Chunks the Local Endpoint Requires to be 3302 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3304 This option gets a list of chunk types (see [RFC4960]) for a 3305 specified association that the local endpoint requires to be received 3306 authenticated only. 3308 The following structure is used to access these parameters: 3310 struct sctp_authchunks { 3311 sctp_assoc_t gauth_assoc_id; 3312 uint32_t gauth_number_of_chunks; 3313 uint8_t gauth_chunks[]; 3314 }; 3316 gauth_assoc_id: This parameter indicates for which association the 3317 user is requesting the list of local authenticated chunks. For 3318 one-to-one sockets, this parameter is ignored. 3319 gauth_number_of_chunks: This parameter gives the number of elements 3320 in the array gauth_chunks. 3321 gauth_chunks: This parameter contains an array of chunk types that 3322 the local endpoint is requesting to be authenticated. 3324 7.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3326 This option gets the current number of associations that are attached 3327 to a one-to-many style socket. The option value is an uint32_t. 3328 Note that this number is only a snap shot. This means that the 3329 number of associations may have changed when the caller gets back the 3330 option result. 3332 For a one-to-one style socket, this socket option results in an 3333 error. 3335 7.2.6. Get the Current Identifiers of Associations 3336 (SCTP_GET_ASSOC_ID_LIST) 3338 This option gets the current list of SCTP association identifiers of 3339 the SCTP associations handled by a one-to-many style socket. 3341 The option value has the structure 3343 struct sctp_assoc_ids { 3344 uint32_t gaids_number_of_ids; 3345 sctp_assoc_t gaids_assoc_id[]; 3346 }; 3348 The caller must provide a large enough buffer to hold all association 3349 identifiers. If the buffer is too small, an error must be returned. 3350 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3351 idea how large the buffer has to be. gaids_number_of_ids gives the 3352 number of elements in the array gaids_assoc_id. Note also that the 3353 some or all of sctp_assoc_t returned in the array may become invalid 3354 by the time the caller gets back the result. 3356 For a one-to-one style socket, this socket option results in an 3357 error. 3359 7.3. Write-Only Options 3361 The options defined in this subsection are write-only. Using this 3362 option in a getsockopt() or sctp_opt_info() call will result in an 3363 error indicating EOPNOTSUPP. 3365 7.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3367 Requests that the peer marks the enclosed address as the association 3368 primary (see [RFC5061]). The enclosed address must be one of the 3369 association's locally bound addresses. 3371 The following structure is used to make a set peer primary request: 3373 struct sctp_setpeerprim { 3374 sctp_assoc_t sspp_assoc_id; 3375 struct sockaddr_storage sspp_addr; 3376 }; 3378 sspp_addr: The address to set as primary. 3379 sspp_assoc_id: This parameter is ignored for one-to-one style 3380 sockets. For one-to-many style sockets it identifies the 3381 association for this request. Note that the predefined constants 3382 are not allowed on this option. 3384 7.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3386 This set option adds a chunk type that the user is requesting to be 3387 received only in an authenticated way. Changes to the list of chunks 3388 will only affect future associations on the socket. 3390 The following structure is used to add a chunk: 3392 struct sctp_authchunk { 3393 uint8_t sauth_chunk; 3394 }; 3396 sauth_chunk: This parameter contains a chunk type that the user is 3397 requesting to be authenticated. 3399 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3400 chunks must not be used. If they are used, an error must be 3401 returned. The usage of this option enables SCTP AUTH in cases where 3402 it is not required by other means (for example the use of dynamic 3403 address reconfiguration). 3405 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3407 This option will set a shared secret key that is used to build an 3408 association shared key. 3410 The following structure is used to access and modify these 3411 parameters: 3413 struct sctp_authkey { 3414 sctp_assoc_t sca_assoc_id; 3415 uint16_t sca_keynumber; 3416 uint16_t sca_keylength; 3417 uint8_t sca_key[]; 3418 }; 3420 sca_assoc_id: This parameter indicates what association the shared 3421 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3422 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3423 ignored. Note, however, that this option will set a key on the 3424 association if the socket is connected, otherwise this will set a 3425 key on the endpoint. 3426 sca_keynumber: This parameter is the shared key identifier by which 3427 the application will refer to this shared key. If a key of the 3428 specified index already exists, then this new key will replace the 3429 old existing key. Note that shared key identifier '0' defaults to 3430 a null key. 3431 sca_keylength: This parameter is the length of the array sca_key. 3432 sca_key: This parameter contains an array of bytes that is to be 3433 used by the endpoint (or association) as the shared secret key. 3434 Note, if the length of this field is zero, a null key is set. 3436 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3438 This set option indicates that the application will not send user 3439 messages anymore using the indicated key identifier. 3441 struct sctp_authkeyid { 3442 sctp_assoc_t scact_assoc_id; 3443 uint16_t scact_keynumber; 3444 }; 3446 scact_assoc_id: This parameter indicates which association the 3447 shared key identifier is being deleted from. The special 3448 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3449 sockets, this parameter is ignored. Note, however, that this 3450 option will deactivate the key from the association if the socket 3451 is connected, otherwise this will deactivate the key from the 3452 endpoint. 3454 scact_keynumber: This parameter is the shared key identifier which 3455 the application is requesting to be deactivated. The key 3456 identifier must correspond to an existing shared key. Note if 3457 this parameter is zero, use of the null key identifier '0' is 3458 deactivated on the endpoint and/or association. 3460 The currently active key cannot be deactivated. 3462 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3464 This set option will delete a shared secret key which has been 3465 deactivated of an SCTP association. 3467 struct sctp_authkeyid { 3468 sctp_assoc_t scact_assoc_id; 3469 uint16_t scact_keynumber; 3470 }; 3472 scact_assoc_id: This parameter indicates which association the 3473 shared key identifier is being deleted from. The special 3474 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3475 sockets, this parameter is ignored. Note, however, that this 3476 option will delete the key from the association if the socket is 3477 connected, otherwise this will delete the key from the endpoint. 3478 scact_keynumber: This parameter is the shared key identifier which 3479 the application is requesting to be deleted. The key identifier 3480 must correspond to an existing shared key and must not be in use 3481 for any packet being sent by the SCTP implementation. This means 3482 in particular, that it must be deactivated first. Note if this 3483 parameter is zero, use of the null key identifier '0' is deleted 3484 from the endpoint and/or association. 3486 Only deactivated keys that are no longer used by the association can 3487 be deleted. 3489 7.4. Ancillary Data and Notification Interest Options 3491 Applications can receive per-message ancillary information and 3492 notifications of certain SCTP events with recvmsg(). 3494 The following optional information is available to the application: 3495 SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3496 stream number, TSN, SSN, etc. described in Section 5.2.2) 3497 SCTP_ASSOC_CHANGE (sctp_association_event): described in 3498 Section 5.3.2 3500 SCTP_PEER_ADDR_CHANGE (sctp_address_event): described in 3501 Section 5.3.3 3502 SCTP_SEND_FAILED (sctp_send_failure_event): described in 3503 Section 5.3.5 3504 SCTP_REMOTE_ERROR (sctp_peer_error_event): described in 3505 Section 5.3.4 3506 SCTP_SHUTDOWN_EVENT (sctp_shutdown_event): described in 3507 Section 5.3.6 3508 SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): described 3509 in Section 5.3.8 3510 SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): described 3511 in Section 5.3.7 3512 SCTP_AUTHENTICATION_EVENT (sctp_authentication_event): described in 3513 Section 5.3.9) 3514 SCTP_SENDER_DRY_EVENT (sctp_sender_dry_event): described in 3515 Section 5.3.10 3516 SCTP_NOTIFICATIONS_STOPPED_EVENT (): described in Section 5.3.11 3518 To receive any ancillary data or notifications, first the application 3519 registers its interest by calling the SCTP_EVENTS (deprecated, see 3520 below) setsockopt() with the following structure: 3522 struct sctp_event_subscribe{ 3523 uint8_t sctp_data_io_event; 3524 uint8_t sctp_association_event; 3525 uint8_t sctp_address_event; 3526 uint8_t sctp_send_failure_event; 3527 uint8_t sctp_peer_error_event; 3528 uint8_t sctp_shutdown_event; 3529 uint8_t sctp_partial_delivery_event; 3530 uint8_t sctp_adaptation_layer_event; 3531 uint8_t sctp_authentication_event; 3532 uint8_t sctp_sender_dry_event; 3533 }; 3535 sctp_data_io_event: Setting this flag to 1 will cause the reception 3536 of SCTP_SNDRCV information on a per message basis. The 3537 application will need to use the recvmsg() interface so that it 3538 can receive the event information contained in the msg_control 3539 field. Setting the flag to 0 will disable the reception of the 3540 message control information. 3541 sctp_association_event: Setting this flag to 1 will enable the 3542 reception of association event notifications. Setting the flag to 3543 0 will disable association event notifications. 3545 sctp_address_event: Setting this flag to 1 will enable the reception 3546 of address event notifications. Setting the flag to 0 will 3547 disable address event notifications. 3548 sctp_send_failure_event: Setting this flag to 1 will enable the 3549 reception of send failure event notifications. Setting the flag 3550 to 0 will disable send failure event notifications. 3551 sctp_peer_error_event: Setting this flag to 1 will enable the 3552 reception of peer error event notifications. Setting the flag to 3553 0 will disable peer error event notifications. 3554 sctp_shutdown_event: Setting this flag to 1 will enable the 3555 reception of shutdown event notifications. Setting the flag to 0 3556 will disable shutdown event notifications. 3557 sctp_partial_delivery_event: Setting this flag to 1 will enable the 3558 reception of partial delivery notifications. Setting the flag to 3559 0 will disable partial delivery event notifications. 3560 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 3561 reception of adaptation layer notifications. Setting the flag to 3562 0 will disable adaptation layer event notifications. 3563 sctp_authentication_event: Setting this flag to 1 will enable the 3564 reception of authentication layer notifications. Setting the flag 3565 to 0 will disable authentication layer event notifications. 3566 sctp_sender_dry_event: Setting this flag to 1 will enable the 3567 reception of sender dry notifications. Setting the flag to 0 will 3568 disable sender dry event notifications. 3570 An example where an application would like to receive data io events 3571 and association events but no others would be as follows: 3573 { 3574 struct sctp_event_subscribe events; 3576 memset(&events,0,sizeof(events)); 3578 events.sctp_data_io_event = 1; 3579 events.sctp_association_event = 1; 3581 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 3582 } 3584 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3585 receives ancillary data and notifications for all associations bound 3586 to the file descriptor. For one-to-one style SCTP sockets, the 3587 caller receives ancillary data and notifications only for the single 3588 association bound to the file descriptor. 3590 The SCTP_EVENTS socket option has one issue for future compatibility. 3591 As new features are added the structure (sctp_event_subscribe) must 3592 be expanded. This can cause an application binary interface (ABI) 3593 issue unless an implementation has added padding at the end of the 3594 structure. To avoid this problem, SCTP_EVENTS has been deprecated 3595 and a new option SCTP_EVENT socket option has taken its place. The 3596 option is used with the following structure: 3598 struct sctp_event { 3599 sctp_assoc_t se_assoc_id; 3600 uint16_t se_type; 3601 uint8_t se_on; 3602 }; 3604 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 3605 sockets. For one-to-many style sockets any this field can be a 3606 particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 3607 se_type: The se_type field can be filled with any value that would 3608 show up in the respective sn_type field (in the sctp_tlv structure 3609 of the notification). 3610 se_on: The se_on field is set to 1 to turn on an event and set to 0 3611 to turn off an event. 3613 To use this option the user fills in this structure and then calls 3614 the setsockopt to turn on or off an individual event. The following 3615 is an example use of this option: 3617 { 3618 struct sctp_event event; 3620 memset(&event, 0, sizeof(event)); 3622 event.se_assoc_id = SCTP_FUTURE_ASSOC; 3623 event.se_type = SCTP_SENDER_DRY_EVENT; 3624 event.se_on = 1; 3625 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 3626 } 3628 By default both the one-to-one style and the one-to-many style socket 3629 has all options off. 3631 8. New Functions 3633 Depending on the system, the following interface can be implemented 3634 as a system call or library function. 3636 8.1. sctp_bindx() 3638 This function allows the user to bind a specific subset of addresses 3639 or, if the SCTP extension described in [RFC5061] is supported, add or 3640 delete specific addresses. 3642 The function prototype is 3644 int sctp_bindx(int sd, 3645 struct sockaddr *addrs, 3646 int addrcnt, 3647 int flags); 3649 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3650 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3651 or IPv6 addresses. 3653 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3654 Section 3.1.2 for this usage. 3656 addrs is a pointer to an array of one or more socket addresses. Each 3657 address is contained in its appropriate structure. For an IPv6 3658 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 3659 array of sockaddr_in is used. The caller specifies the number of 3660 addresses in the array with addrcnt. Note that the wildcard 3661 addresses cannot be used in combination with non wildcard addresses 3662 on a socket with this function, doing so will result in an error. 3664 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3665 -1 and sets errno to the appropriate error code. 3667 For SCTP, the port given in each socket address must be the same, or 3668 sctp_bindx() will fail, setting errno to EINVAL. 3670 The flags parameter is formed from the bitwise OR of zero or more of 3671 the following currently defined flags: 3672 o SCTP_BINDX_ADD_ADDR 3673 o SCTP_BINDX_REM_ADDR 3674 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3675 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3676 addresses from the association. The two flags are mutually 3677 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3678 caller may not remove all addresses from an association; sctp_bindx() 3679 will reject such an attempt with EINVAL. 3681 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3682 additional addresses with an endpoint after calling bind(). Or use 3683 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3684 socket is associated with, so that no new association accepted will 3685 be associated with these addresses. If the endpoint supports dynamic 3686 address reconfiguration an SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR 3687 may cause an endpoint to send the appropriate message to the peer to 3688 change the peer's address lists. 3690 Adding and removing addresses from a connected association is an 3691 optional functionality. Implementations that do not support this 3692 functionality should return -1 and set errno to EOPNOTSUPP. 3694 sctp_bindx() can be called on an already bound socket or on an 3695 unbound socket. If the socket is unbound and the first port number 3696 in the addrs is zero, the kernel will choose a port number. All port 3697 numbers after the first one being 0 must also be zero. If the first 3698 port number is not zero, the following port numbers must be zero or 3699 have the same value as the first one. For an already bound socket, 3700 all port numbers provided must be the bound one or 0. 3702 sctp_bindx() is an atomic operation. Therefore, the binding will be 3703 either successful on all addresses or fail on all addresses. If 3704 multiple addresses are provided and the sctp_bindx() call fails there 3705 is no indication which address is responsible for the failure. The 3706 only way to get a specific error indication is to call sctp_bindx() 3707 with only one address sequentially. 3709 8.2. sctp_peeloff() 3711 After an association is established on a one-to-many style socket, 3712 the application may wish to branch off the association into a 3713 separate socket/file descriptor. 3715 This is particularly desirable when, for instance, the application 3716 wishes to have a number of sporadic message senders/receivers remain 3717 under the original one-to-many style socket, but branch off these 3718 associations carrying high volume data traffic into their own 3719 separate socket descriptors. 3721 The application uses the sctp_peeloff() call to branch off an 3722 association into a separate socket (Note the semantics are somewhat 3723 changed from the traditional one-to-one style accept() call). Note 3724 that the new socket is a one-to-one style socket. Thus it will be 3725 confined to operations allowed for a one-to-one style socket. 3727 The function prototype is 3729 int sctp_peeloff(int sd, 3730 sctp_assoc_t assoc_id); 3732 and the arguments are 3733 sd: The original one-to-many style socket descriptor returned from 3734 the socket() system call (see Section 3.1.1). 3735 assoc_id: the specified identifier of the association that is to be 3736 branched off to a separate file descriptor (Note, in a traditional 3737 one-to-one style accept() call, this would be an out parameter, 3738 but for the one-to-many style call, this is an in parameter). 3739 The function returns a non-negative file descriptor representing the 3740 branched-off association, or -1 if an error occurred. The variable 3741 errno is then set appropriately. 3743 8.3. sctp_getpaddrs() 3745 sctp_getpaddrs() returns all peer addresses in an association. 3747 The function protoype is: 3749 int sctp_getpaddrs(int sd, 3750 sctp_assoc_t id, 3751 struct sockaddr **addrs); 3753 On return, addrs will point to an array dynamically allocated 3754 sockaddr structures of the appropriate type for the socket type. The 3755 caller should use sctp_freepaddrs() to free the memory. Note that 3756 the in/out parameter addrs must not be NULL. 3758 If sd is an IPv4 socket, the addresses returned will be all IPv4 3759 addresses. If sd is an IPv6 socket, the addresses returned can be a 3760 mix of IPv4 or IPv6 addresses. 3762 For one-to-many style sockets, id specifies the association to query. 3763 For one-to-one style sockets, id is ignored. 3765 On success, sctp_getpaddrs() returns the number of peer addresses in 3766 the association. If there is no association on this socket, 3767 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3768 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3769 is undefined. 3771 8.4. sctp_freepaddrs() 3773 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 3775 The function prototype is 3777 void sctp_freepaddrs(struct sockaddr *addrs); 3779 and addrs is the array of peer addresses returned by 3780 sctp_getpaddrs(). 3782 8.5. sctp_getladdrs() 3784 sctp_getladdrs() returns all locally bound address(es) on a socket. 3786 The function prototype is 3788 int sctp_getladdrs(int sd, 3789 sctp_assoc_t id, 3790 struct sockaddr **addrs); 3792 On return, addrs will point to a dynamically allocated array of 3793 sockaddr structures of the appropriate type for the socket type. The 3794 caller should use sctp_freeladdrs() to free the memory. Note that 3795 the in/out parameter addrs must not be NULL. 3797 If sd is an IPv4 socket, the addresses returned will be all IPv4 3798 addresses. If sd is an IPv6 socket, the addresses returned can be a 3799 mix of IPv4 or IPv6 addresses. 3801 For one-to-many style sockets, id specifies the association to query. 3802 For one-to-one style sockets, id is ignored. 3804 If the id field is set to the value '0' then the locally bound 3805 addresses are returned without regard to any particular association. 3807 On success, sctp_getladdrs() returns the number of local addresses 3808 bound to the socket. If the socket is unbound, sctp_getladdrs() 3809 returns 0, and the value of *addrs is undefined. If an error occurs, 3810 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3812 8.6. sctp_freeladdrs() 3814 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 3816 The function prototype is 3818 void sctp_freeladdrs(struct sockaddr *addrs); 3820 and addrs is the array of local addresses returned by 3821 sctp_getladdrs(). 3823 8.7. sctp_sendmsg() 3825 This function is deprecated, sctp_sendv() should be used instead. 3827 An implementation may provide a library function (or possibly system 3828 call) to assist the user with the advanced features of SCTP. 3830 The function prototype is 3832 ssize_t sctp_sendmsg(int sd, 3833 const void *msg, 3834 size_t len, 3835 const struct sockaddr *to, 3836 socklen_t tolen, 3837 uint32_t ppid, 3838 uint32_t flags, 3839 uint16_t stream_no, 3840 uint32_t pr_value, 3841 uint32_t context); 3843 and the arguments are: 3844 sd: The socket descriptor. 3845 msg: The message to be sent. 3846 len: The length of the message. 3847 to: The destination address of the message. 3848 tolen: The length of the destination address. 3849 ppid: The same as sinfo_ppid (see Section 5.2.2). 3850 flags: The same as sinfo_flags (see Section 5.2.2). 3851 stream_no: The same as sinfo_stream (see Section 5.2.2). 3852 pr_value: The same as sinfo_pr_value (see Section 5.2.2). 3853 context: The same as sinfo_context (see Section 5.2.2). 3854 The call returns the number of characters sent, or -1 if an error 3855 occurred. The variable errno is then set appropriately. 3857 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 3858 marking is enabled on the socket specified by sd). 3860 Using sctp_sendmsg() on a non-connected one-to-one style socket for 3861 implicit connection setup may or may not work depending on the SCTP 3862 implementation. 3864 8.8. sctp_recvmsg() 3866 This function is deprecated, sctp_recvv() should be used instead. 3868 An implementation may provide a library function (or possibly system 3869 call) to assist the user with the advanced features of SCTP. Note 3870 that in order for the sctp_sndrcvinfo structure to be filled in by 3871 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3872 the SCTP_EVENTS option. Note that the setting of the 3873 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 3874 sctp_sndrcvinfo information to be extended. 3876 The function prototype is 3877 ssize_t sctp_recvmsg(int sd, 3878 void *msg, 3879 size_t len, 3880 struct sockaddr *from, 3881 socklen_t *fromlen 3882 struct sctp_sndrcvinfo *sinfo 3883 int *msg_flags); 3885 and the arguments are 3886 sd: The socket descriptor. 3887 msg: The message buffer to be filled. 3888 len: The length of the message buffer. 3889 from: A pointer to an address to be filled with the sender of this 3890 messages address. 3891 fromlen: An in/out parameter describing the from length. 3892 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 3893 receipt of the message. 3894 msg_flags: A pointer to an integer to be filled with any message 3895 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 3896 field. Options for the receive may also be passed into the value 3897 (e.g. MSG_PEEK). On return from the call, the msg_flags value 3898 will be different than what was sent in to the call. If 3899 implemented via a recvmsg() call, the msg_flags should only 3900 contain the value of the flags from the recvmsg() call. 3901 The call returns the number of bytes received, or -1 if an error 3902 occurred. The variable errno is then set appropriately. 3904 8.9. sctp_connectx() 3906 An implementation may provide a library function (or possibly system 3907 call) to assist the user with associating to an endpoint that is 3908 multi-homed. Much like sctp_bindx() this call allows a caller to 3909 specify multiple addresses at which a peer can be reached. The way 3910 the SCTP stack uses the list of addresses to set up the association 3911 is implementation dependent. This function only specifies that the 3912 stack will try to make use of all the addresses in the list when 3913 needed. 3915 Note that the list of addresses passed in is only used for setting up 3916 the association. It does not necessarily equal the set of addresses 3917 the peer uses for the resulting association. If the caller wants to 3918 find out the set of peer addresses, it must use sctp_getpaddrs() to 3919 retrieve them after the association has been set up. 3921 The function prototype is 3922 int sctp_connectx(int sd, 3923 struct sockaddr *addrs, 3924 int addrcnt, 3925 sctp_assoc_t *id); 3927 and the arguments are: 3928 sd: The socket descriptor. 3929 addrs: An (packed) array of addresses. 3930 addrcnt: The number of addresses in the array. 3931 id: An output parameter that if passed in as a non-NULL will return 3932 the association identification for the newly created association 3933 (if successful). 3935 The call returns 0 on success or -1 if an error occurred. The 3936 variable errno is then set appropriately. 3938 8.10. sctp_send() 3940 This function is deprecated, sctp_sendv() should be used instead. 3942 An implementation may provide another alternative function or system 3943 call to assist an application with the sending of data without the 3944 use of the CMSG header structures. 3946 The function prototype is 3948 ssize_t sctp_send(int sd, 3949 const void *msg, 3950 size_t len, 3951 const struct sctp_sndrcvinfo *sinfo, 3952 int flags); 3954 and the arguments are 3955 sd: The socket descriptor. 3956 msg: The message to be sent. 3957 len: The length of the message. 3958 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 3959 in Section 5.2.2 for a sendmsg() call. 3960 flags: The same flags as used by the sendmsg() call flags (e.g. 3961 MSG_DONTROUTE). 3962 The call returns the number of bytes sent, or -1 if an error 3963 occurred. The variable errno is then set appropriately. 3965 This function call may also be used to terminate an association using 3966 an association identification by setting the sinfo.sinfo_flags to 3967 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3968 to be terminated. In such a case the len of the message can be zero. 3970 Using sctp_send() on a non-connected one-to-one style socket for 3971 implicit connection setup may or may not work depending on the SCTP 3972 implementation. 3974 Sending a message using sctp_send() is atomic unless explicit EOR 3975 marking is enabled on the socket specified by sd. 3977 8.11. sctp_sendx() 3979 This function is deprecated, sctp_sendv() should be used instead. 3981 An implementation may provide another alternative function or system 3982 call to assist an application with the sending of data without the 3983 use of the CMSG header structures that also gives a list of 3984 addresses. The list of addresses is provided for implicit 3985 association setup. In such a case the list of addresses serves the 3986 same purpose as the addresses given in sctp_connectx() (see 3987 Section 8.9). 3989 The function prototype is 3991 ssize_t sctp_sendx(int sd, 3992 const void *msg, 3993 size_t len, 3994 struct sockaddr *addrs, 3995 int addrcnt, 3996 struct sctp_sndrcvinfo *sinfo, 3997 int flags); 3999 and the arguments are: 4000 sd: The socket descriptor. 4001 msg: The message to be sent. 4002 len: The length of the message. 4003 addrs: is an array of addresses. 4004 addrcnt: The number of addresses in the array. 4005 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 4006 Section 5.2.2 for a sendmsg() call. 4007 flags: The same flags as used by the sendmsg() call flags (e.g. 4008 MSG_DONTROUTE). 4009 The call returns the number of bytes sent, or -1 if an error 4010 occurred. The variable errno is then set appropriately. 4012 Note that in case of implicit connection setup, on return from this 4013 call the sinfo_assoc_id field of the sinfo structure will contain the 4014 new association id. 4016 This function call may also be used to terminate an association using 4017 an association identification by setting the sinfo.sinfo_flags to 4018 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4019 to be terminated. In such a case the len of the message would be 4020 zero. 4022 Sending a message using sctp_send() is atomic unless explicit EOR 4023 marking is enabled on the socket specified by sd. 4025 Using sctp_sendx() on a non-connected one-to-one style socket for 4026 implicit connection setup may or may not work depending on the SCTP 4027 implementation. 4029 8.12. sctp_recvv() 4031 An implementation may provide a library function (or possibly system 4032 call) to assist the user with the advanced features of SCTP. Note 4033 that in order for the sctp_recvinfo structure to be filled in by 4034 sctp_recvv() the caller must set the SCTP_RECVRCVINFO and 4035 SCTP_RECVNXTINFO socket option. 4037 The function prototype is 4039 struct sctp_recvinfo { 4040 uint16_t recv_version; 4041 uint16_t recv_length; 4042 uint32_t recv_flags; 4043 struct sctp_rcvinfo recv_rcvinfo; 4044 struct sctp_rcvinfo recv_nxtinfo; 4045 }; 4047 ssize_t sctp_recvv(int sd, 4048 const struct iovec *msg_iov, 4049 size_t msg_iovlen, 4050 struct sockaddr *from, 4051 socklen_t *fromlen 4052 struct sctp_recvinfo *info 4053 int *msg_flags); 4055 and the arguments are 4056 sd: The socket descriptor. 4057 msg_iov: The scatter buffer. Not more than one user message is 4058 provided. 4059 msg_iovlen: The number of elements in msg_iov. 4060 from: A pointer to an address to be filled with the sender of this 4061 message's address. 4063 fromlen: An in/out parameter describing the from length. 4064 info: A pointer to an sctp_recvinfo structure to be filled upon 4065 receipt of the message. The recv_length field is the length of 4066 the struct sctp_recvinfo. The recv_version for the structure as 4067 defined in this document is 1. If the sctp_recvinfo is valid, the 4068 recv_flags field indicates if the recv_rcvinfo or recv_rcvinfo is 4069 valid. The recv_flags field holds a bit wise or of 4070 SCTP_RECV_RCVINFO_VALID and SCTP_RECV_NXTINFO_VALID. 4071 msg_flags: A pointer to an integer to be filled with any message 4072 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4073 field. Options for the receive may also be passed into the value 4074 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4075 will be different than what was sent in to the call. If 4076 implemented via a recvmsg() call, the msg_flags should only 4077 contain the value of the flags from the recvmsg() call. 4078 The call returns the number of bytes received, or -1 if an error 4079 occurred. The variable errno is then set appropriately. 4081 8.13. sctp_sendv() 4083 An implementation may provide another alternative function or system 4084 call to assist an application with the sending of data without the 4085 use of the CMSG header structures that also gives a list of 4086 addresses. The list of addresses is provided for implicit 4087 association setup. In such a case the list of addresses serves the 4088 same purpose as the addresses given in sctp_connectx() (see 4089 Section 8.9). 4091 The function prototype is 4093 struct sctp_sendinfo { 4094 uint16_t send_version; 4095 uint16_t send_length; 4096 uint32_t send_flags; 4097 struct sctp_sndinfo send_sndinfo; 4098 struct sctp_prinfo send_prinfo; 4099 struct sctp_authinfo send_authinfo; 4100 }; 4102 ssize_t sctp_sendv(int sd, 4103 const struct iovec *msg_iov, 4104 size_t msg_iovlen, 4105 struct sockaddr *addrs, 4106 int addrcnt, 4107 struct sctp_sendinfo *info, 4108 int flags); 4110 and the arguments are: 4112 sd: The socket descriptor. 4113 msg_iov: The gather buffer. It is treated as at most one single 4114 user message. 4115 msg_iovlen: The number of elements in msg_iov. 4116 addrs: is an array of addresses. 4117 addrcnt: The number of addresses in the array. 4118 info: A pointer to a sctp_sendinfo structure. The send_length field 4119 is the length of the struct sctp_sendinfo. The send_version for 4120 the structure as defined in this document is 1. If the 4121 sctp_sendinfo is valid, the send_flags field indicates if the 4122 send_sndinfo, send_prinfo or send_authinfo is valid. The 4123 send_flags field holds a bit wise or of SCTP_SEND_SNDINFO_VALID, 4124 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID. 4125 flags: The same flags as used by the sendmsg() call flags (e.g. 4126 MSG_DONTROUTE). 4127 The call returns the number of bytes sent, or -1 if an error 4128 occurred. The variable errno is then set appropriately. 4130 Note that in case of implicit connection setup, on return from this 4131 call the send_sndinfo.snd_assoc_id will contain the new association 4132 id. 4134 This function call may also be used to terminate an association using 4135 an association identification by setting the send_sndinfo.snd_flags 4136 to SCTP_EOF and the send_sndinfo.snd_sid to the association that 4137 needs to be terminated. In such a case the len of the message would 4138 be zero. 4140 Sending a message using sctp_sendv() is atomic unless explicit EOR 4141 marking is enabled on the socket specified by sd. 4143 Using sctp_sendv() on a non-connected one-to-one style socket for 4144 implicit connection setup may or may not work depending on the SCTP 4145 implementation. 4147 9. IANA Considerations 4149 This document requires no actions from IANA. 4151 10. Security Considerations 4153 Many TCP and UDP implementations reserve port numbers below 1024 for 4154 privileged users. If the target platform supports privileged users, 4155 the SCTP implementation should restrict the ability to call bind() or 4156 sctp_bindx() on these port numbers to privileged users. 4158 Similarly unprivileged users should not be able to set protocol 4159 parameters that could result in the congestion control algorithm 4160 being more aggressive than permitted on the public Internet. These 4161 parameters are: 4162 o struct sctp_rtoinfo 4164 If an unprivileged user inherits a one-to-many style socket with open 4165 associations on a privileged port, it may be permitted to accept new 4166 associations, but it should not be permitted to open new 4167 associations. This could be relevant for the r* family of protocols. 4169 Applications using the one-to-many style sockets and using the 4170 interleave level if 0 are subject to denial of service attacks as 4171 described in Section 7.1.20. 4173 11. Acknowledgments 4175 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4176 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4177 early formation of this document. 4179 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 4180 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 4181 Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG 4182 mailing list for contributing valuable comments. 4184 A special thanks to Phillip Conrad, for his suggested text, quick and 4185 constructive insights, and most of all his persistent fighting to 4186 keep the interface to SCTP usable for the application programmer. 4188 12. References 4190 12.1. Normative References 4192 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4193 Stevens, "Basic Socket Interface Extensions for IPv6", 4194 RFC 3493, February 2003. 4196 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4197 "Advanced Sockets Application Program Interface (API) for 4198 IPv6", RFC 3542, May 2003. 4200 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4201 Conrad, "Stream Control Transmission Protocol (SCTP) 4202 Partial Reliability Extension", RFC 3758, May 2004. 4204 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4205 "Authenticated Chunks for the Stream Control Transmission 4206 Protocol (SCTP)", RFC 4895, August 2007. 4208 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4209 RFC 4960, September 2007. 4211 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4212 Kozuka, "Stream Control Transmission Protocol (SCTP) 4213 Dynamic Address Reconfiguration", RFC 5061, 4214 September 2007. 4216 12.2. Informative References 4218 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4219 RFC 793, September 1981. 4221 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4222 August 1980. 4224 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4225 Functional Specification", RFC 1644, July 1994. 4227 Appendix A. One-to-One Style Code Example 4229 The following code is a simple implementation of an echo server over 4230 SCTP. The example shows how to use some features of one-to-one style 4231 IPv4 SCTP sockets, including: 4232 o Opening, binding, and listening for new associations on a socket 4233 o Enabling ancillary data 4234 o Enabling notifications 4235 o Using ancillary data with sendmsg() and recvmsg() 4236 o Using MSG_EOR to determine if an entire message has been read 4237 o Handling notifications 4239 #include 4240 #include 4241 #include 4242 #include 4243 #include 4244 #include 4245 #include 4246 #include 4247 #include 4249 #define BUFLEN 100 4250 static void 4251 handle_event(void *buf) 4252 { 4253 struct sctp_assoc_change *sac; 4254 struct sctp_send_failed *ssf; 4255 struct sctp_paddr_change *spc; 4256 struct sctp_remote_error *sre; 4257 union sctp_notification *snp; 4258 char addrbuf[INET6_ADDRSTRLEN]; 4259 const char *ap; 4260 struct sockaddr_in *sin; 4261 struct sockaddr_in6 *sin6; 4263 snp = buf; 4265 switch (snp->sn_header.sn_type) { 4266 case SCTP_ASSOC_CHANGE: 4267 sac = &snp->sn_assoc_change; 4268 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 4269 "outstr=%hu\n", sac->sac_state, sac->sac_error, 4270 sac->sac_inbound_streams, sac->sac_outbound_streams); 4271 break; 4272 case SCTP_SEND_FAILED: 4273 ssf = &snp->sn_send_failed; 4274 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 4275 ssf->ssf_error); 4276 break; 4278 case SCTP_PEER_ADDR_CHANGE: 4279 spc = &snp->sn_paddr_change; 4280 if (spc->spc_aaddr.ss_family == AF_INET) { 4281 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4282 ap = inet_ntop(AF_INET, &sin->sin_addr, 4283 addrbuf, INET6_ADDRSTRLEN); 4284 } else { 4285 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4286 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4287 addrbuf, INET6_ADDRSTRLEN); 4288 } 4289 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 4290 spc->spc_state, spc->spc_error); 4291 break; 4292 case SCTP_REMOTE_ERROR: 4293 sre = &snp->sn_remote_error; 4294 printf("^^^ remote_error: err=%hu len=%hu\n", 4295 ntohs(sre->sre_error), ntohs(sre->sre_length)); 4296 break; 4297 case SCTP_SHUTDOWN_EVENT: 4299 printf("^^^ shutdown event\n"); 4300 break; 4301 default: 4302 printf("unknown type: %hu\n", snp->sn_header.sn_type); 4303 break; 4304 }; 4305 } 4307 static void * 4308 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 4309 ssize_t *nrp, size_t cmsglen) 4310 { 4311 ssize_t nr = 0, nnr = 0; 4312 struct iovec iov; 4314 *nrp = 0; 4315 iov.iov_base = buf; 4316 iov.iov_len = *buflen; 4317 msg->msg_iov = &iov; 4318 msg->msg_iovlen = 1; 4320 for (;;) { 4321 #ifndef MSG_XPG4_2 4322 #define MSG_XPG4_2 0 4323 #endif 4324 msg->msg_flags = MSG_XPG4_2; 4325 msg->msg_controllen = cmsglen; 4327 nnr = recvmsg(fd, msg, 0); 4328 if (nnr <= 0) { 4329 /* EOF or error */ 4330 *nrp = nr; 4331 return (NULL); 4332 } 4333 nr += nnr; 4335 if ((msg->msg_flags & MSG_EOR) != 0) { 4336 *nrp = nr; 4337 return (buf); 4338 } 4340 /* Realloc the buffer? */ 4341 if (*buflen == (size_t)nr) { 4342 buf = realloc(buf, *buflen * 2); 4343 if (buf == 0) { 4344 fprintf(stderr, "out of memory\n"); 4345 exit(1); 4347 } 4348 *buflen *= 2; 4349 } 4350 /* Set the next read offset */ 4351 iov.iov_base = (char *)buf + nr; 4352 iov.iov_len = *buflen - nr; 4353 } 4354 } 4356 static void 4357 echo(int fd, int socketModeone_to_many) 4358 { 4359 ssize_t nr; 4360 struct sctp_sndrcvinfo *sri; 4361 struct msghdr msg; 4362 struct cmsghdr *cmsg; 4363 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 4364 char *buf; 4365 size_t buflen; 4366 struct iovec iov; 4367 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 4368 /* Allocate the initial data buffer */ 4369 buflen = BUFLEN; 4370 if (!(buf = malloc(BUFLEN))) { 4371 fprintf(stderr, "out of memory\n"); 4372 exit(1); 4373 } 4375 /* Set up the msghdr structure for receiving */ 4376 memset(&msg, 0, sizeof (msg)); 4377 msg.msg_control = cbuf; 4378 msg.msg_controllen = cmsglen; 4379 msg.msg_flags = 0; 4380 cmsg = (struct cmsghdr *)cbuf; 4381 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 4383 /* Wait for something to echo */ 4384 while (buf = mysctp_recvmsg(fd, &msg, 4385 buf, &buflen, &nr, cmsglen)) { 4387 /* Intercept notifications here */ 4388 if (msg.msg_flags & MSG_NOTIFICATION) { 4389 handle_event(buf); 4390 continue; 4391 } 4393 iov.iov_base = buf; 4394 iov.iov_len = nr; 4395 msg.msg_iov = &iov; 4396 msg.msg_iovlen = 1; 4398 printf("got %u bytes on stream %hu:\n", nr, 4399 sri->sinfo_stream); 4400 write(0, buf, nr); 4402 /* Echo it back */ 4403 msg.msg_flags = MSG_XPG4_2; 4404 if (sendmsg(fd, &msg, 0) < 0) { 4405 perror("sendmsg"); 4406 exit(1); 4407 } 4408 } 4410 if (nr < 0) { 4411 perror("recvmsg"); 4412 } 4413 if(socketModeone_to_many == 0) 4414 close(fd); 4415 } 4417 int main() 4418 { 4419 struct sctp_event_subscribe event; 4420 int lfd, cfd; 4421 int onoff = 1; 4422 struct sockaddr_in sin; 4423 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 4424 perror("socket"); 4425 exit(1); 4426 } 4428 sin.sin_family = AF_INET; 4429 sin.sin_port = htons(7); 4430 sin.sin_addr.s_addr = INADDR_ANY; 4431 if (bind(lfd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4432 perror("bind"); 4433 exit(1); 4434 } 4436 if (listen(lfd, 1) == -1) { 4437 perror("listen"); 4438 exit(1); 4439 } 4441 /* Wait for new associations */ 4442 for (;;) { 4443 if ((cfd = accept(lfd, NULL, 0)) == -1) { 4444 perror("accept"); 4445 exit(1); 4446 } 4448 /* Enable all events */ 4449 event.sctp_data_io_event = 1; 4450 event.sctp_association_event = 1; 4451 event.sctp_address_event = 1; 4452 event.sctp_send_failure_event = 1; 4453 event.sctp_peer_error_event = 1; 4454 event.sctp_shutdown_event = 1; 4455 event.sctp_partial_delivery_event = 1; 4456 event.sctp_adaptation_layer_event = 1; 4457 if (setsockopt(cfd, IPPROTO_SCTP, 4458 SCTP_EVENTS, &event, 4459 sizeof(event)) != 0) { 4460 perror("setevent failed"); 4461 exit(1); 4462 } 4463 /* Echo back any and all data */ 4464 echo(cfd,0); 4465 } 4466 } 4468 Appendix B. One-to-Many Style Code Example 4470 The following code is a simple implementation of an echo server over 4471 SCTP. The example shows how to use some features of one-to-many 4472 style IPv4 SCTP sockets, including: 4473 o Opening and binding of a socket 4474 o Enabling ancillary data 4475 o Enabling notifications 4476 o Using ancillary data with sendmsg() and recvmsg() 4477 o Using MSG_EOR to determine if an entire message has been read 4478 o Handling notifications 4480 Note most functions defined in Appendix A are reused in this example. 4482 int main() 4483 { 4484 int fd; 4485 int idleTime = 2; 4486 struct sockaddr_in sin; 4487 struct sctp_event_subscribe event; 4489 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 4490 perror("socket"); 4491 exit(1); 4492 } 4494 sin.sin_family = AF_INET; 4495 sin.sin_port = htons(7); 4496 sin.sin_addr.s_addr = INADDR_ANY; 4497 if (bind(fd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4498 perror("bind"); 4499 exit(1); 4500 } 4502 /* Enable all notifications and events */ 4503 event.sctp_data_io_event = 1; 4504 event.sctp_association_event = 1; 4505 event.sctp_address_event = 1; 4506 event.sctp_send_failure_event = 1; 4507 event.sctp_peer_error_event = 1; 4508 event.sctp_shutdown_event = 1; 4509 event.sctp_partial_delivery_event = 1; 4510 event.sctp_adaptation_layer_event = 1; 4511 if (setsockopt(fd, IPPROTO_SCTP, 4512 SCTP_EVENTS, &event, 4513 sizeof(event)) != 0) { 4514 perror("setevent failed"); 4515 exit(1); 4516 } 4517 /* Set associations to auto-close in 2 seconds of 4518 * inactivity 4519 */ 4520 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4521 &idleTime, 4) < 0) { 4522 perror("setsockopt SCTP_AUTOCLOSE"); 4523 exit(1); 4524 } 4526 /* Allow new associations to be accepted */ 4527 if (listen(fd, 1) < 0) { 4528 perror("listen"); 4529 exit(1); 4530 } 4532 /* Wait for new associations */ 4533 while(1){ 4534 /* Echo back any and all data */ 4535 echo(fd,1); /* from appendix a */ 4536 } 4537 } 4539 Authors' Addresses 4541 Randall R. Stewart 4542 Huawei 4543 Chapin, SC 29036 4544 USA 4546 Email: rstewart@huawei.com 4548 Kacheong Poon 4549 Oracle Corporation 4551 Email: ka-cheong.poon@oracle.com 4553 Michael Tuexen 4554 Muenster University of Applied Sciences 4555 Stegerwaldstr. 39 4556 48565 Steinfurt 4557 Germany 4559 Email: tuexen@fh-muenster.de 4561 Vladislav Yasevich 4562 HP 4563 110 Spitrook Rd 4564 Nashua, NH 03062 4565 USA 4567 Email: vladislav.yasevich@hp.com 4569 Peter Lei 4570 Cisco Systems, Inc. 4571 8735 West Higgins Road 4572 Suite 300 4573 Chicago, IL 60631 4574 USA 4576 Email: peterlei@cisco.com