idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-23.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 (July 12, 2010) is 5036 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: January 13, 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 July 12, 2010 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-23.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 January 13, 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 . . . . . . . . . . . . . . . . . . 16 83 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 84 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 17 85 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18 86 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19 87 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 19 88 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20 89 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21 90 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 21 91 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22 92 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 22 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) . . . . 29 101 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31 102 5.2.6. SCTP Next Receive Information Structure 103 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 32 104 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 32 105 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 33 106 5.2.9. SCTP Destination Address Structure (IPv4) 107 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . . 33 108 5.2.10. SCTP Destination Address Structure (IPv6) 109 (SCTP_DSTADDRV6) . . . . . . . . . . . . . . . . . . . 34 110 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 34 111 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 35 112 5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 36 113 5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 37 114 5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 38 115 5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 39 116 5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 40 117 5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 41 118 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 42 119 5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 42 120 5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 43 121 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 44 122 5.3.12. SCTP_SEND_FAILED_EVENT . . . . . . . . . . . . . . . . 44 123 5.4. Ancillary Data Considerations and Semantics . . . . . . . 45 124 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 45 125 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 46 126 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 46 127 6. Common Operations for Both Styles . . . . . . . . . . . . . . 47 128 6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 47 129 6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 49 130 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 50 131 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 50 132 6.5. Implicit Association Setup . . . . . . . . . . . . . . . . 51 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) . . . . . . . 54 137 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 56 138 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 56 139 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 57 140 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 57 141 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 57 142 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 57 143 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 58 144 7.1.10. Set Adaptation Layer Indicator 145 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 58 146 7.1.11. Enable/Disable Message Fragmentation 147 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 58 148 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 58 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) . 61 152 7.1.15. Set/Clear IPv4 Mapped Addresses 153 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 61 154 7.1.16. Get or Set the Maximum Fragmentation Size 155 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 61 156 7.1.17. Get or Set the List of Supported HMAC Identifiers 157 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 62 158 7.1.18. Get or Set the Active Shared Key 159 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 63 160 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 63 161 7.1.20. Get or Set Fragmented Interleave 162 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 64 163 7.1.21. Set or Get the SCTP Partial Delivery Point 164 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 65 165 7.1.22. Set or Get the Use of Extended Receive Info 166 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 66 167 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 66 168 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 66 169 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 67 170 7.1.26. Enable or Disable Explicit EOR Marking 171 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 67 172 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 67 173 7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 68 174 7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 175 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 68 176 7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 177 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 68 178 7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . . 68 179 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 68 180 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 69 181 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 70 182 7.2.3. Get the List of Chunks the Peer Requires to be 183 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 71 184 7.2.4. Get the List of Chunks the Local Endpoint Requires 185 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 71 186 7.2.5. Get the Current Number of Associations 187 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 72 188 7.2.6. Get the Current Identifiers of Associations 189 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 72 190 7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 72 191 7.3.1. Set Peer Primary Address 192 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 72 193 7.3.2. Add a Chunk That Must Be Authenticated 194 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 73 195 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 73 196 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 74 197 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 74 198 7.4. Ancillary Data and Notification Interest Options . . . . . 75 199 8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 78 200 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 78 201 8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 80 202 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 80 203 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 81 204 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 81 205 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 82 206 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 82 207 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 83 208 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 84 209 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 85 210 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 86 211 8.12. sctp_recvxxx() . . . . . . . . . . . . . . . . . . . . . . 87 212 8.13. sctp_sendxxx() . . . . . . . . . . . . . . . . . . . . . . 88 213 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 89 214 10. Security Considerations . . . . . . . . . . . . . . . . . . . 89 215 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 89 216 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 90 217 12.1. Normative References . . . . . . . . . . . . . . . . . . . 90 218 12.2. Informative References . . . . . . . . . . . . . . . . . . 90 219 Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 90 220 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 96 221 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 97 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 The one-to-many style interface has the following characteristics: 289 o Outbound association setup is implicit. 290 o Messages are delivered in complete messages (with one notable 291 exception). 292 o There is a 1 to many relationship between socket and association. 294 3.1. Basic Operation 296 A typical server in this style uses the following socket calls in 297 sequence to prepare an endpoint for servicing requests: 298 o socket() 299 o bind() 300 o listen() 301 o recvmsg() 302 o sendmsg() 303 o close() 305 A typical client uses the following calls in sequence to setup an 306 association with a server to request services: 307 o socket() 308 o sendmsg() 309 o recvmsg() 310 o close() 312 In this style, by default, all the associations connected to the 313 endpoint are represented with a single socket. Each association is 314 assigned an association ID (type is sctp_assoc_t) so that an 315 application can use it to differentiate between them. In some 316 implementations, the peer endpoints' addresses can also be used for 317 this purpose. But this is not required for performance reasons. If 318 an implementation does not support using addresses to differentiate 319 between different associations, the sendto() call can only be used to 320 setup an association implicitly. It cannot be used to send data to 321 an established association as the association ID cannot be specified. 323 Once as association ID is assigned to an SCTP association, that ID 324 will not be reused until the application explicitly terminates the 325 association. The resources belonging to that association will not be 326 freed until that happens. This is similar to the close() operation 327 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 328 option (section 7.1.8) is set. In this case, after the association 329 is terminated gracefully and automatically, the association ID 330 assigned to it can be reused. All applications using this option 331 should be aware of this to avoid the possible problem of sending data 332 to an incorrect peer endpoint. 334 If the server or client wishes to branch an existing association off 335 to a separate socket, it is required to call sctp_peeloff() and to 336 specify the association identifier. The sctp_peeloff() call will 337 return a new socket which can then be used with recv() and send() 338 functions for message passing. See Section 8.2 for more on branched- 339 off associations. The returned socket is a one-to-one style socket. 341 Once an association is branched off to a separate socket, it becomes 342 completely separated from the original socket. All subsequent 343 control and data operations to that association must be done through 344 the new socket. For example, the close operation on the original 345 socket will not terminate any associations that have been branched 346 off to a different socket. 348 One-to-many style socket calls are discussed in more detail in the 349 following subsections. 351 3.1.1. socket() 353 Applications use socket() to create a socket descriptor to represent 354 an SCTP endpoint. 356 The function prototype is 358 int socket(int domain, 359 int type, 360 int protocol); 362 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 363 type and IPPROTO_SCTP as the protocol. 365 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 366 socket. 368 Using the PF_INET domain indicates the creation of an endpoint which 369 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 370 can use both IPv6 and IPv4 addresses. 372 3.1.2. bind() 374 Applications use bind() to specify which local address and port the 375 SCTP endpoint should associate itself with. 377 An SCTP endpoint can be associated with multiple addresses. To do 378 this, sctp_bindx() is introduced in Section 8.1 to help applications 379 do the job of associating multiple addresses. But note that an 380 endpoint can only be associated with one local port. 382 These addresses associated with a socket are the eligible transport 383 addresses for the endpoint to send and receive data. The endpoint 384 will also present these addresses to its peers during the association 385 initialization process, see [RFC4960]. 387 After calling bind(), if the endpoint wishes to accept new 388 associations on the socket, it must call listen() (see 389 Section 3.1.3). 391 The function prototype of bind() is 393 int bind(int sd, 394 struct sockaddr *addr, 395 socklen_t addrlen); 397 and the arguments are 398 sd: The socket descriptor returned by socket(). 399 addr: The address structure (struct sockaddr_in for an IPv4 address 400 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 401 addrlen: The size of the address structure. 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. 440 Note that one-to-many style socket consumers do not need to call 441 accept to retrieve new associations. Calling accept() on a one-to- 442 many style socket should return EOPNOTSUPP. Rather, new associations 443 are accepted automatically, and notifications of the new associations 444 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 445 these notifications are enabled). Clients will typically not call 446 listen(), so that they can be assured that only actively initiated 447 associations are on the socket. Server or peer-to-peer sockets, on 448 the other hand, will always accept new associations, so a well- 449 written application using server one-to-many style sockets must be 450 prepared to handle new associations from unwanted peers. 452 Also note that the SCTP_ASSOC_CHANGE event provides the association 453 ID for a new association, so if applications wish to use the 454 association ID as input to other socket calls, they should ensure 455 that the SCTP_ASSOC_CHANGE event is enabled. 457 3.1.4. sendmsg() and recvmsg() 459 An application uses the sendmsg() and recvmsg() call to transmit data 460 to and receive data from its peer. 462 The function prototypes are 464 ssize_t sendmsg(int sd, 465 const struct msghdr *message, 466 int flags); 468 and 470 ssize_t recvmsg(int sd, 471 struct msghdr *message, 472 int flags); 474 using the arguments: 475 sd: The socket descriptor of the endpoint. 476 message: Pointer to the msghdr structure which contains a single 477 user message and possibly some ancillary data. See Section 5 for 478 complete description of the data structures. 479 flags: No new flags are defined for SCTP at this level. See 480 Section 5 for SCTP specific flags used in the msghdr structure. 482 As described in Section 5, different types of ancillary data can be 483 sent and received along with user data. When sending, the ancillary 484 data is used to specify the sent behavior, such as the SCTP stream 485 number to use. When receiving, the ancillary data is used to 486 describe the received data, such as the SCTP stream sequence number 487 of the message. 489 When sending user data with sendmsg(), the msg_name field in the 490 msghdr structure will be filled with one of the transport addresses 491 of the intended receiver. If there is no existing association 492 between the sender and the intended receiver, the sender's SCTP stack 493 will set up a new association and then send the user data (see 494 Section 6.5 for more on implicit association setup). If sendmsg() is 495 called with no data and there is no existing association, a new one 496 will be established. The SCTP_INIT type ancillary data can be used 497 to change some of the parameters used to set up a new association. 498 If sendmsg() is called with NULL data, and there is no existing 499 association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is 500 retured and errno is set to EINVAL. Sending a message using 501 sendmsg() is atomic unless explicit EOR marking is enabled on the 502 socket specified by sd (see Section 7.1.26). 504 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 505 be delivered if that notification has been enabled, and no more data 506 can be sent to that association. Any attempt to send more data will 507 cause sendmsg() to return with an ESHUTDOWN error. Note that the 508 socket is still open for reading at this point so it is possible to 509 retrieve notifications. 511 When receiving a user message with recvmsg(), the msg_name field in 512 the msghdr structure will be populated with the source transport 513 address of the user data. The caller of recvmsg() can use this 514 address information to determine to which association the received 515 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 516 disabled, applications must use the peer transport address provided 517 in the msg_name field by recvmsg() to perform correlation to an 518 association, since they will not have the association ID. 520 If all data in a single message has been delivered, MSG_EOR will be 521 set in the msg_flags field of the msghdr structure (see section 522 Section 5.1). 524 If the application does not provide enough buffer space to completely 525 receive a data message, MSG_EOR will not be set in msg_flags. 526 Successive reads will consume more of the same message until the 527 entire message has been delivered, and MSG_EOR will be set. 529 If the SCTP stack is running low on buffers, it may partially deliver 530 a message. In this case, MSG_EOR will not be set, and more calls to 531 recvmsg() will be necessary to completely consume the message. Only 532 one message at a time can be partially delivered in any stream. The 533 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 534 what interlacing of messages occurs for both the one-to-one and the 535 one-to-many model sockets. Please consult Section 7.1.20 for further 536 details on message delivery options. 538 Note, if the socket is a branched-off socket that only represents one 539 association (see Section 3.1), the msg_name field can be used to 540 override the primary address when sending data. 542 3.1.5. close() 544 Applications use close() to perform graceful shutdown (as described 545 in Section 10.1 of [RFC4960]) on all the associations currently 546 represented by a one-to-many style socket. 548 The function prototype is 550 int close(int sd); 552 and the argument is 553 sd: The socket descriptor of the associations to be closed. 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 and 559 possibly passing a user specified abort code in the data field. Both 560 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 561 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. 583 Multiple connect() calls can be made on the same socket to create 584 multiple associations. This is different from the semantics of 585 connect() on a UDP socket. 587 3.2. Non-blocking mode 589 Some SCTP application may wish to avoid being blocked when calling a 590 socket interface function. 592 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 593 one-to-many style socket, an application may set the non-blocking 594 option by a fcntl() (such as O_NONBLOCK). After setting the socket 595 to non-blocking mode, the sendmsg() function returns immediately. 596 The success or failure of sending the data message (with possible 597 SCTP_INITMSG ancillary data) will be signaled by the 598 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or CANT_START_ASSOC. If 599 user data could not be sent (due to a CANT_START_ASSOC), the sender 600 will also receive an SCTP_SEND_FAILED event. Events can be received 601 by the user calling recvmsg(). A server (having called listen()) is 602 also notified of an association up event by the reception of an 603 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 604 possibly the reception of the first data message. 606 To shutdown the association gracefully, the user must call sendmsg() 607 with no data and with the SCTP_EOF flag set. The function returns 608 immediately, and completion of the graceful shutdown is indicated by 609 an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see 610 Section 5.3.2). Note that this can also be done using the 611 sctp_send() call described in Section 8.10. 613 An application is recommended to use caution when using select() (or 614 poll()) for writing on a one-to-many style socket. The reason being 615 that the interpretation of select on write is implementation 616 specific. Generally a positive return on a select on write would 617 only indicate that one of the associations represented by the one-to- 618 many socket is writable. An application that writes after the 619 select() returns may still block since the association that was 620 writeable is not the destination association of the write call. 621 Likewise select() (or poll()) for reading from a one-to-many socket 622 will only return an indication that one of the associations 623 represented by the socket has data to be read. 625 An application that wishes to know that a particular association is 626 ready for reading or writing should either use the one-to-one style 627 or use the sctp_peeloff() (see Section 8.2) function to separate the 628 association of interest from the one-to-many socket. 630 3.3. Special considerations 632 The fact that a one-to-many style socket can provide access to many 633 SCTP associations through a single socket descriptor has important 634 implications for both application programmers and system programmers 635 implementing this API. A key issue is how buffer space inside the 636 sockets layer is managed. Because this implementation detail 637 directly affects how application programmers must write their code to 638 ensure correct operation and portability, this section provides some 639 guidance to both implementers and application programmers. 641 An important feature that SCTP shares with TCP is flow control. 642 Specifically, a sender may not send data faster than the receiver can 643 consume it. 645 For TCP, flow control is typically provided for in the sockets API as 646 follows. If the reader stops reading, the sender queues messages in 647 the socket layer until it uses all of its socket buffer space 648 allocation creating a "stalled connection". Further attempts to 649 write to the socket will block or return the error EAGAIN or 650 EWOULDBLOCK for a non-blocking socket. At some point, either the 651 connection is closed, or the receiver begins to read again freeing 652 space in the output queue. 654 For one-to-one style SCTP sockets (this includes sockets descriptors 655 that were separated from a one-to-many style socket with 656 sctp_peeloff()) the behavior is identical. For one-to-many style 657 SCTP sockets there are multiple associations for a single socket, 658 which makes the situation more complicated. If the implementation 659 uses a single buffer space allocation shared by all associations, a 660 single stalled association can prevent the further sending of data on 661 all associations active on a particular one-to-many style socket. 663 For a blocking socket, it should be clear that a single stalled 664 association can block the entire socket. For this reason, 665 application programmers may want to use non-blocking one-to-many 666 style sockets. The application should at least be able to send 667 messages to the non-stalled associations. 669 But a non-blocking socket is not sufficient if the API implementer 670 has chosen a single shared buffer allocation for the socket. A 671 single stalled association would eventually cause the shared 672 allocation to fill, and it would become impossible to send even to 673 non-stalled associations. 675 The API implementer can solve this problem by providing each 676 association with its own allocation of outbound buffer space. Each 677 association should conceptually have as much buffer space as it would 678 have if it had its own socket. As a bonus, this simplifies the 679 implementation of sctp_peeloff(). 681 To ensure that a given stalled association will not prevent other 682 non-stalled associations from being writable, application programmers 683 should either: 684 o demand that the underlying implementation dedicates independent 685 buffer space reservation to each association (as suggested above), 686 or 687 o verify that their application layer protocol does not permit large 688 amounts of unread data at the receiver (this is true of some 689 request-response protocols, for example), or 690 o use one-to-one style sockets for association which may potentially 691 stall (either from the beginning, or by using sctp_peeloff before 692 sending large amounts of data that may cause a stalled condition). 694 4. One-to-One Style Interface 696 The goal of this style is to follow as closely as possible the 697 current practice of using the sockets interface for a connection 698 oriented protocol, such as TCP. This style enables existing 699 applications using connection oriented protocols to be ported to SCTP 700 with very little effort. 702 One-to-one style sockets can be connected (explicitly or implicitly) 703 at most once, simular to TCP sockets. 705 Note that some new SCTP features and some new SCTP socket options can 706 only be utilized through the use of sendmsg() and recvmsg() calls, 707 see Section 4.1.8. 709 4.1. Basic Operation 711 A typical server in one-to-one style uses the following system call 712 sequence to prepare an SCTP endpoint for servicing requests: 713 o socket() 714 o bind() 715 o listen() 716 o accept() 718 The accept() call blocks until a new association is set up. It 719 returns with a new socket descriptor. The server then uses the new 720 socket descriptor to communicate with the client, using recv() and 721 send() calls to get requests and send back responses. 723 Then it calls 724 o close() 725 to terminate the association. 727 A typical client uses the following system call sequence to setup an 728 association with a server to request services: 729 o socket() 730 o connect() 732 After returning from connect(), the client uses send()/sendmsg() and 733 recv()/recvmsg() calls to send out requests and receive responses 734 from the server. 736 The client calls 737 o close() 738 to terminate this association when done. 740 4.1.1. socket() 742 Applications call socket() to create a socket descriptor to represent 743 an SCTP endpoint. 745 The function prototype is 747 int socket(int domain, 748 int type, 749 int protocol); 751 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 752 type and IPPROTO_SCTP as the protocol. 754 Here, SOCK_STREAM indicates the creation of a one-to-one style 755 socket. 757 Using the PF_INET domain indicates the creation of an endpoint which 758 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 759 can use both IPv6 and IPv4 addresses. 761 4.1.2. bind() 763 Applications use bind() to specify which local address and port the 764 SCTP endpoint should associate itself with. 766 An SCTP endpoint can be associated with multiple addresses. To do 767 this, sctp_bindx() is introduced in Section 8.1 to help applications 768 do the job of associating multiple addresses. But note that an 769 endpoint can only be associated with one local port. 771 These addresses associated with a socket are the eligible transport 772 addresses for the endpoint to send and receive data. The endpoint 773 will also present these addresses to its peers during the association 774 initialization process, see [RFC4960]. 776 The function prototype of bind() is 778 int bind(int sd, 779 struct sockaddr *addr, 780 socklen_t addrlen); 782 and the arguments are 783 sd: The socket descriptor returned by socket(). 784 addr: The address structure (struct sockaddr_in for an IPv4 address 785 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 786 addrlen: The size of the address structure. 788 If sd is an IPv4 socket, the address passed must be an IPv4 address. 789 If the sd is an IPv6 socket, the address passed can either be an IPv4 790 or an IPv6 address. 792 Applications cannot call bind() multiple times to associate multiple 793 addresses to the endpoint. After the first call to bind(), all 794 subsequent calls will return an error. 796 If the IP address part of addr is specified as a wildcard (INADDR_ANY 797 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 798 IPv6 address), the operating system will associate the endpoint with 799 an optimal address set of the available interfaces. If the IPv4 800 sin_port or IPv6 sin6_port is set to 0, the operating system will 801 choose an ephemeral port for the endpoint. 803 If a bind() is not called prior to the connect() call, the system 804 picks an ephemeral port and will choose an address set equivalent to 805 binding with a wildcard address. One of these addresses will be the 806 primary address for the association. This automatically enables the 807 multi-homing capability of SCTP. 809 The completion of this bind() process does not ready the SCTP 810 endpoint to accept inbound SCTP association requests. Until a 811 listen() system call, described below, is performed on the socket, 812 the SCTP endpoint will promptly reject an inbound SCTP INIT request 813 with an SCTP ABORT. 815 4.1.3. listen() 817 Applications use listen() to ready the SCTP endpoint for accepting 818 inbound associations. 820 The function prototype is 822 int listen(int sd, 823 int backlog); 825 and the arguments are 826 sd: the socket descriptor of the SCTP endpoint. 827 backlog: this specifies the max number of outstanding associations 828 allowed in the socket's accept queue. These are the associations 829 that have finished the four-way initiation handshake (see Section 830 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 831 of '0' indicates that the caller no longer wishes to receive new 832 associations. 834 4.1.4. accept() 836 Applications use the accept() call to remove an established SCTP 837 association from the accept queue of the endpoint. A new socket 838 descriptor will be returned from accept() to represent the newly 839 formed association. 841 The function prototype is 843 int accept(int sd, 844 struct sockaddr *addr, 845 socklen_t *addrlen); 847 and the arguments are 848 sd: The listening socket descriptor. 849 addr: On return, addr (struct sockaddr_in for an IPv4 address or 850 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 851 contain the primary address of the peer endpoint. 852 addrlen: On return, addrlen will contain the size of addr. 853 The functions returns the socket descriptor for the newly formed 854 association. 856 4.1.5. connect() 858 Applications use connect() to initiate an association to a peer. 860 The function prototype is 862 int connect(int sd, 863 const struct sockaddr *addr, 864 socklen_t addrlen); 866 and the arguments are 867 sd: The socket descriptor of the endpoint. 868 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 869 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 870 addrlen: The size of the address. 872 This operation corresponds to the ASSOCIATE primitive described in 873 section 10.1 of [RFC4960]. 875 The number of outbound streams the new association has is stack 876 dependent. Applications can use the SCTP_INITMSG option described in 877 Section 7.1.3 should be used before connecting to change the number 878 of outbound streams. 880 If a bind() is not called prior to the connect() call, the system 881 picks an ephemeral port and will choose an address set equivalent to 882 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 883 respectively. One of the addresses will be the primary address for 884 the association. This automatically enables the multi-homing 885 capability of SCTP. 887 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 888 during the association set up phase. If an application wants to do 889 this, it cannot use the connect() call. Instead, it should use 890 sendto() or sendmsg() to initiate an association. If it uses 891 sendto() and it wants to change the initialization behavior, it needs 892 to use the SCTP_INITMSG socket option before calling sendto(). Or it 893 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 894 association without doing the setsockopt(). Note that the implicit 895 setup is supported for the one-to-many style sockets. 897 SCTP does not support half close semantics. This means that unlike 898 T/TCP, MSG_EOF should not be set in the flags parameter when calling 899 sendto() or sendmsg() when the call is used to initiate a connection. 900 MSG_EOF is not an acceptable flag with an SCTP socket. 902 4.1.6. close() 904 Applications use close() to gracefully close down an association. 906 The function prototype is 908 int close(int sd); 910 and the argument is 911 sd: The socket descriptor of the association to be closed. 913 After an application calls close() on a socket descriptor, no further 914 socket operations will succeed on that descriptor. 916 4.1.7. shutdown() 918 SCTP differs from TCP in that it does not have half closed semantics. 919 Hence the shutdown() call for SCTP is an approximation of the TCP 920 shutdown() call, and solves some different problems. Full TCP- 921 compatibility is not provided, so developers porting TCP applications 922 to SCTP may need to recode sections that use shutdown(). (Note that 923 it is possible to achieve the same results as half close in SCTP 924 using SCTP streams.) 926 The function prototype is 928 int shutdown(int sd, 929 int how); 931 and the arguments are 932 sd: The socket descriptor of the association to be closed. 933 how: Specifies the type of shutdown. The values are as follows: 934 SHUT_RD: Disables further receive operations. No SCTP protocol 935 action is taken. 936 SHUT_WR: Disables further send operations, and initiates the SCTP 937 shutdown sequence. 938 SHUT_RDWR: Disables further send and receive operations and 939 initiates the SCTP shutdown sequence. 941 The major difference between SCTP and TCP shutdown() is that SCTP 942 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 943 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 944 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 945 the SCTP association while still leaving the socket descriptor open. 946 This allows the caller to receive back any data which SCTP is unable 947 to deliver (see Section 5.3.5 for more information) and receive event 948 notifications. 950 To perform the ABORT operation described in [RFC4960] section 10.1, 951 an application can use the socket option SO_LINGER. It is described 952 in Section 7.1.4. 954 4.1.8. sendmsg() and recvmsg() 956 With a one-to-one style socket, the application can also use 957 sendmsg() and recvmsg() to transmit data to and receive data from its 958 peer. The semantics is similar to those used in the one-to-many 959 style (section Section 3.1.3), with the following differences: 960 1. When sending, the msg_name field in the msghdr is not used to 961 specify the intended receiver, rather it is used to indicate a 962 preferred peer address if the sender wishes to discourage the 963 stack from sending the message to the primary address of the 964 receiver. If the socket is connected and the transport address 965 given is not part of the current association, the data will not 966 be sent and an SCTP_SEND_FAILED event will be delivered to the 967 application if send failure events are enabled. 968 2. Using sendmsg() on a non-connected one-to-one style socket for 969 implicit connection setup may or may not work depending on the 970 SCTP implementation. 972 4.1.9. getpeername() 974 Applications use getpeername() to retrieve the primary socket address 975 of the peer. This call is for TCP compatibility, and is not multi- 976 homed. It does not work with one-to-many style sockets. See 977 Section 8.3 for a multi-homed/one-to-many style version of the call. 979 The function prototype is 981 int getpeername(int sd, 982 struct sockaddr *address, 983 socklen_t *len); 985 and the arguments are: 986 sd: The socket descriptor to be queried. 988 address: On return, the peer primary address is stored in this 989 buffer. If the socket is an IPv4 socket, the address will be 990 IPv4. If the socket is an IPv6 socket, the address will be either 991 an IPv6 or IPv4 address. 992 len: The caller should set the length of address here. On return, 993 this is set to the length of the returned address. 995 If the actual length of the address is greater than the length of the 996 supplied sockaddr structure, the stored address will be truncated. 998 5. Data Structures 1000 This section discusses important data structures which are specific 1001 to SCTP and are used with sendmsg() and recvmsg() calls to control 1002 SCTP endpoint operations and to access ancillary information and 1003 notifications. 1005 5.1. The msghdr and cmsghdr Structures 1007 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1008 well as the ancillary data carried in the structure, is the key for 1009 the application to set and get various control information from the 1010 SCTP endpoint. 1012 The msghdr and the related cmsghdr structures are defined and 1013 discussed in detail in [RFC3542]. They are defined as: 1015 struct msghdr { 1016 void *msg_name; /* ptr to socket address structure */ 1017 socklen_t msg_namelen; /* size of socket address structure */ 1018 struct iovec *msg_iov; /* scatter/gather array */ 1019 size_t msg_iovlen; /* # elements in msg_iov */ 1020 void *msg_control; /* ancillary data */ 1021 socklen_t msg_controllen; /* ancillary data buffer length */ 1022 int msg_flags; /* flags on received message */ 1023 }; 1025 struct cmsghdr { 1026 socklen_t cmsg_len; /* #bytes, including this header */ 1027 int cmsg_level; /* originating protocol */ 1028 int cmsg_type; /* protocol-specific type */ 1029 /* followed by unsigned char cmsg_data[]; */ 1030 }; 1032 In the msghdr structure, the usage of msg_name has been discussed in 1033 previous sections (see Section 3.1.3 and Section 4.1.8). 1035 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1036 field) are treated as a single SCTP data chunk, rather than multiple 1037 chunks, for both sendmsg() and recvmsg(). 1039 The msg_flags are not used when sending a message with sendmsg(). 1041 If a notification has arrived, recvmsg() will return the notification 1042 with the MSG_NOTIFICATION flag set in msg_flags. If the 1043 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1044 Section 5.3 for more information about notifications. 1046 If all portions of a data frame or notification have been read, 1047 recvmsg() will return with MSG_EOR set in msg_flags. 1049 5.2. SCTP msg_control Structures 1051 A key element of all SCTP specific socket extensions is the use of 1052 ancillary data to specify and access SCTP specific data via the 1053 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1054 Fine-grained control over initialization and sending parameters are 1055 handled with ancillary data. 1057 Each ancillary data item is proceeded by a struct cmsghdr (see 1058 Section 5.1), which defines the function and purpose of the data 1059 contained in the cmsg_data[] member. 1061 By default on either style socket, SCTP will pass no ancillary data; 1062 Specific ancillary data items can be enabled with socket options 1063 defined for SCTP; see Section 7.4. 1065 Note that all ancillary types are fixed length; see Section 5.4 for 1066 further discussion on this. These data structures use struct 1067 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1068 address format. 1070 Other protocols may also provide ancillary data to the socket layer 1071 consumer. These ancillary data items from other protocols may 1072 intermingle with SCTP data. For example, the IPv6 socket API 1073 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1074 data items. If a socket API consumer enables delivery of both SCTP 1075 and IPv6 ancillary data, they both may appear in the same msg_control 1076 buffer in any order. An application may thus need to handle other 1077 types of ancillary data besides those passed by SCTP. 1079 The sockets application must provide a buffer large enough to 1080 accommodate all ancillary data provided via recvmsg(). If the buffer 1081 is not large enough, the ancillary data will be truncated and the 1082 msghdr's msg_flags will include MSG_CTRUNC. 1084 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1086 This cmsghdr structure provides information for initializing new SCTP 1087 associations with sendmsg(). The SCTP_INITMSG socket option uses 1088 this same data structure. This structure is not used for recvmsg(). 1090 +--------------+-----------+---------------------+ 1091 | cmsg_level | cmsg_type | cmsg_data[] | 1092 +--------------+-----------+---------------------+ 1093 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1094 +--------------+-----------+---------------------+ 1096 The sctp_initmsg structure is defined below: 1098 struct sctp_initmsg { 1099 uint16_t sinit_num_ostreams; 1100 uint16_t sinit_max_instreams; 1101 uint16_t sinit_max_attempts; 1102 uint16_t sinit_max_init_timeo; 1103 }; 1105 sinit_num_ostreams: This is an integer number representing the 1106 number of streams that the application wishes to be able to send 1107 to. This number is confirmed in the SCTP_COMM_UP notification and 1108 must be verified since it is a negotiated number with the remote 1109 endpoint. The default value of 0 indicates to use the endpoint 1110 default value. 1111 sinit_max_instreams: This value represents the maximum number of 1112 inbound streams the application is prepared to support. This 1113 value is bounded by the actual implementation. In other words the 1114 user may be able to support more streams than the Operating 1115 System. In such a case, the Operating System limit overrides the 1116 value requested by the user. The default value of 0 indicates to 1117 use the endpoints default value. 1118 sinit_max_attempts: This integer specifies how many attempts the 1119 SCTP endpoint should make at resending the INIT. This value 1120 overrides the system SCTP 'Max.Init.Retransmits' value. The 1121 default value of 0 indicates to use the endpoints default value. 1122 This is normally set to the system's default 'Max.Init.Retransmit' 1123 value. 1124 sinit_max_init_timeo: This value represents the largest Time-Out or 1125 RTO value (in milliseconds) to use in attempting an INIT. 1126 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1127 upon timeout. For the INIT message this value may override 1128 'RTO.Max'. This value must not influence 'RTO.Max' during data 1129 transmission and is only used to bound the initial setup time. A 1130 default value of 0 indicates to use the endpoints default value. 1131 This is normally set to the system's 'RTO.Max' value (60 seconds). 1133 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1135 This cmsghdr structure specifies SCTP options for sendmsg() and 1136 describes SCTP header information about a received message through 1137 recvmsg(). This structure mixes the send and receive path. 1138 SCTP_SNDINFO described in Section 5.2.4 and SCTP_RCVINFO described in 1139 Section 5.2.5 split this information. These structures should be 1140 used, when possible, since SCTP_SNDRCV is deprecated. 1142 +--------------+-------------+------------------------+ 1143 | cmsg_level | cmsg_type | cmsg_data[] | 1144 +--------------+-------------+------------------------+ 1145 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1146 +--------------+-------------+------------------------+ 1148 The sctp_sndrcvinfo structure is defined below: 1150 struct sctp_sndrcvinfo { 1151 uint16_t sinfo_stream; 1152 uint16_t sinfo_ssn; 1153 uint16_t sinfo_flags; 1154 uint32_t sinfo_ppid; 1155 uint32_t sinfo_context; 1156 uint32_t sinfo_pr_value; 1157 uint32_t sinfo_tsn; 1158 uint32_t sinfo_cumtsn; 1159 sctp_assoc_t sinfo_assoc_id; 1160 }; 1162 sinfo_stream: For recvmsg() the SCTP stack places the message's 1163 stream number in this value. For sendmsg() this value holds the 1164 stream number that the application wishes to send this message to. 1165 If a sender specifies an invalid stream number an error indication 1166 is returned and the call fails. 1167 sinfo_ssn: For recvmsg() this value contains the stream sequence 1168 number that the remote endpoint placed in the DATA chunk. For 1169 fragmented messages this is the same number for all deliveries of 1170 the message (if more than one recvmsg() is needed to read the 1171 message). The sendmsg() call will ignore this parameter. 1172 sinfo_flags: This field may contain any of the following flags and 1173 is composed of a bitwise OR of these values. 1174 recvmsg() flags: 1175 SCTP_UNORDERED: This flag is present when the message was sent 1176 non-ordered. 1178 sendmsg() flags: 1179 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1180 the message. If this flag is clear the datagram is 1181 considered an ordered send. 1182 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1183 the SCTP stack to override the primary destination address 1184 with the address found with the sendto/sendmsg call. 1185 SCTP_ABORT: Setting this flag causes the specified association 1186 to abort by sending an ABORT message to the peer (one-to- 1187 many style only). The ABORT chunk will contain an error 1188 cause 'User Initiated Abort' with cause code 12. The cause 1189 specific information of this error cause is provided in 1190 msg_iov. 1191 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1192 procedure on the specified association. Graceful shutdown 1193 assures that all data queued by both endpoints is 1194 successfully transmitted before closing the association 1195 (one-to-many style only). 1196 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1197 model socket to send the message to all associations that 1198 are currently established on this socket. For the one-to- 1199 one socket, this flag has no effect. 1200 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1201 passed to the remote end in each user message. In recvmsg() this 1202 value is the same information that was passed by the upper layer 1203 in the peer application. Please note that the SCTP stack performs 1204 no byte order modification of this field. For example, if the 1205 DATA chunk has to contain a given value in network byte order, the 1206 SCTP user has to perform the htonl() computation. 1207 sinfo_context: This value is an opaque 32 bit context datum that is 1208 used in the sendmsg() function. This value is passed back to the 1209 upper layer if an error occurs on the send of a message and is 1210 retrieved with each undelivered message (Note: if an endpoint has 1211 done multiple sends, all of which fail, multiple different 1212 sinfo_context values will be returned. One with each user data 1213 message). 1214 sinfo_pr_value: The meaning of this field depends on the PR-SCTP 1215 policy specified by the sinfo_pr_policy field. It is ignored when 1216 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1217 lifetime is specified. 1218 sinfo_tsn: For the receiving side, this field holds a TSN that was 1219 assigned to one of the SCTP Data Chunks. 1220 sinfo_cumtsn: This field will hold the current cumulative TSN as 1221 known by the underlying SCTP layer. Note this field is ignored 1222 when sending. 1224 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1225 the identifier for the association announced in the SCTP_COMM_UP 1226 notification. All notifications for a given association have the 1227 same identifier. Ignored for one-to-one style sockets. 1229 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1231 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1233 This cmsghdr structure specifies SCTP options for SCTP header 1234 information about a received message via recvmsg(). Note that this 1235 structure is an extended version of SCTP_SNDRCV (see Section 5.2.2) 1236 and will only be received if the user has set the socket option 1237 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1238 needed to receive ancillary data. See Section 7.1.22 on this socket 1239 option. Note that next message data is not valid unless the current 1240 message is completely read, i.e. the MSG_EOR is set, in other words 1241 if the application has more data to read from the current message 1242 then no next message information will be available. 1244 SCTP_NXTINFO described in Section 5.2.6 should be used when possible, 1245 since SCTP_EXTRCV is considered deprecated. 1247 +--------------+-------------+------------------------+ 1248 | cmsg_level | cmsg_type | cmsg_data[] | 1249 +--------------+-------------+------------------------+ 1250 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1251 +--------------+-------------+------------------------+ 1253 The sctp_extrcvinfo structure is defined below: 1255 struct sctp_extrcvinfo { 1256 uint16_t sinfo_stream; 1257 uint16_t sinfo_ssn; 1258 uint16_t sinfo_flags; 1259 uint32_t sinfo_ppid; 1260 uint32_t sinfo_context; 1261 uint32_t sinfo_pr_value; 1262 uint32_t sinfo_tsn; 1263 uint32_t sinfo_cumtsn; 1264 uint16_t serinfo_next_flags; 1265 uint16_t serinfo_next_stream; 1266 uint32_t serinfo_next_aid; 1267 uint32_t serinfo_next_length; 1268 uint32_t serinfo_next_ppid; 1269 sctp_assoc_t sinfo_assoc_id; 1270 }; 1271 sinfo_*: Please see Section 5.2.2 for the details for these fields. 1272 serinfo_next_flags: This bitmask will hold one or more of the 1273 following values: 1274 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1275 message information is available i.e.: next_stream, 1276 next_asocid, next_length and next_ppid fields all have valid 1277 values. If this bit is set to 0, then these fields are not 1278 valid and should be ignored. 1279 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1280 next message is completely in the receive buffer. The 1281 next_length field thus contains the entire message size. If 1282 this flag is set to 0, then the next_length field only contains 1283 part of the message size since the message is still being 1284 received (it is being partially delivered). 1285 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1286 the next message to be received was sent by the peer as 1287 unordered. If this bit is not set (i.e the bit is 0) the next 1288 message to be read is an ordered message in the stream 1289 specified. 1290 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1291 the next message to be received is not a message from the peer, 1292 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1293 serinfo_next_stream: This value, when valid (see 1294 serinfo_next_flags), contains the next stream number that will be 1295 received on a subsequent call to one of the receive message 1296 functions. 1297 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1298 contains the next association identification that will be received 1299 on a subsequent call to one of the receive message functions. 1300 serinfo_next_length: This value, when valid (see 1301 serinfo_next_flags), contains the length of the next message that 1302 will be received on a subsequent call to one of the receive 1303 message functions. Note that this length may be a partial length 1304 depending on the settings of next_flags. 1305 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1306 contains the ppid of the next message that will be received on a 1307 subsequent call to one of the receive message functions. 1309 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) 1311 This cmsghdr structure specifies SCTP options for sendmsg(). 1313 +--------------+--------------+---------------------+ 1314 | cmsg_level | cmsg_type | cmsg_data[] | 1315 +--------------+--------------+---------------------+ 1316 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1317 +--------------+--------------+---------------------+ 1319 The sctp_sndinfo structure is defined below: 1321 struct sctp_sndinfo { 1322 uint16_t snd_sid; 1323 uint16_t snd_flags; 1324 uint32_t snd_ppid; 1325 uint32_t snd_context; 1326 sctp_assoc_t snd_assoc_id; 1327 }; 1329 snd_sid: This value holds the stream number that the application 1330 wishes to send this message to. If a sender specifies an invalid 1331 stream number an error indication is returned and the call fails. 1332 snd_flags: This field may contain any of the following flags and is 1333 composed of a bitwise OR of these values. 1335 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1336 message. If this flag is clear the datagram is considered an 1337 ordered send. 1338 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1339 SCTP stack to override the primary destination address with the 1340 address found with the sendto()/sendmsg call. 1341 SCTP_ABORT: Setting this flag causes the specified association to 1342 abort by sending an ABORT message to the peer (one-to-many 1343 style only). The ABORT chunk will contain an error cause 'User 1344 Initiated Abort' with cause code 12. The cause specific 1345 information of this error cause is provided in msg_iov. 1346 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1347 procedures on the specified association. Graceful shutdown 1348 assures that all data queued by both endpoints is successfully 1349 transmitted before closing the association (one-to-many style 1350 only). 1351 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1352 socket to send the message to all associations that are 1353 currently established on this socket. For the one-to-one 1354 socket, this flag has no effect. 1355 snd_ppid: This value in sendmsg() is an unsigned integer that is 1356 passed to the remote end in each user message. Please note that 1357 the SCTP stack performs no byte order modification of this field. 1358 For example, if the DATA chunk has to contain a given value in 1359 network byte order, the SCTP user has to perform the htonl() 1360 computation. 1361 snd_context: This value is an opaque 32 bit context datum that is 1362 used in the sendmsg() function. This value is passed back to the 1363 upper layer if an error occurs on the send of a message and is 1364 retrieved with each undelivered message (Note: if an endpoint has 1365 done multiple sends, all of which fail, multiple different 1366 sinfo_context values will be returned. One with each user data 1367 message). 1368 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1369 the identifier for the association announced in the SCTP_COMM_UP 1370 notification. All notifications for a given association have the 1371 same identifier. Ignored for one-to-one style sockets. 1373 An sctp_sndinfo item always corresponds to the data in msg_iov. 1375 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1377 This cmsghdr structure describes SCTP receive information about a 1378 received message through recvmsg(). 1380 To enable the delivery of this information an application must use 1381 the SCTP_RECVRCVINFO socket option (see Section 7.1.29). 1383 +--------------+--------------+---------------------+ 1384 | cmsg_level | cmsg_type | cmsg_data[] | 1385 +--------------+--------------+---------------------+ 1386 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1387 +--------------+--------------+---------------------+ 1389 The sctp_rcvinfo structure is defined below: 1391 struct sctp_rcvinfo { 1392 uint16_t rcv_sid; 1393 uint16_t rcv_ssn; 1394 uint16_t rcv_flags; 1395 uint32_t rcv_ppid; 1396 uint32_t rcv_tsn; 1397 uint32_t rcv_cumtsn; 1398 sctp_assoc_t rcv_assoc_id; 1399 }; 1401 rcv_sid: The SCTP stack places the message's stream number in this 1402 value. 1403 rcv_ssn: This value contains the stream sequence number that the 1404 remote endpoint placed in the DATA chunk. For fragmented messages 1405 this is the same number for all deliveries of the message (if more 1406 than one recvmsg() is needed to read the message). 1407 rcv_flags: This field may contain any of the following flags and is 1408 composed of a bitwise OR of these values. 1410 SCTP_UNORDERED: This flag is present when the message was sent 1411 non-ordered. 1413 rcv_ppid: This value is the same information that was passed by the 1414 upper layer in the peer application. Please note that the SCTP 1415 stack performs no byte order modification of this field. For 1416 example, if the DATA chunk has to contain a given value in network 1417 byte order, the SCTP user has to perform the htonl() computation. 1418 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1419 Data Chunks. 1420 rcv_cumtsn: This field will hold the current cumulative TSN as known 1421 by the underlying SCTP layer. 1422 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1423 the identifier for the association announced in the SCTP_COMM_UP 1424 notification. All notifications for a given association have the 1425 same identifier. Ignored for one-to-one style sockets. 1427 A sctp_rcvinfo item always corresponds to the data in msg_iov. 1429 5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1431 This cmsghdr structure describes SCTP receive information of the next 1432 message which will be delivered through recvmsg() if this information 1433 is already available when delivering the current message. 1435 It uses the same structure as the SCTP Receive Information Structure. 1437 To enable the delivery of this information an application must use 1438 the SCTP_RECVNXTINFO socket option (see Section 7.1.30). 1440 +--------------+--------------+---------------------+ 1441 | cmsg_level | cmsg_type | cmsg_data[] | 1442 +--------------+--------------+---------------------+ 1443 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo | 1444 +--------------+--------------+---------------------+ 1446 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1448 This cmsghdr structure specifies SCTP options for sendmsg(). 1450 +--------------+-------------+--------------------+ 1451 | cmsg_level | cmsg_type | cmsg_data[] | 1452 +--------------+-------------+--------------------+ 1453 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1454 +--------------+-------------+--------------------+ 1456 The sctp_prinfo structure is defined below: 1458 struct sctp_prinfo { 1459 uint16_t pr_policy; 1460 uint32_t pr_value; 1462 }; 1464 pr_policy: This specifies which PR-SCTP policy is used. Using 1465 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1466 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1467 defined in [RFC3758] is used. In this case, the lifetime is 1468 provided in pr_value. 1469 pr_value: The meaning of this field depends on the PR-SCTP policy 1470 specified by the pr_policy field. It is ignored when 1471 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1472 lifetime in milliseconds is specified. 1474 An sctp_prinfo item always corresponds to the data in msg_iov. 1476 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1478 This cmsghdr structure specifies SCTP options for sendmsg(). 1480 +--------------+---------------+----------------------+ 1481 | cmsg_level | cmsg_type | cmsg_data[] | 1482 +--------------+---------------+----------------------+ 1483 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1484 +--------------+---------------+----------------------+ 1486 The sctp_authinfo structure is defined below: 1488 struct sctp_authinfo { 1489 uint16_t auth_keyid; 1490 }; 1492 auth_keyid: This specifies the shared key identifier used for 1493 sending the user message. 1495 An sctp_authinfo item always corresponds to the data in msg_iov. 1496 Please note that the SCTP implementation must not bundle user 1497 messages that needs to be authenticated using different shared key 1498 identifiers. 1500 5.2.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4) 1502 This cmsghdr structure specifies SCTP options for sendmsg(). 1504 +--------------+----------------+----------------+ 1505 | cmsg_level | cmsg_type | cmsg_data[] | 1506 +--------------+----------------+----------------+ 1507 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1508 +--------------+----------------+----------------+ 1510 This ancillary data can be used to provide more than one destination 1511 address to sendmsg(). It can be used to implement sctp_sendxxx() 1512 using send_msg(). 1514 5.2.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 1516 This cmsghdr structure specifies SCTP options for sendmsg(). 1518 +--------------+----------------+-----------------+ 1519 | cmsg_level | cmsg_type | cmsg_data[] | 1520 +--------------+----------------+-----------------+ 1521 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1522 +--------------+----------------+-----------------+ 1524 This ancillary data can be used to provide more than one destination 1525 address to sendmsg(). It can be used to implement sctp_sendxxx() 1526 using send_msg(). 1528 5.3. SCTP Events and Notifications 1530 An SCTP application may need to understand and process events and 1531 errors that happen on the SCTP stack. These events include network 1532 status changes, association startups, remote operational errors and 1533 undeliverable messages. All of these can be essential for the 1534 application. 1536 When an SCTP application layer does a recvmsg() the message read is 1537 normally a data message from a peer endpoint. If the application 1538 wishes to have the SCTP stack deliver notifications of non-data 1539 events, it sets the appropriate socket option for the notifications 1540 it wants. See Section 7.4 for these socket options. When a 1541 notification arrives, recvmsg() returns the notification in the 1542 application-supplied data buffer via msg_iov, and sets 1543 MSG_NOTIFICATION in msg_flags. 1545 This section details the notification structures. Every notification 1546 structure carries some common fields which provide general 1547 information. 1549 A recvmsg() call will return only one notification at a time. Just 1550 as when reading normal data, it may return part of a notification if 1551 the msg_iov buffer is not large enough. If a single read is not 1552 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1553 reading the notification before subsequent data can arrive. 1555 5.3.1. SCTP Notification Structure 1557 The notification structure is defined as the union of all 1558 notification types. 1560 union sctp_notification { 1561 struct sctp_tlv { 1562 uint16_t sn_type; /* Notification type. */ 1563 uint16_t sn_flags; 1564 uint32_t sn_length; 1565 } sn_header; 1566 struct sctp_assoc_change sn_assoc_change; 1567 struct sctp_paddr_change sn_paddr_change; 1568 struct sctp_remote_error sn_remote_error; 1569 struct sctp_send_failed sn_send_failed; 1570 struct sctp_shutdown_event sn_shutdown_event; 1571 struct sctp_adaptation_event sn_adaptation_event; 1572 struct sctp_pdapi_event sn_pdapi_event; 1573 struct sctp_authkey_event sn_auth_event; 1574 struct sctp_sender_dry_event sn_sender_dry_event; 1575 }; 1577 sn_type: The following list describes the SCTP notification and 1578 event types for the field sn_type. 1579 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1580 either been opened or closed. Refer to Section 5.3.2 for 1581 details. 1582 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1583 part of an existing association has experienced a change of 1584 state (e.g. a failure or return to service of the reachability 1585 of an endpoint via a specific transport address). Please see 1586 Section 5.3.3 for data structure details. 1587 SCTP_REMOTE_ERROR: The attached error message is an Operational 1588 Error received from the remote peer. It includes the complete 1589 TLV sent by the remote endpoint. See Section 5.3.4 for the 1590 detailed format. 1591 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1592 remote endpoint. This structure includes the original 1593 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1594 structure uses the sctp_sndrcvinfo per Section 5.3.5. 1595 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1596 data should be sent on this socket. 1597 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1598 indicated adaptation layer. Please see Section 5.3.7. 1600 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1601 receiver that the partial delivery has been aborted. This may 1602 indicate the association is about to be aborted. Please see 1603 Section 5.3.8. 1604 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1605 receiver that either an error occurred on authentication, or a 1606 new key was made active. See Section 5.3.9. 1607 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1608 application that the sender has no user data queued anymore, 1609 neither for transmission nor retransmission. See 1610 Section 5.3.10. 1611 sn_flags: These are notification-specific flags. 1612 sn_length: This is the length of the whole sctp_notification 1613 structure including the sn_type, sn_flags, and sn_length fields. 1615 5.3.2. SCTP_ASSOC_CHANGE 1617 Communication notifications inform the ULP that an SCTP association 1618 has either begun or ended. The identifier for a new association is 1619 provided by this notification. The notification information has the 1620 following format: 1622 struct sctp_assoc_change { 1623 uint16_t sac_type; 1624 uint16_t sac_flags; 1625 uint32_t sac_length; 1626 uint16_t sac_state; 1627 uint16_t sac_error; 1628 uint16_t sac_outbound_streams; 1629 uint16_t sac_inbound_streams; 1630 sctp_assoc_t sac_assoc_id; 1631 uint8_t sac_info[]; 1632 }; 1634 sac_type: It should be SCTP_ASSOC_CHANGE. 1635 sac_flags: Currently unused. 1636 sac_length: This field is the total length of the notification data, 1637 including the notification header. 1638 sac_state: This field holds one of a number of values that 1639 communicate the event that happened to the association. They 1640 include: 1641 SCTP_COMM_UP: A new association is now ready and data may be 1642 exchanged with this peer. When an association has been 1643 established successfully, this notification should be the first 1644 one. 1646 SCTP_COMM_LOST: The association has failed. The association is 1647 now in the closed state. If SEND FAILED notifications are 1648 turned on, a SCTP_COMM_LOST is accompanied by a series of 1649 SCTP_SEND_FAILED events, one for each outstanding message. 1650 SCTP_RESTART: SCTP has detected that the peer has restarted. 1651 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1652 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1653 blocking mode is set and data was sent (on a one-to-many style 1654 socket), a SCTP_CANT_STR_ASSOC is accompanied by a series of 1655 SCTP_SEND_FAILED events, one for each outstanding message. 1656 sac_error: If the state was reached due to an error condition (e.g. 1657 SCTP_COMM_LOST) any relevant error information is available in 1658 this field. This corresponds to the protocol error codes defined 1659 in [RFC4960]. 1660 sac_outbound_streams: 1661 sac_inbound_streams: The maximum number of streams allowed in each 1662 direction are available in sac_outbound_streams and sac_inbound 1663 streams. 1664 sac_assoc_id: The association id field holds the identifier for the 1665 association. All notifications for a given association have the 1666 same association identifier. For a one-to-one style socket, this 1667 field is ignored. 1668 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1669 received for this association, sac_info[] contains the complete 1670 ABORT chunk as defined in the SCTP specification [RFC4960] section 1671 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1672 may contain an array of uint8_t describing the features that the 1673 current association supports. Features may include 1674 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1675 extension described in [RFC3758]. 1676 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1677 extension described in [RFC4895]. 1678 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1679 extension described in [RFC5061]. 1680 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 1681 local endpoints use separate send and/or receive buffers for 1682 each SCTP association. 1684 5.3.3. SCTP_PEER_ADDR_CHANGE 1686 When a destination address of a multi-homed peer encounters a state 1687 change a peer address change event is sent. The notification has the 1688 following format: 1690 struct sctp_paddr_change { 1691 uint16_t spc_type; 1692 uint16_t spc_flags; 1693 uint32_t spc_length; 1694 struct sockaddr_storage spc_aaddr; 1695 uint32_t spc_state; 1696 uint32_t spc_error; 1697 sctp_assoc_t spc_assoc_id; 1698 } 1700 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 1701 spc_flags: Currently unused. 1702 spc_length: This field is the total length of the notification data, 1703 including the notification header. 1704 spc_aaddr: The affected address field holds the remote peer's 1705 address that is encountering the change of state. 1706 spc_state: This field holds one of a number of values that 1707 communicate the event that happened to the address. They include: 1708 SCTP_ADDR_AVAILABLE: This address is now reachable. This 1709 notification is provided whenever an address becomes reachable 1710 and was unreachable. 1711 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 1712 reached. Any data sent to this address is rerouted to an 1713 alternate until this address becomes reachable. This 1714 notification is provided whenever an address becomes 1715 unreachable and was reachable. 1716 SCTP_ADDR_REMOVED: The address is no longer part of the 1717 association. 1718 SCTP_ADDR_ADDED: The address is now part of the association. 1719 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 1720 primary destination address. 1721 SCTP_ADDR_CONFIRMED: This address has now been confirmed as a 1722 valid address. This notification is provided once for each 1723 address as soon as the address is confirmed. 1724 spc_error: If the state was reached due to any error condition (e.g. 1725 SCTP_ADDR_UNREACHABLE) any relevant error information is available 1726 in this field. 1727 spc_assoc_id: The association id field holds the identifier for the 1728 association. All notifications for a given association have the 1729 same association identifier. For a one-to-one style socket, this 1730 field is ignored. 1732 5.3.4. SCTP_REMOTE_ERROR 1734 A remote peer may send an Operational Error message to its peer. 1735 This message indicates a variety of error conditions on an 1736 association. The entire ERROR chunk as it appears on the wire is 1737 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 1738 specification [RFC4960] and any extensions for a list of possible 1739 error formats. An SCTP error notification has the following format: 1741 struct sctp_remote_error { 1742 uint16_t sre_type; 1743 uint16_t sre_flags; 1744 uint32_t sre_length; 1745 uint16_t sre_error; 1746 sctp_assoc_t sre_assoc_id; 1747 uint8_t sre_data[]; 1748 }; 1750 sre_type: It should be SCTP_REMOTE_ERROR. 1751 sre_flags: Currently unused. 1752 sre_length: This field is the total length of the notification data, 1753 including the notification header and the contents of sre_data. 1754 sre_error: This value represents one of the Operational Error causes 1755 defined in the SCTP specification, in network byte order. 1756 sre_assoc_id: The association id field holds the identifier for the 1757 association. All notifications for a given association have the 1758 same association identifier. For a one-to-one style socket, this 1759 field is ignored. 1760 sre_data: This contains the ERROR chunk as defined in the SCTP 1761 specification [RFC4960] section 3.3.10. 1763 5.3.5. SCTP_SEND_FAILED 1765 Please note that this notification is deprecated. 1767 If SCTP cannot deliver a message, it can return back the message as a 1768 notification if the SCTP_SEND_FAILED event is enabled. The 1769 notification has the following format: 1771 struct sctp_send_failed { 1772 uint16_t ssf_type; 1773 uint16_t ssf_flags; 1774 uint32_t ssf_length; 1775 uint32_t ssf_error; 1776 struct sctp_sndrcvinfo ssf_info; 1777 sctp_assoc_t ssf_assoc_id; 1778 uint8_t ssf_data[]; 1779 }; 1781 ssf_type: It should be SCTP_SEND_FAILED. 1783 ssf_flags: The flag value will take one of the following values: 1784 SCTP_DATA_UNSENT: Indicates that the data was never put on the 1785 wire. 1786 SCTP_DATA_SENT: Indicates that the data was put on the wire. 1787 Note that this does not necessarily mean that the data was (or 1788 was not) successfully delivered. 1789 ssf_length: This field is the total length of the notification data, 1790 including the notification header and the payload in ssf_data. 1791 ssf_error: This value represents the reason why the send failed, and 1792 if set, will be an SCTP protocol error code as defined in 1793 [RFC4960] section 3.3.10. 1794 ssf_info: The send information associated with the undelivered 1795 message. The ssf_info.sinfo_flags field will also contain an 1796 indication if the beginning of the message and/or end of the 1797 message is present. In cases where no data has been sent on the 1798 wire, this field will have or'ed in the value SCTP_DATA_NOT_FRAG, 1799 which is a composition of both a "BEGIN" and "END" fragmentation 1800 bit. In cases where only part of the data has been sent, this 1801 field will have or'ed in the value SCTP_DATA_LAST_FRAG, which 1802 corresponds to the "END" bit. Note that the message itself may be 1803 more than one chunk. If the ssf_info.sinfo_flags field holds 1804 neither of these two values then a piece that has been fragmented 1805 and sent but not acknowledged is present. This piece is from an 1806 unspecified position in the message and the application can make 1807 no assumptions about the data itself. Applications wanting to 1808 examine a recovered message should look for the 1809 SCTP_DATA_NOT_FRAG. Without this flag the application should 1810 assume part of the message arrived and take appropriate steps to 1811 audit and recover any lost or missing data. 1812 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 1813 identifier for the association. All notifications for a given 1814 association have the same association identifier. For a one-to- 1815 one style socket, this field is ignored. 1816 ssf_data: The undelivered message or part of the undelivered message 1817 will be present in the ssf_data field. Note that the 1818 ssf_info.sinfo_flags field as noted above should be used to 1819 determine if a complete message is present or just a piece of the 1820 message. Note that only user data is present in this field, any 1821 chunk headers or SCTP common headers must be removed by the SCTP 1822 stack. 1824 5.3.6. SCTP_SHUTDOWN_EVENT 1826 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1827 inform the application that it should cease sending data. 1829 struct sctp_shutdown_event { 1830 uint16_t sse_type; 1831 uint16_t sse_flags; 1832 uint32_t sse_length; 1833 sctp_assoc_t sse_assoc_id; 1834 }; 1836 sse_type: It should be SCTP_SHUTDOWN_EVENT. 1837 sse_flags: Currently unused. 1838 sse_length: This field is the total length of the notification data, 1839 including the notification header. It will generally be sizeof 1840 (struct sctp_shutdown_event). 1841 sse_flags: Currently unused. 1842 sse_assoc_id: The association id field holds the identifier for the 1843 association. All notifications for a given association have the 1844 same association identifier. For a one-to-one style socket, this 1845 field is ignored. 1847 5.3.7. SCTP_ADAPTATION_INDICATION 1849 When a peer sends an Adaptation Layer Indication parameter as 1850 described in [RFC5061], SCTP delivers this notification to inform the 1851 application about the peer's adaptation layer indication. 1853 struct sctp_adaptation_event { 1854 uint16_t sai_type; 1855 uint16_t sai_flags; 1856 uint32_t sai_length; 1857 uint32_t sai_adaptation_ind; 1858 sctp_assoc_t sai_assoc_id; 1859 }; 1861 sai_type: It should be SCTP_ADAPTATION_INDICATION. 1862 sai_flags: Currently unused. 1863 sai_length: This field is the total length of the notification data, 1864 including the notification header. It will generally be sizeof 1865 (struct sctp_adaptation_event). 1866 sai_adaptation_ind: This field holds the bit array sent by the peer 1867 in the adaptation layer indication parameter. The bits are in 1868 network byte order. 1869 sai_assoc_id: The association id field holds the identifier for the 1870 association. All notifications for a given association have the 1871 same association identifier. For a one-to-one style socket, this 1872 field is ignored. 1874 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT 1876 When a receiver is engaged in a partial delivery of a message this 1877 notification will be used to indicate various events. 1879 struct sctp_pdapi_event { 1880 uint16_t pdapi_type; 1881 uint16_t pdapi_flags; 1882 uint32_t pdapi_length; 1883 uint32_t pdapi_indication; 1884 uint32_t pdapi_stream; 1885 uint32_t pdapi_seq; 1886 sctp_assoc_t pdapi_assoc_id; 1887 }; 1889 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 1890 pdapi_flags: Currently unused. 1891 pdapi_length: This field is the total length of the notification 1892 data, including the notification header. It will generally be 1893 sizeof(struct sctp_pdapi_event). 1894 pdapi_indication: This field holds the indication being sent to the 1895 application. Currently there is only one defined value: 1896 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 1897 delivery of a user message has been aborted. This happens, for 1898 example, if an association is aborted while a partial delivery 1899 is going on or the user message gets abandoned using PR-SCTP 1900 while the partial delivery of this message is going on. 1901 pdapi_stream: This field holds the stream on which the partial 1902 delivery event happened. 1903 pdapi_seq: This field holds the stream sequence number which was 1904 being partially delivered. 1905 pdapi_assoc_id: The association id field holds the identifier for 1906 the association. All notifications for a given association have 1907 the same association identifier. For a one-to-one style socket 1908 this field is ignored. 1910 5.3.9. SCTP_AUTHENTICATION_EVENT 1912 [RFC4895] defines an extension to authenticate SCTP messages. The 1913 following notification is used to report different events relating to 1914 the use of this extension. 1916 struct sctp_authkey_event { 1917 uint16_t auth_type; 1918 uint16_t auth_flags; 1919 uint32_t auth_length; 1920 uint16_t auth_keynumber; 1921 uint32_t auth_indication; 1922 sctp_assoc_t auth_assoc_id; 1923 }; 1925 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 1926 auth_flags: Currently unused. 1927 auth_length: This field is the total length of the notification 1928 data, including the notification header. It will generally be 1929 sizeof (struct sctp_authkey_event). 1930 auth_keynumber: This field holds the keynumber for the affected key 1931 indicated in the event (depends on auth_indication). 1932 auth_indication: This field holds the error or indication being 1933 reported. The following values are currently defined: 1934 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 1935 made active (used for the first time by the peer) and is now 1936 the active key. The auth_keynumber field holds the user 1937 specified key number. 1938 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 1939 support SCTP AUTH as defined in [RFC4895]. 1940 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 1941 implementation will not use the key identifier specified in 1942 auth_keynumber anymore. 1943 auth_assoc_id: The association id field holds the identifier for the 1944 association. All notifications for a given association have the 1945 same association identifier. For a one-to-one style socket this 1946 field is ignored. 1948 5.3.10. SCTP_SENDER_DRY_EVENT 1950 When the SCTP implementation has no user data anymore to send or 1951 retransmit, this notification is given to the user. If the user 1952 subscribes to this event and SCTP has at this point of time no user 1953 data to send or retransmit, this notification is also given to the 1954 user. 1956 struct sctp_sender_dry_event { 1957 uint16_t sender_dry_type; 1958 uint16_t sender_dry_flags; 1959 uint32_t sender_dry_length; 1960 sctp_assoc_t sender_dry_assoc_id; 1961 }; 1962 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 1963 sender_dry_flags: Currently unused. 1964 sender_dry_length: This field is the total length of the 1965 notification data, including the notification header. It will 1966 generally be sizeof(struct sctp_sender_dry_event). 1968 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT 1970 Notifications, when subscribed to, are reliable. They are always 1971 delivered as long as there is space in the socket receive buffer. 1972 However, if an implementation experiences a notification storm, it 1973 may run out of socket buffer space. When this occurs it may wish to 1974 disable notifications. If the implementation chooses to do this, it 1975 will append a final notification SCTP_NOTIFICATIONS_STOPPED_EVENT. 1976 This notification is an union sctp_notification, where only the 1977 struct sctp_tlv (see the union above) is used. That merely has this 1978 type in the sn_type field, the sn_length field set to the sizeof an 1979 sctp_tlv structure and the sn_flags set to 0. If an application 1980 receives this notification, it will need to resubscribe to any 1981 notifications of interest to it, except for the data io event. 1983 An endpoint is automatically subscribed to this event as soon as it 1984 is subscribed to any event other than data io events. 1986 5.3.12. SCTP_SEND_FAILED_EVENT 1988 If SCTP cannot deliver a message, it can return back the message as a 1989 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 1990 notification has the following format: 1992 struct sctp_send_failed { 1993 uint16_t ssf_type; 1994 uint16_t ssf_flags; 1995 uint32_t ssf_length; 1996 uint32_t ssf_error; 1997 struct sctp_sndinfo ssf_info; 1998 sctp_assoc_t ssf_assoc_id; 1999 uint8_t ssf_data[]; 2000 }; 2002 ssf_type: It should be SCTP_SEND_FAILED_EVENT. 2003 ssf_flags: The flag value will take one of the following values: 2004 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2005 wire. 2007 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2008 Note that this does not necessarily mean that the data was (or 2009 was not) successfully delivered. 2010 ssf_length: This field is the total length of the notification data, 2011 including the notification header and the payload in ssf_data. 2012 ssf_error: This value represents the reason why the send failed, and 2013 if set, will be an SCTP protocol error code as defined in 2014 [RFC4960] section 3.3.10. 2015 ssf_info: The send information associated with the undelivered 2016 message. The ssf_info.snd_flags field will also contain an 2017 indication if the beginning of the message and/or end of the 2018 message is present. In cases where no data has been sent on the 2019 wire, this field will have or'ed in the value SCTP_DATA_NOT_FRAG, 2020 which is a composition of both a "BEGIN" and "END" fragmentation 2021 bit. In cases where only part of the data has been sent, this 2022 field will have or'ed in the value SCTP_DATA_LAST_FRAG, which 2023 corresponds to the "END" bit. Note that the message itself may be 2024 more than one chunk. If the ssf_info.snd_flags field holds 2025 neither of these two values then a piece that has been fragmented 2026 and sent but not acknowledged is present. This piece is from an 2027 unspecified position in the message and the application can make 2028 no assumptions about the data itself. Applications wanting to 2029 examine a recovered message should look for the 2030 SCTP_DATA_NOT_FRAG. Without this flag the application should 2031 assume part of the message arrived and take appropriate steps to 2032 audit and recover any lost or missing data. 2033 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 2034 identifier for the association. All notifications for a given 2035 association have the same association identifier. For a one-to- 2036 one style socket, this field is ignored. 2037 ssf_data: The undelivered message or part of the undelivered message 2038 will be present in the ssf_data field. Note that the 2039 ssf_info.sinfo_flags field as noted above should be used to 2040 determine if a complete message is present or just a piece of the 2041 message. Note that only user data is present in this field, any 2042 chunk headers or SCTP common headers must be removed by the SCTP 2043 stack. 2045 5.4. Ancillary Data Considerations and Semantics 2047 Programming with ancillary socket data contains some subtleties and 2048 pitfalls, which are discussed below. 2050 5.4.1. Multiple Items and Ordering 2052 Multiple ancillary data items may be included in any call to 2053 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 2054 items, or both. 2056 The ordering of ancillary data items (either by SCTP or another 2057 protocol) is not significant and is implementation-dependent, so 2058 applications must not depend on any ordering. 2060 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 2061 correspond to the data in the msghdr's msg_iov member. There can be 2062 only one single such type ancillary data for each sendmsg() or 2063 recvmsg() call. 2065 5.4.2. Accessing and Manipulating Ancillary Data 2067 Applications can infer the presence of data or ancillary data by 2068 examining the msg_iovlen and msg_controllen msghdr members, 2069 respectively. 2071 Implementations may have different padding requirements for ancillary 2072 data, so portable applications should make use of the macros 2073 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 2074 [RFC3542] and the SCTP implementation's documentation for more 2075 information. The following is an example, from [RFC3542], 2076 demonstrating the use of these macros to access ancillary data: 2078 struct msghdr msg; 2079 struct cmsghdr *cmsgptr; 2081 /* fill in msg */ 2083 /* call recvmsg() */ 2085 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 2086 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 2087 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 2088 u_char *ptr; 2090 ptr = CMSG_DATA(cmsgptr); 2091 /* process data pointed to by ptr */ 2092 } 2093 } 2095 5.4.3. Control Message Buffer Sizing 2097 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2098 ancillary data will often be fundamental to the correct and sane 2099 operation of the sockets application. This is particularly true of 2100 the one-to-many semantics, but also of the one-to-one semantics. For 2101 example, if an application needs to send and receive data on 2102 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2103 ancillary data is indispensable. 2105 Given that some ancillary data is critical, and that multiple 2106 ancillary data items may appear in any order, applications should be 2107 carefully written to always provide a large enough buffer to contain 2108 all possible ancillary data that can be presented by recvmsg(). If 2109 the buffer is too small, and crucial data is truncated, it may pose a 2110 fatal error condition. 2112 Thus, it is essential that applications be able to deterministically 2113 calculate the maximum required buffer size to pass to recvmsg(). One 2114 constraint imposed on this specification that makes this possible is 2115 that all ancillary data definitions are of a fixed length. One way 2116 to calculate the maximum required buffer size might be to take the 2117 sum the sizes of all enabled ancillary data item structures, as 2118 calculated by CMSG_SPACE. For example, if we enabled 2119 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 2120 and allocate the buffer size as follows: 2122 size_t total; 2123 void *buf; 2125 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 2126 CMSG_SPACE(sizeof (struct in6_pktinfo)); 2128 buf = malloc(total); 2130 We could then use this buffer (buf) for msg_control on each call to 2131 recvmsg() and be assured that we would not lose any ancillary data to 2132 truncation. 2134 6. Common Operations for Both Styles 2136 6.1. send(), recv(), sendto(), and recvfrom() 2138 Applications can use send() and sendto() to transmit data to the peer 2139 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2140 data from the peer. 2142 The function prototypes are 2144 ssize_t send(int sd, 2145 const void *msg, 2146 size_t len, 2147 int flags); 2149 ssize_t sendto(int sd, 2150 const void *msg, 2151 size_t len, 2152 int flags, 2153 const struct sockaddr *to, 2154 socklen_t tolen); 2156 ssize_t recv(int sd, 2157 void *buf, 2158 size_t len, 2159 int flags); 2161 ssize_t recvfrom(int sd, 2162 void *buf, 2163 size_t len, 2164 int flags, 2165 struct sockaddr *from, 2166 socklen_t *fromlen); 2168 and the arguments are 2169 sd: The socket descriptor of an SCTP endpoint. 2170 msg: The message to be sent. 2171 len: the size of the message or the size of the buffer. 2172 to: one of the peer addresses of the association to be used to send 2173 the message. 2174 tolen: The size of the address. 2175 buf: The buffer to store a received message. 2176 from: The buffer to store the peer address used to send the received 2177 message. 2178 fromlen: The size of the from address. 2179 flags: (described below). 2181 These calls give access to only basic SCTP protocol features. If 2182 either peer in the association uses multiple streams, or sends 2183 unordered data, these calls will usually be inadequate, and may 2184 deliver the data in unpredictable ways. 2186 SCTP has the concept of multiple streams in one association. The 2187 above calls do not allow the caller to specify on which stream a 2188 message should be sent. The system uses stream 0 as the default 2189 stream for send() and sendto(). recv() and recvfrom() return data 2190 from any stream, but the caller can not distinguish the different 2191 streams. This may result in data seeming to arrive out of order. 2192 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2193 provide no indication. 2195 SCTP is message based. The msg buffer above in send() and sendto() 2196 is considered to be a single message. This means that if the caller 2197 wants to send a message that is composed by several buffers, the 2198 caller needs to combine them before calling send() or sendto(). 2199 Alternately, the caller can use sendmsg() to do that without 2200 combining them. Sending a message using send() or sendto() is atomic 2201 unless explicit EOR marking is enabled on the socket specified by sd. 2202 Using sendto() on a non-connected one-to-one style socket for 2203 implicit connection setup may or may not work depending on the SCTP 2204 implementation. recv() and recvfrom() cannot distinguish message 2205 boundaries. 2207 In receiving, if the buffer supplied is not large enough to hold a 2208 complete message, the receive call acts like a stream socket and 2209 returns as much data as will fit in the buffer. 2211 Note, the send() and recv() calls may not be used for a one-to-many 2212 style socket. 2214 Note, if an application calls a send function with no user data and 2215 no ancillary data the SCTP implementation should reject the request 2216 with an appropriate error message. An implementation is not allowed 2217 to send a DATA chunk with no user data [RFC4960]. 2219 6.2. setsockopt() and getsockopt() 2221 Applications use setsockopt() and getsockopt() to set or retrieve 2222 socket options. Socket options are used to change the default 2223 behavior of socket calls. They are described in Section 7. 2225 The function prototypes are 2227 int getsockopt(int sd, 2228 int level, 2229 int optname, 2230 void *optval, 2231 socklen_t *optlen); 2233 and 2235 int setsockopt(int sd, 2236 int level, 2237 int optname, 2238 const void *optval, 2239 socklen_t optlen); 2241 and the arguments are 2242 sd: The socket descriptor. 2243 level: Set to IPPROTO_SCTP for all SCTP options. 2244 optname: The option name. 2245 optval: The buffer to store the value of the option. 2246 optlen: The size of the buffer (or the length of the option 2247 returned). 2249 All socket options set on a one-to-one style listening socket also 2250 apply to all accepted sockets. For one-to-many style sockets often a 2251 socket option will pass a structure that includes an assoc_id field. 2252 This field can be filled with the association id of a particular 2253 association and unless otherwise specified can be filled with one of 2254 the following constants: 2255 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2256 after this socket option will be affected by this call. 2257 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2258 associations will be affected by this call, future associations 2259 will still receive the previous default value. 2260 SCTP_ALL_ASSOC: Specifies that all current and future associations 2261 will be affected by this call. 2263 6.3. read() and write() 2265 Applications can use read() and write() to send and receive data to 2266 and from a peer. They have the same semantics as send() and recv() 2267 except that the flags parameter cannot be used. 2269 Note, these calls, when used in the one-to-many style, should only be 2270 used with branched off socket descriptors (see Section 8.2). 2272 6.4. getsockname() 2274 Applications use getsockname() to retrieve the locally-bound socket 2275 address of the specified socket. This is especially useful if the 2276 caller let SCTP choose a local port. This call is for single homed 2277 endpoints. It does not work well with multi-homed endpoints. See 2278 Section 8.5 for a multi-homed version of the call. 2280 The function prototype is 2282 int getsockname(int sd, 2283 struct sockaddr *address, 2284 socklen_t *len); 2286 and the arguments are 2287 sd: The socket descriptor to be queried. 2288 address: On return, one locally bound address (chosen by the SCTP 2289 stack) is stored in this buffer. If the socket is an IPv4 socket, 2290 the address will be IPv4. If the socket is an IPv6 socket, the 2291 address will be either an IPv6 or IPv4 address. 2292 len: The caller should set the length of the address here. On 2293 return, this is set to the length of the returned address. 2295 If the actual length of the address is greater than the length of the 2296 supplied sockaddr structure, the stored address will be truncated. 2298 If the socket has not been bound to a local name, the value stored in 2299 the object pointed to by address is unspecified. 2301 6.5. Implicit Association Setup 2303 Once the bind() call is complete, the application can begin sending 2304 and receiving data using the sendmsg()/recvmsg() or sendto()/ 2305 recvfrom() calls, without going through any explicit association 2306 setup procedures (i.e., no connect() calls required). 2308 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2309 sender finds that no association exists between the sender and the 2310 intended receiver (identified by the address passed either in the 2311 msg_name field of msghdr structure in the sendmsg() call or the 2312 dest_addr field in the sendto() call), the SCTP stack will 2313 automatically setup an association to the intended receiver. 2315 Upon the successful association setup an SCTP_COMM_UP notification 2316 will be dispatched to the socket at both the sender and receiver 2317 side. This notification can be read by the recvmsg() system call 2318 (see Section 3.1.3). 2320 Note, if the SCTP stack at the sender side supports bundling, the 2321 first user message may be bundled with the COOKIE ECHO message 2322 [RFC4960]. 2324 When the SCTP stack sets up a new association implicitly, the 2325 SCTP_INIT type ancillary data may also be passed along (see 2326 Section 5.2.1 for details of the data structures) to change some 2327 parameters used in setting up new association. 2329 If this information is not present in the sendmsg() call, or if the 2330 implicit association setup is triggered by a sendto() call, the 2331 default association initialization parameters will be used. These 2332 default association parameters may be set with respective 2333 setsockopt() calls or be left to the system defaults. 2335 Implicit association setup cannot be initiated by send() calls. 2337 7. Socket Options 2339 The following sub-section describes various SCTP level socket options 2340 that are common to both styles. SCTP associations can be multi- 2341 homed. Therefore, certain option parameters include a 2342 sockaddr_storage structure to select which peer address the option 2343 should be applied to. 2345 For the one-to-many style sockets, an sctp_assoc_t (association ID) 2346 parameter is used to identify the association instance that the 2347 operation affects. So it must be set when using this style. 2349 For the one-to-one style sockets and branched off one-to-many style 2350 sockets (see Section 8.2) this association ID parameter is ignored. 2352 Note that socket or IP level options are set or retrieved per socket. 2353 This means that for one-to-many style sockets, the options will be 2354 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2355 association ID) belonging to the socket. For one-to-one style, these 2356 options will be applied to all peer addresses of the association 2357 controlled by the socket. Applications should be careful in setting 2358 those options. 2360 For some IP stacks getsockopt() is read-only; so a new interface will 2361 be needed when information must be passed both into and out of the 2362 SCTP stack. The syntax for sctp_opt_info() is 2364 int sctp_opt_info(int sd, 2365 sctp_assoc_t id, 2366 int opt, 2367 void *arg, 2368 socklen_t *size); 2370 The sctp_opt_info() call is a replacement for getsockopt() only and 2371 will not set any options associated with the specified socket. A 2372 setsockopt() must be used to set any writeable option. 2374 For one-to-many style sockets, id specifies the association to query. 2375 For one-to-one style sockets, id is ignored. For one-to-many 2376 sockets, any association identifier in the structure provided as arg 2377 is ignored and id takes precedence. 2379 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used here. 2380 Using them will result in an error (returning -1 and errno set to 2381 EINVAL). SCTP_FUTURE_ASSOC can be used to query information for 2382 future associations. 2384 The field opt specifies which SCTP socket option to get. It can get 2385 any socket option currently supported that requests information 2386 (either read/write options or read only) such as: 2387 SCTP_RTOINFO 2388 SCTP_ASSOCINFO 2389 SCTP_DEFAULT_SEND_PARAM 2390 SCTP_GET_PEER_ADDR_INFO 2391 SCTP_PRIMARY_ADDR 2392 SCTP_PEER_ADDR_PARAMS 2393 SCTP_STATUS 2394 SCTP_CONTEXT 2395 SCTP_AUTH_ACTIVE_KEY 2396 SCTP_PEER_AUTH_CHUNKS 2397 SCTP_LOCAL_AUTH_CHUNKS 2399 The arg field is an option-specific structure buffer provided by the 2400 caller. See Section 8.5 subsections for more information on these 2401 options and option-specific structures. 2403 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2404 sets errno to the appropriate error code. 2406 All options that support specific settings on an association by 2407 filling in either an association id variable or a sockaddr_storage 2408 should also support the setting of the same value for the entire 2409 endpoint (i.e. future associations). To accomplish this the 2410 following logic is used when setting one of these options: 2411 o If an address is specified via a sockaddr_storage that is included 2412 in the structure, the address is used to lookup the association 2413 and the settings are applied to the specific address (if 2414 appropriate) or to the entire association. 2415 o If an association identification is filled in but not a 2416 sockaddr_storage (if present), the association is found using the 2417 association identification and the settings should be applied to 2418 the specified association (since a specific address is not 2419 specified). Note this also applies to options that hold an 2420 association identification in their structure but do not have a 2421 sockaddr_storage field. 2422 o If neither the sockaddr_storage nor association identification is 2423 set, i.e. the sockaddr_storage is set to all 0 (INADDR_ANY) and 2424 the association identification is SCTP_FUTURE_ASSOC, the settings 2425 are a default and to be applied to the endpoint. 2427 7.1. Read / Write Options 2429 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2431 The protocol parameters used to initialize and limit the 2432 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2433 information on how these parameters are used in RTO calculation. 2435 The following structure is used to access and modify these 2436 parameters: 2438 struct sctp_rtoinfo { 2439 sctp_assoc_t srto_assoc_id; 2440 uint32_t srto_initial; 2441 uint32_t srto_max; 2442 uint32_t srto_min; 2443 }; 2445 srto_initial: This contains the initial RTO value. 2446 srto_max and srto_min: These contain the maximum and minimum bounds 2447 for all RTOs. 2448 srto_assoc_id: This parameter is ignored for one-to-one style 2449 sockets. For one-to-many style sockets the application may fill 2450 in an association identification or SCTP_FUTURE_ASSOC. It is an 2451 error to use SCTP_{CURRENT|ALL}_ASSOC in srto_asssoc_id. 2453 All times are given in milliseconds. A value of 0, when modifying 2454 the parameters, indicates that the current value should not be 2455 changed. 2457 To access or modify these parameters, the application should call 2458 getsockopt() or setsockopt() respectively with the option name 2459 SCTP_RTOINFO. 2461 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2463 This option is used to both examine and set various association and 2464 endpoint parameters. See [RFC4960] for more information on how this 2465 parameter is used. 2467 The following structure is used to access and modify these 2468 parameters: 2470 struct sctp_assocparams { 2471 sctp_assoc_t sasoc_assoc_id; 2472 uint16_t sasoc_asocmaxrxt; 2473 uint16_t sasoc_number_peer_destinations; 2474 uint32_t sasoc_peer_rwnd; 2475 uint32_t sasoc_local_rwnd; 2476 uint32_t sasoc_cookie_life; 2477 }; 2479 sasoc_assoc_id: This parameter is ignored for one-to-one style 2480 sockets. For one-to-many style sockets the application may fill 2481 in an association identification or SCTP_FUTURE_ASSOC. It is an 2482 error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_asssoc_id. 2483 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2484 to make for the association. 2485 sasoc_number_peer_destinations: This is the number of destination 2486 addresses that the peer has. 2487 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2488 (reported in the last SACK) minus any outstanding data (i.e. data 2489 in flight). 2490 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2491 the peer. 2492 sasoc_cookie_life: This is the association's cookie life value used 2493 when issuing cookies. 2495 The values of the sasoc_peer_rwnd is meaningless when examining 2496 endpoint information. 2498 All time values are given in milliseconds. A value of 0, when 2499 modifying the parameters, indicates that the current value should not 2500 be changed. 2502 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2503 on either an endpoint or association basis. The rwnd and destination 2504 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2505 sasoc_local_rwnd) are not settable and any value placed in these is 2506 ignored. 2508 To access or modify these parameters, the application should call 2509 getsockopt() or setsockopt() respectively with the option name 2510 SCTP_ASSOCINFO. 2512 The maximum number of retransmissions before an address is considered 2513 unreachable is also tunable, but is address-specific, so it is 2514 covered in a separate option. If an application attempts to set the 2515 value of the association maximum retransmission parameter to more 2516 than the sum of all maximum retransmission parameters, setsockopt() 2517 may return an error. The reason for this, from [RFC4960] section 2518 8.2: 2520 Note: When configuring the SCTP endpoint, the user should avoid 2521 having the value of 'Association.Max.Retrans' (sasoc_maxrt in this 2522 option) larger than the summation of the 'Path.Max.Retrans' (see 2523 Section 7.1.2 on spp_pathmaxrxt) of all the destination addresses for 2524 the remote endpoint. Otherwise, all the destination addresses may 2525 become inactive while the endpoint still considers the peer endpoint 2526 reachable. 2528 7.1.3. Initialization Parameters (SCTP_INITMSG) 2530 Applications can specify protocol parameters for the default 2531 association initialization. The structure used to access and modify 2532 these parameters is defined in Section 5.2.1. The option name 2533 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2535 Setting initialization parameters is effective only on an unconnected 2536 socket (for one-to-many style sockets only future associations are 2537 affected by the change). With one-to-one style sockets, this option 2538 is inherited by sockets derived from a listening socket. 2540 7.1.4. SO_LINGER 2542 An application can use this option to perform the SCTP ABORT 2543 primitive. This option affects all associations related to the 2544 socket. 2546 The linger option structure is: 2548 struct linger { 2549 int l_onoff; /* option on/off */ 2550 int l_linger; /* linger time */ 2551 }; 2553 To enable the option, set l_onoff to 1. If the l_linger value is set 2554 to 0, calling close() is the same as the ABORT primitive. If the 2555 value is set to a negative value, the setsockopt() call will return 2556 an error. If the value is set to a positive value linger_time, the 2557 close() can be blocked for at most linger_time ms. If the graceful 2558 shutdown phase does not finish during this period, close() will 2559 return but the graceful shutdown phase will continue in the system. 2561 Note, this is a socket level option not an SCTP level option. So 2562 when setting SO_LINGER an application must specify a level of 2563 SOL_SOCKET in the setsockopt() call. 2565 7.1.5. SCTP_NODELAY 2567 Turn on/off any Nagle-like algorithm. This means that packets are 2568 generally sent as soon as possible and no unnecessary delays are 2569 introduced, at the cost of more packets in the network. Expects an 2570 integer boolean flag. Turning this option on disables any Nagle-like 2571 algorithm. 2573 7.1.6. SO_RCVBUF 2575 Sets the receive buffer size in octets. For SCTP one-to-one style 2576 sockets, this controls the receiver window size. For one-to-many 2577 style sockets the meaning is implementation dependent. It might 2578 control the receive buffer for each association bound to the socket 2579 descriptor or it might control the receive buffer for the whole 2580 socket. The call expects an integer. 2582 7.1.7. SO_SNDBUF 2584 Sets the send buffer size. For SCTP one-to-one style sockets, this 2585 controls the amount of data SCTP may have waiting in internal buffers 2586 to be sent. This option therefore bounds the maximum size of data 2587 that can be sent in a single send call. For one-to-many style 2588 sockets, the effect is the same, except that it applies to one or all 2589 associations (see Section 3.3) bound to the socket descriptor used in 2590 the setsockopt() or getsockopt() call. The option applies to each 2591 association's window size separately. The call expects an integer. 2593 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 2595 This socket option is applicable to the one-to-many style socket 2596 only. When set it will cause associations that are idle for more 2597 than the specified number of seconds to automatically close using the 2598 graceful shutdown procedure. An association being idle is defined as 2599 an association that has not sent or received user data. The special 2600 value of '0' indicates that no automatic close of any association 2601 should be performed, this is the default value. The option expects 2602 an integer defining the number of seconds of idle time before an 2603 association is closed. 2605 An application using this option should enable receiving the 2606 association change notification. This is the only mechanism an 2607 application is informed about the closing of an association. After 2608 an association is closed, the association ID assigned to it can be 2609 reused. An application should be aware of this to avoid the possible 2610 problem of sending data to an incorrect peer endpoint. 2612 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 2614 Requests that the local SCTP stack uses the enclosed peer address as 2615 the association's primary. The enclosed address must be one of the 2616 association peer's addresses. 2618 The following structure is used to make a set peer primary request: 2620 struct sctp_setprim { 2621 sctp_assoc_t ssp_assoc_id; 2622 struct sockaddr_storage ssp_addr; 2623 }; 2625 ssp_addr: The address to set as primary. 2626 ssp_assoc_id: This parameter is ignored for one-to-one style 2627 sockets. For one-to-many style sockets it identifies the 2628 association for this request. Note that the special sctp_assoc_t 2629 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 2631 7.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2633 Requests that the local endpoint set the specified Adaptation Layer 2634 Indication parameter for all future INIT and INIT-ACK exchanges. 2636 The following structure is used to access and modify this parameter: 2638 struct sctp_setadaptation { 2639 uint32_t ssb_adaptation_ind; 2640 }; 2642 ssb_adaptation_ind: The adaptation layer indicator that will be 2643 included in any outgoing Adaptation Layer Indication parameter. 2645 7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 2647 This option is a on/off flag and is passed as an integer where a non- 2648 zero is on and a zero is off. If enabled no SCTP message 2649 fragmentation will be performed. Instead, if a message being sent 2650 exceeds the current PMTU size, the message will not be sent and 2651 instead an error will be indicated to the user. 2653 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2655 Applications can enable or disable heartbeats for any peer address of 2656 an association, modify an address's heartbeat interval, force a 2657 heartbeat to be sent immediately, and adjust the address's maximum 2658 number of retransmissions sent before an address is considered 2659 unreachable. 2661 The following structure is used to access and modify an address's 2662 parameters: 2664 struct sctp_paddrparams { 2665 sctp_assoc_t spp_assoc_id; 2666 struct sockaddr_storage spp_address; 2667 uint32_t spp_hbinterval; 2668 uint16_t spp_pathmaxrxt; 2669 uint32_t spp_pathmtu; 2670 uint32_t spp_flags; 2671 uint32_t spp_ipv6_flowlabel; 2672 uint8_t spp_ipv4_tos; 2673 }; 2675 spp_assoc_id: This parameter is ignored for one-to-one style 2676 sockets. For one-to-many style sockets it identifies the 2677 association for this query. Note that the predefined constants 2678 are not allowed. 2679 spp_address: This specifies which address is of interest. If a 2680 wildcard address is provided it applies to all current and future 2681 paths. 2682 spp_hbinterval: This contains the value of the heartbeat interval, 2683 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 2684 spp_flag is set to SPP_HB_ENABLE the value of this field is 2685 ignored. Note also that a value of zero indicates the current 2686 setting should be left unchanged. To set an actual value of zero 2687 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 2688 it is set to 0, it does not mean that SCTP will continuously send 2689 out heartbeat since the actual interval also includes a the 2690 current RTO and jitter (see Section 8.3 in [RFC4960]). 2691 spp_pathmaxrxt: This contains the maximum number of retransmissions 2692 before this address shall be considered unreachable. Note that a 2693 value of zero indicates the current setting should be left 2694 unchanged. 2695 spp_ipv6_flowlabel: This field is used in conjunction with the 2696 SPP_IPV6_FLOWLABEL flag. This setting has precedence over any 2697 IPv6 layer setting. 2698 spp_ipv4_tos: This field is used in conjunction with the 2699 SPP_IPV4_TOS flag. This setting has precedence over any IPv4 2700 layer setting. 2701 spp_flags: These flags are used to control various features on an 2702 association. The flag field is a bit mask which may contain zero 2703 or more of the following options: 2704 SPP_HB_ENABLE: Enable heartbeats on the specified address. 2706 SPP_HB_DISABLE: Disable heartbeats on the specified address. 2707 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 2708 exclusive, only one of these two should be specified. Enabling 2709 both fields will have undetermined results. 2710 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 2711 immediately. This must not be used in conjunction with a 2712 wildcard address. 2713 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 2714 is to be set to the value of 0 milliseconds. 2715 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 2716 specified address. 2717 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 2718 the specified address. Note that if the address field is empty 2719 then all addresses on the association are affected. Note also 2720 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2721 exclusive. Enabling both will have undetermined results. 2722 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 2723 IPV6 flowlabel value. The value is obtained in the 2724 spp_ipv6_flowlabel field. 2726 Upon retrieval, this flag will be set to indicate that the 2727 spp_ipv6_flowlabel field has a valid value returned. If a 2728 specific destination address is set (in the spp_address field), 2729 then the value returned is that of the address. If just an 2730 association is specified (and no address), then the 2731 association's default flowlabel is returned. If neither an 2732 association nor a destination is specified, then the socket's 2733 default flowlabel is returned. For non IPv6 sockets, this flag 2734 will be left cleared. 2735 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 2736 TOS value associated with either the association or a specific 2737 address. The value is obtained in the spp_ipv4_tos field. 2739 Upon retrieval, this flag will be set to indicate that the 2740 spp_ipv4_tos field has a valid value returned. If a specific 2741 destination address is set when called (in the spp_address 2742 field) then that specific destination address' TOS value is 2743 returned. If just an association is specified then the 2744 association default TOS is returned. If neither an association 2745 nor an destination is specified, then the sockets default TOS 2746 is returned. 2748 To read or modify these parameters, the application should call 2749 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2751 7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 2753 Please note that this options is deprecated. Section 7.1.31 should 2754 be used instead. 2756 Applications that wish to use the sendto() system call may wish to 2757 specify a default set of parameters that would normally be supplied 2758 through the inclusion of ancillary data. This socket option allows 2759 such an application to set the default sctp_sndrcvinfo structure. 2760 The application that wishes to use this socket option simply passes 2761 the sctp_sndrcvinfo structure defined in Section 5.2.2 to this call. 2762 The input parameters accepted by this call include sinfo_stream, 2763 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy and 2764 sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2765 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2766 specifies the association to apply the parameters to. In a one-to- 2767 many style sockets any of the predefined constants are also allowed 2768 in this field. The field is ignored on the one-to-one style. 2770 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) 2772 This socket option is used to specify various notifications and 2773 ancillary data the user wishes to receive. Please see Section 7.4 2774 for a full description of this option and its usage. Note that this 2775 option is considered deprecated and present for backward 2776 compatibility. New applications should use the SCTP_SET_EVENT 2777 option. See Section 7.4 for a full description of that option as 2778 well. 2780 7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2782 This socket option is a boolean flag which turns on or off the 2783 mapping of IPv4 addresses. If this option is turned on and the 2784 socket is type PF_INET6, then IPv4 addresses will be mapped to V6 2785 representation. If this option is turned off, then no mapping will 2786 be done of V4 addresses and a user will receive both PF_INET6 and 2787 PF_INET type addresses on the socket. See [RFC3542] for more details 2788 on mapped V6 addresses. 2790 By default this option is turned off and expects an integer to be 2791 passed where non-zero turns on the option and zero turns off the 2792 option. 2794 7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 2796 This option will get or set the maximum size to put in any outgoing 2797 SCTP DATA chunk. If a message is larger than this size it will be 2798 fragmented by SCTP into the specified size. Note that the underlying 2799 SCTP implementation may fragment into smaller sized chunks when the 2800 PMTU of the underlying association is smaller than the value set by 2801 the user. The default value for this option is '0' which indicates 2802 the user is not limiting fragmentation and only the PMTU will affect 2803 SCTP's choice of DATA chunk size. Note also that values set larger 2804 than the maximum size of an IP datagram will effectively let SCTP 2805 control fragmentation (i.e. the same as setting this option to 0). 2807 The following structure is used to access and modify this parameter: 2809 struct sctp_assoc_value { 2810 sctp_assoc_t assoc_id; 2811 uint32_t assoc_value; 2812 }; 2814 assoc_id: This parameter is ignored for one-to-one style sockets. 2815 For one-to-many style sockets this parameter indicates which 2816 association the user is performing an action upon. It is an error 2817 to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_asssoc_id. 2818 assoc_value: This parameter specifies the maximum size in bytes. 2820 7.1.17. Get or Set the List of Supported HMAC Identifiers 2821 (SCTP_HMAC_IDENT) 2823 This option gets or sets the list of HMAC algorithms that the local 2824 endpoint requires the peer to use. 2826 The following structure is used to get or set these identifiers: 2828 struct sctp_hmacalgo { 2829 uint32_t shmac_number_of_idents; 2830 uint16_t shmac_idents[]; 2831 }; 2833 shmac_number_of_idents: This field gives the number of elements 2834 present in the array shmac_idents. 2835 shmac_idents: This parameter contains an array of HMAC identifiers 2836 that the local endpoint is requesting the peer to use, in priority 2837 order. The following identifiers are valid: 2838 * SCTP_AUTH_HMAC_ID_SHA1 2839 * SCTP_AUTH_HMAC_ID_SHA256 2841 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 2842 may include any of the other values in its preferred order (lowest 2843 list position has the highest preference in algorithm selection). 2844 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 2845 of an unknown HMAC identifier (including optional identifiers unknown 2846 to the implementation) will cause the set option to fail and return 2847 an error. 2849 7.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 2851 This option will get or set the active shared key to be used to build 2852 the association shared key. 2854 The following structure is used to access and modify these 2855 parameters: 2857 struct sctp_authkeyid { 2858 sctp_assoc_t scact_assoc_id; 2859 uint16_t scact_keynumber; 2860 }; 2862 scact_assoc_id: This parameter sets the active key of the specified 2863 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 2864 used. For one-to-one sockets, this parameter is ignored. Note, 2865 however, that this option will set the active key on the 2866 association if the socket is connected, otherwise this will set 2867 the default active key for the endpoint. 2868 scact_keynumber: This parameter is the shared key identifier which 2869 the application is requesting to become the active shared key to 2870 be used for sending authenticated chunks. The key identifier must 2871 correspond to an existing shared key. Note that shared key 2872 identifier '0' defaults to a null key. 2874 When used with setsockopt() the SCTP implementation must use the 2875 indicated shared key identifier for all messages being given to an 2876 SCTP implementation via a send call after the setsockopt() call until 2877 changed again. Therefore, the SCTP implementation must not bundle 2878 user messages which should be authenticated using different shared 2879 key identifiers. 2881 Initially the key with key identifier 0 is the active key. 2883 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 2885 This option will affect the way delayed acks are performed. This 2886 option allows the application to get or set the delayed ack time, in 2887 milliseconds. It also allows changing the delayed ack frequency. 2888 Changing the frequency to 1 disables the delayed sack algorithm. 2889 Note that if sack_delay or sack_freq are 0 when setting this option, 2890 the current values will remain unchanged. 2892 The following structure is used to access and modify these 2893 parameters: 2895 struct sctp_sack_info { 2896 sctp_assoc_t sack_assoc_id; 2897 uint32_t sack_delay; 2898 uint32_t sack_freq; 2899 }; 2901 sack_assoc_id: This parameter is ignored for one-to-one style 2902 sockets. For one-to-many style sockets this parameter indicates 2903 which association the user is performing an action upon. The 2904 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 2905 sack_delay: This parameter contains the number of milliseconds that 2906 the user is requesting the delayed ACK timer to be set to. Note 2907 that this value is defined in the standard to be between 200 and 2908 500 milliseconds. 2909 sack_freq: This parameter contains the number of packets that must 2910 be received before a sack is sent without waiting for the delay 2911 timer to expire. The default value is 2, setting this value to 1 2912 will disable the delayed sack algorithm. 2914 7.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 2916 Fragmented interleave controls how the presentation of messages 2917 occurs for the message receiver. There are three levels of fragment 2918 interleave defined. Two of the levels affect the one-to-one model, 2919 while the one-to-many model is affected by all three levels. 2921 This option takes an integer value. It can be set to a value of 0, 1 2922 or 2. Attempting to set this level to other values will return an 2923 error. 2925 Setting the three levels provides the following receiver 2926 interactions: 2928 level 0: Prevents the interleaving of any messages. This means that 2929 when a partial delivery begins, no other messages will be received 2930 except the message being partially delivered. If another message 2931 arrives on a different stream (or association) that could be 2932 delivered, it will be blocked waiting for the user to read all of 2933 the partially delivered message. 2934 level 1: Allows interleaving of messages that are from different 2935 associations. For the one-to-one model, level 0 and level 1 thus 2936 have the same meaning since a one-to-one socket always receives 2937 messages from the same association. Note that setting the one-to- 2938 many model to this level may cause multiple partial deliveries 2939 from different associations but for any given association, only 2940 one message will be delivered until all parts of a message have 2941 been delivered. This means that one large message, being read 2942 with an association identification of "X", will block other 2943 messages from association "X" from being delivered. 2944 level 2: Allows complete interleaving of messages. This level 2945 requires that the sender carefully observes not only the peer 2946 association identification (or address) but must also pay careful 2947 attention to the stream number. With this option enabled a 2948 partially delivered message may begin being delivered for 2949 association "X" stream "Y" and the next subsequent receive may 2950 return a message from association "X" stream "Z". Note that no 2951 other messages would be delivered for association "X" stream "Y" 2952 until all of stream "Y"'s partially delivered message was read. 2953 Note that this option also affects the one-to-one model. Also 2954 note that for the one-to-many model not only may another streams 2955 message from the same association be delivered from the next 2956 receive, some other associations message may be delivered upon the 2957 next receive. 2959 An implementation should default the one-to-many model to level 1. 2960 The reason for this is that otherwise it is possible that a peer 2961 could begin sending a partial message and thus block all other peers 2962 from sending data. However a setting of level 2 requires the 2963 application to not only be aware of the association (via the 2964 association id or peer's address) but also the stream number. The 2965 stream number is not present unless the user has subscribed to the 2966 sctp_data_io_events (see Section 7.4). This is also why we recommend 2967 that the one-to-one model be defaulted to level 0 (level 1 for the 2968 one-to-one model has no effect). Note that an implementation should 2969 return an error if an application attempts to set the level to 2 and 2970 has not subscribed to the sctp_data_io_events. 2972 For applications that have subscribed to events those events appear 2973 in the normal socket buffer data stream. This means that unless the 2974 user has set the fragmentation interleave level to 0, notifications 2975 may also be interleaved with partially delivered messages. 2977 7.1.21. Set or Get the SCTP Partial Delivery Point 2978 (SCTP_PARTIAL_DELIVERY_POINT) 2980 This option will set or get the SCTP partial delivery point. This 2981 point is the size of a message where the partial delivery API will be 2982 invoked to help free up rwnd space for the peer. Setting this to a 2983 lower value will cause partial deliveries to happen more often. The 2984 call's argument is an integer that sets or gets the partial delivery 2985 point in bytes. Note also that the call will fail if the user 2986 attempts to set this value larger than the socket receive buffer 2987 size. 2989 Note that any single message having a length smaller than or equal to 2990 the SCTP partial delivery point will be delivered in one single read 2991 call as long as the user provided buffer is large enough to hold the 2992 message. 2994 7.1.22. Set or Get the Use of Extended Receive Info 2995 (SCTP_USE_EXT_RCVINFO) 2997 This option will enable or disable the use of the extended version of 2998 the sctp_sndrcvinfo structure. If this option is disabled, then the 2999 normal sctp_sndrcvinfo structure is returned in all receive message 3000 calls. If this option is enabled then the sctp_extrcvinfo structure 3001 is returned in all receive message calls. This option is present for 3002 compatibility with older applications and is deprecated. Future 3003 applications should use SCTP_NXTINFO to retrieve this same 3004 information via ancillary data. 3006 Note that the sctp_extrcvinfo structure is never used in any send 3007 call. 3009 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3011 This option will enable or disable the use of the automatic 3012 generation of ASCONF chunks to add and delete addresses to an 3013 existing association. Note that this option has two caveats namely: 3014 a) it only affects sockets that are bound to all addresses on the 3015 machine, and b) the system administrator may have an overriding 3016 control that turns the ASCONF feature off no matter what setting the 3017 socket option may have. 3019 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3021 This option will allow a user to change the maximum burst of packets 3022 that can be emitted by this association. Note that the default value 3023 is 4, and some implementations may restrict this setting so that it 3024 can only be lowered. 3026 To set or get this option the user fills in the following structure: 3028 struct sctp_assoc_value { 3029 sctp_assoc_t assoc_id; 3030 uint32_t assoc_value; 3031 }; 3033 assoc_id: This parameter is ignored for one-to-one style sockets. 3034 For one-to-many style sockets this parameter indicates which 3035 association the user is performing an action upon. The special 3036 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3038 assoc_value: This parameter contains the maximum burst. 3040 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3042 The context field in the sctp_sndrcvinfo structure is normally only 3043 used when a failed message is retrieved holding the value that was 3044 sent down on the actual send call. This option allows the setting of 3045 a default context on an association basis that will be received on 3046 reading messages from the peer. This is especially helpful in the 3047 one-to-many model for an application to keep some reference to an 3048 internal state machine that is processing messages on the 3049 association. Note that the setting of this value only affects 3050 received messages from the peer and does not affect the value that is 3051 saved with outbound messages. 3053 To set or get this option the user fills in the following structure: 3055 struct sctp_assoc_value { 3056 sctp_assoc_t assoc_id; 3057 uint32_t assoc_value; 3058 }; 3060 assoc_id: This parameter is ignored for one-to-one style sockets. 3061 For one-to-many style sockets this parameter indicates which 3062 association the user is performing an action upon. The special 3063 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3064 assoc_value: This parameter contains the context. 3066 7.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3068 This boolean flag is used to enable or disable explicit end of record 3069 (EOR) marking. When this option is enabled, a user may make multiple 3070 send system calls to send a record and must indicate that they are 3071 finished sending a particular record by including the SCTP_EOR flag. 3072 If this boolean flag is disabled then each individual send system 3073 call is considered to have an SCTP_EOR indicator set on it implicitly 3074 without the user having to explicitly add this flag. 3076 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3078 This option only supports one-to-one style SCTP sockets. If used on 3079 a one-to-many style SCTP socket an error is indicated. 3081 This setsockopt() call must not be used after calling bind() or 3082 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3083 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3084 SCTP sockets bound to the same port must have set the 3085 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3086 having set the SCTP_REUSE_PORT option will fail if there are other 3087 sockets bound to the same port. At most one socket being bound to 3088 the same port may be listening. 3090 It should be noted that the behavior of the socket level socket 3091 option to reuse ports and/or addresses for SCTP sockets is 3092 unspecified. 3094 7.1.28. Set Notification Event (SCTP_EVENT) 3096 This socket option is used to set a specific notification option. 3097 Please see Section 7.4 for a full description of this option and its 3098 usage. 3100 7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3101 Data (SCTP_RECVRCVINFO) 3103 Setting this option specifies that SCTP_RCVINFO defined in 3104 Section 5.2.5 is returned as ancillary data by recvmsg(). The call 3105 expects an integer. 3107 7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3108 Data (SCTP_RECVNXTINFO) 3110 Setting this option specifies that SCTP_NXTINFO defined in 3111 Section 5.2.6 is returned as ancillary data by recvmsg(). The call 3112 expects an integer. 3114 7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3116 Applications that wish to use the sendto() system call may wish to 3117 specify a default set of parameters that would normally be supplied 3118 through the inclusion of ancillary data. This socket option allows 3119 such an application to set the default sctp_sndrcvinfo structure. 3120 The application that wishes to use this socket option simply passes 3121 the sctp_sndinfo structure defined in Section 5.2.4 to this call. 3122 The input parameters accepted by this call include snd_sid, 3123 snd_flags, snd_ppid, snd_context. The snd_flags is composed of a 3124 bitwise OR of SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The 3125 snd_assoc_id field specifies the association to apply the parameters 3126 to. In a one-to-many style sockets any of the predefined constants 3127 are also allowed in this field. The field is ignored on the one-to- 3128 one style. 3130 7.2. Read-Only Options 3132 The options defined in this subsection are read-only. Using this 3133 option in a setsockopt() call will result in an error indicating 3134 EOPNOTSUPP. 3136 7.2.1. Association Status (SCTP_STATUS) 3138 Applications can retrieve current status information about an 3139 association, including association state, peer receiver window size, 3140 number of unacked data chunks, and number of data chunks pending 3141 receipt. This information is read-only. 3143 The following structure is used to access this information: 3145 struct sctp_status { 3146 sctp_assoc_t sstat_assoc_id; 3147 int32_t sstat_state; 3148 uint32_t sstat_rwnd; 3149 uint16_t sstat_unackdata; 3150 uint16_t sstat_penddata; 3151 uint16_t sstat_instrms; 3152 uint16_t sstat_outstrms; 3153 uint32_t sstat_fragmentation_point; 3154 struct sctp_paddrinfo sstat_primary; 3155 }; 3157 sstat_assoc_id: This parameter is ignored for one-to-one style 3158 sockets. For one-to-many style sockets it holds the identifier 3159 for the association. All notifications for a given association 3160 have the same association identifier. The special SCTP_{FUTURE| 3161 CURRENT|ALL}_ASSOC cannot be used. 3162 sstat_state: This contains the association's current state one of 3163 the following values: 3164 * SCTP_CLOSED 3165 * SCTP_BOUND 3166 * SCTP_LISTEN 3167 * SCTP_COOKIE_WAIT 3168 * SCTP_COOKIE_ECHOED 3169 * SCTP_ESTABLISHED 3170 * SCTP_SHUTDOWN_PENDING 3171 * SCTP_SHUTDOWN_SENT 3172 * SCTP_SHUTDOWN_RECEIVED 3173 * SCTP_SHUTDOWN_ACK_SENT 3174 sstat_rwnd: This contains the association peer's current receiver 3175 window size. 3176 sstat_unackdata: This is the number of unacked data chunks. 3177 sstat_penddata: This is the number of data chunks pending receipt. 3179 sstat_instrms: The number of streams that the peer will be using 3180 outbound. 3181 sstat_outstrms: The number of streams that the endpoint is allowed 3182 to use outbound. 3183 sstat_fragmentation_point: The size at which SCTP fragmentation will 3184 occur. 3185 sstat_primary: This is information on the current primary peer 3186 address. 3188 To access these status values, the application calls getsockopt() 3189 with the option name SCTP_STATUS. 3191 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3193 Applications can retrieve information about a specific peer address 3194 of an association, including its reachability state, congestion 3195 window, and retransmission timer values. This information is read- 3196 only. 3198 The following structure is used to access this information: 3200 struct sctp_paddrinfo { 3201 sctp_assoc_t spinfo_assoc_id; 3202 struct sockaddr_storage spinfo_address; 3203 int32_t spinfo_state; 3204 uint32_t spinfo_cwnd; 3205 uint32_t spinfo_srtt; 3206 uint32_t spinfo_rto; 3207 uint32_t spinfo_mtu; 3208 }; 3210 spinfo_assoc_id: This parameter is ignored for one-to-one style 3211 sockets. For one-to-many style sockets the following applies: 3212 This field may be filled by the application, if so, this field 3213 will have priority in looking up the association using the address 3214 specified in spinfo_address. Note that if the address does not 3215 belong to the association specified then this call will fail. If 3216 the application does not fill in the spinfo_assoc_id, then the 3217 address will be used to lookup the association and on return this 3218 field will have the valid association id. In other words, this 3219 call can be used to translate an address into an association id. 3220 Note that the predefined constants are not allowed on this option. 3221 spinfo_address: This is filled by the application, and contains the 3222 peer address of interest. 3224 spinfo_state: This contains the peer address' state (either 3225 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 3226 SCTP_UNCONFIRMED). 3227 spinfo_cwnd: This contains the peer address' current congestion 3228 window. 3229 spinfo_srtt: This contains the peer address' current smoothed round- 3230 trip time calculation in milliseconds. 3231 spinfo_rto: This contains the peer address' current retransmission 3232 timeout value in milliseconds. 3233 spinfo_mtu: The current P-MTU of this address. 3235 7.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3236 (SCTP_PEER_AUTH_CHUNKS) 3238 This option gets a list of chunk types (see [RFC4960] for a specified 3239 association that the peer requires to be received authenticated only. 3241 The following structure is used to access these parameters: 3243 struct sctp_authchunks { 3244 sctp_assoc_t gauth_assoc_id; 3245 uint32_t gauth_number_of_chunks 3246 uint8_t gauth_chunks[]; 3247 }; 3249 gauth_assoc_id: This parameter indicates for which association the 3250 user is requesting the list of peer authenticated chunks. For 3251 one-to-one sockets, this parameter is ignored. Note that the 3252 predefined constants are not allowed with this option. 3253 gauth_number_of_chunks: This parameter gives the number of elements 3254 in the array gauth_chunks. 3255 gauth_chunks: This parameter contains an array of chunk types that 3256 the peer is requesting to be authenticated. 3258 7.2.4. Get the List of Chunks the Local Endpoint Requires to be 3259 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3261 This option gets a list of chunk types (see [RFC4960]) for a 3262 specified association that the local endpoint requires to be received 3263 authenticated only. 3265 The following structure is used to access these parameters: 3267 struct sctp_authchunks { 3268 sctp_assoc_t gauth_assoc_id; 3269 uint32_t gauth_number_of_chunks; 3270 uint8_t gauth_chunks[]; 3271 }; 3272 gauth_assoc_id: This parameter indicates for which association the 3273 user is requesting the list of local authenticated chunks. For 3274 one-to-one sockets, this parameter is ignored. 3275 gauth_number_of_chunks: This parameter gives the number of elements 3276 in the array gauth_chunks. 3277 gauth_chunks: This parameter contains an array of chunk types that 3278 the local endpoint is requesting to be authenticated. 3280 7.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3282 This option gets the current number of associations that are attached 3283 to a one-to-many style socket. The option value is an uint32_t. 3284 Note that this number is only a snap shot. This means that the 3285 number of associations may have changed when the caller gets back the 3286 option result. 3288 7.2.6. Get the Current Identifiers of Associations 3289 (SCTP_GET_ASSOC_ID_LIST) 3291 This option gets the current list of SCTP association identifiers of 3292 the SCTP associations handled by a one-to-many style socket. 3294 The option value has the structure 3296 struct sctp_assoc_ids { 3297 uint32_t gaids_number_of_ids; 3298 sctp_assoc_t gaids_assoc_id[]; 3299 }; 3301 The caller must provide a large enough buffer to hold all association 3302 identifiers. If the buffer is too small, an error must be returned. 3303 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3304 idea how large the buffer has to be. gaids_number_of_ids gives the 3305 number of elements in the array gaids_assoc_id. Note also that the 3306 some or all of sctp_assoc_t returned in the array may become invalid 3307 by the time the caller gets back the result. 3309 7.3. Write-Only Options 3311 The options defined in this subsection are write-only. Using this 3312 option in a getsockopt() or sctp_opt_info() call will result in an 3313 error indicating EOPNOTSUPP. 3315 7.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3317 Requests that the peer marks the enclosed address as the association 3318 primary (see [RFC5061]). The enclosed address must be one of the 3319 association's locally bound addresses. 3321 The following structure is used to make a set peer primary request: 3323 struct sctp_setpeerprim { 3324 sctp_assoc_t sspp_assoc_id; 3325 struct sockaddr_storage sspp_addr; 3326 }; 3328 sspp_addr: The address to set as primary. 3329 sspp_assoc_id: This parameter is ignored for one-to-one style 3330 sockets. For one-to-many style sockets it identifies the 3331 association for this request. Note that the predefined constants 3332 are not allowed on this option. 3334 7.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3336 This set option adds a chunk type that the user is requesting to be 3337 received only in an authenticated way. Changes to the list of chunks 3338 will only affect future associations on the socket. 3340 The following structure is used to add a chunk: 3342 struct sctp_authchunk { 3343 uint8_t sauth_chunk; 3344 }; 3346 sauth_chunk: This parameter contains a chunk type that the user is 3347 requesting to be authenticated. 3349 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3350 chunks must not be used. If they are used, an error must be 3351 returned. The usage of this option enables SCTP AUTH in cases where 3352 it is not required by other means (for example the use of dynamic 3353 address reconfiguration). 3355 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3357 This option will set a shared secret key that is used to build an 3358 association shared key. 3360 The following structure is used to access and modify these 3361 parameters: 3363 struct sctp_authkey { 3364 sctp_assoc_t sca_assoc_id; 3365 uint16_t sca_keynumber; 3366 uint16_t sca_keylength; 3367 uint8_t sca_key[]; 3368 }; 3369 sca_assoc_id: This parameter indicates what association the shared 3370 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3371 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3372 ignored. Note, however, that this option will set a key on the 3373 association if the socket is connected, otherwise this will set a 3374 key on the endpoint. 3375 sca_keynumber: This parameter is the shared key identifier by which 3376 the application will refer to this shared key. If a key of the 3377 specified index already exists, then this new key will replace the 3378 old existing key. Note that shared key identifier '0' defaults to 3379 a null key. 3380 sca_keylength: This parameter is the length of the array sca_key. 3381 sca_key: This parameter contains an array of bytes that is to be 3382 used by the endpoint (or association) as the shared secret key. 3383 Note, if the length of this field is zero, a null key is set. 3385 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3387 This set option indicates that the application will not send user 3388 messages anymore using the indicated key identifier. 3390 struct sctp_authkeyid { 3391 sctp_assoc_t scact_assoc_id; 3392 uint16_t scact_keynumber; 3393 }; 3395 scact_assoc_id: This parameter indicates which association the 3396 shared key identifier is being deleted from. The special 3397 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3398 sockets, this parameter is ignored. Note, however, that this 3399 option will deactivate the key from the association if the socket 3400 is connected, otherwise this will deactivate the key from the 3401 endpoint. 3402 scact_keynumber: This parameter is the shared key identifier which 3403 the application is requesting to be deactivated. The key 3404 identifier must correspond to an existing shared key. Note if 3405 this parameter is zero, use of the null key identifier '0' is 3406 deactivated on the endpoint and/or association. 3408 The currently active key cannot be deactivated. 3410 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3412 This set option will delete a shared secret key which has been 3413 deactivated of an SCTP association. 3415 struct sctp_authkeyid { 3416 sctp_assoc_t scact_assoc_id; 3417 uint16_t scact_keynumber; 3418 }; 3420 scact_assoc_id: This parameter indicates which association the 3421 shared key identifier is being deleted from. The special 3422 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3423 sockets, this parameter is ignored. Note, however, that this 3424 option will delete the key from the association if the socket is 3425 connected, otherwise this will delete the key from the endpoint. 3426 scact_keynumber: This parameter is the shared key identifier which 3427 the application is requesting to be deleted. The key identifier 3428 must correspond to an existing shared key and must not be in use 3429 for any packet being sent by the SCTP implementation. This means 3430 in particular, that it must be deactivated first. Note if this 3431 parameter is zero, use of the null key identifier '0' is deleted 3432 from the endpoint and/or association. 3434 Only deactivated keys that are no longer used by the association can 3435 be deleted. 3437 7.4. Ancillary Data and Notification Interest Options 3439 Applications can receive per-message ancillary information and 3440 notifications of certain SCTP events with recvmsg(). 3442 The following optional information is available to the application: 3443 SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3444 stream number, TSN, SSN, etc. described in Section 5.2.2) 3445 SCTP_ASSOC_CHANGE (sctp_association_event): described in 3446 Section 5.3.2 3447 SCTP_PEER_ADDR_CHANGE (sctp_address_event): described in 3448 Section 5.3.3 3449 SCTP_SEND_FAILED (sctp_send_failure_event): described in 3450 Section 5.3.5 3451 SCTP_REMOTE_ERROR (sctp_peer_error_event): described in 3452 Section 5.3.4 3453 SCTP_SHUTDOWN_EVENT (sctp_shutdown_event): described in 3454 Section 5.3.6 3455 SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): described 3456 in Section 5.3.8 3457 SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): described 3458 in Section 5.3.7 3460 SCTP_AUTHENTICATION_EVENT (sctp_authentication_event): described in 3461 Section 5.3.9) 3462 SCTP_SENDER_DRY_EVENT (sctp_sender_dry_event): described in 3463 Section 5.3.10 3464 SCTP_NOTIFICATIONS_STOPPED_EVENT (): described in Section 5.3.11 3466 To receive any ancillary data or notifications, first the application 3467 registers its interest by calling the SCTP_EVENTS (deprecated, see 3468 below) setsockopt() with the following structure: 3470 struct sctp_event_subscribe{ 3471 uint8_t sctp_data_io_event; 3472 uint8_t sctp_association_event; 3473 uint8_t sctp_address_event; 3474 uint8_t sctp_send_failure_event; 3475 uint8_t sctp_peer_error_event; 3476 uint8_t sctp_shutdown_event; 3477 uint8_t sctp_partial_delivery_event; 3478 uint8_t sctp_adaptation_layer_event; 3479 uint8_t sctp_authentication_event; 3480 uint8_t sctp_sender_dry_event; 3481 }; 3483 sctp_data_io_event: Setting this flag to 1 will cause the reception 3484 of SCTP_SNDRCV information on a per message basis. The 3485 application will need to use the recvmsg() interface so that it 3486 can receive the event information contained in the msg_control 3487 field. Setting the flag to 0 will disable the reception of the 3488 message control information. 3489 sctp_association_event: Setting this flag to 1 will enable the 3490 reception of association event notifications. Setting the flag to 3491 0 will disable association event notifications. 3492 sctp_address_event: Setting this flag to 1 will enable the reception 3493 of address event notifications. Setting the flag to 0 will 3494 disable address event notifications. 3495 sctp_send_failure_event: Setting this flag to 1 will enable the 3496 reception of send failure event notifications. Setting the flag 3497 to 0 will disable send failure event notifications. 3498 sctp_peer_error_event: Setting this flag to 1 will enable the 3499 reception of peer error event notifications. Setting the flag to 3500 0 will disable peer error event notifications. 3501 sctp_shutdown_event: Setting this flag to 1 will enable the 3502 reception of shutdown event notifications. Setting the flag to 0 3503 will disable shutdown event notifications. 3505 sctp_partial_delivery_event: Setting this flag to 1 will enable the 3506 reception of partial delivery notifications. Setting the flag to 3507 0 will disable partial delivery event notifications. 3508 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 3509 reception of adaptation layer notifications. Setting the flag to 3510 0 will disable adaptation layer event notifications. 3511 sctp_authentication_event: Setting this flag to 1 will enable the 3512 reception of authentication layer notifications. Setting the flag 3513 to 0 will disable authentication layer event notifications. 3514 sctp_sender_dry_event: Setting this flag to 1 will enable the 3515 reception of sender dry notifications. Setting the flag to 0 will 3516 disable sender dry event notifications. 3518 An example where an application would like to receive data io events 3519 and association events but no others would be as follows: 3521 { 3522 struct sctp_event_subscribe events; 3524 memset(&events,0,sizeof(events)); 3526 events.sctp_data_io_event = 1; 3527 events.sctp_association_event = 1; 3529 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 3530 } 3532 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3533 receives ancillary data and notifications for all associations bound 3534 to the file descriptor. For one-to-one style SCTP sockets, the 3535 caller receives ancillary data and notifications only for the single 3536 association bound to the file descriptor. 3538 The SCTP_EVENTS socket option has one issue for future compatibility. 3539 As new features are added the structure (sctp_event_subscribe) must 3540 be expanded. This can cause an application binary interface (ABI) 3541 issue unless an implementation has added padding at the end of the 3542 structure. To avoid this problem, SCTP_EVENTS has been deprecated 3543 and a new option SCTP_EVENT socket option has taken its place. The 3544 option is used with the following structure: 3546 struct sctp_event { 3547 sctp_assoc_t se_assoc_id; 3548 uint16_t se_type; 3549 uint8_t se_on; 3550 }; 3551 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 3552 sockets. For one-to-many style sockets any this field can be a 3553 particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 3554 se_type: The se_type field can be filled with any value that would 3555 show up in the respective sn_type field (in the sctp_tlv structure 3556 of the notification). 3557 se_on: The se_on field is set to 1 to turn on an event and set to 0 3558 to turn off an event. 3560 To use this option the user fills in this structure and then calls 3561 the setsockopt to turn on or off an individual event. The following 3562 is an example use of this option: 3564 { 3565 struct sctp_event event; 3567 memset(&event, 0, sizeof(event)); 3569 event.se_assoc_id = SCTP_FUTURE_ASSOC; 3570 event.se_type = SCTP_SENDER_DRY_EVENT; 3571 event.se_on = 1; 3572 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 3573 } 3575 By default both the one-to-one style and the one-to-many style socket 3576 has all options off. 3578 8. New Functions 3580 Depending on the system, the following interface can be implemented 3581 as a system call or library function. 3583 8.1. sctp_bindx() 3585 This function allows the user to bind a specific subset of addresses 3586 or, if the SCTP extension described in [RFC5061] is supported, add or 3587 delete specific addresses. 3589 The function prototype is 3591 int sctp_bindx(int sd, 3592 struct sockaddr *addrs, 3593 int addrcnt, 3594 int flags); 3596 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3597 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3598 or IPv6 addresses. 3600 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3601 Section 3.1.2 for this usage. 3603 addrs is a pointer to an array of one or more socket addresses. Each 3604 address is contained in its appropriate structure. For an IPv6 3605 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 3606 array of sockaddr_in is used. The caller specifies the number of 3607 addresses in the array with addrcnt. Note that the wildcard 3608 addresses cannot be used in combination with non wildcard addresses 3609 on a socket with this function, doing so will result in an error. 3611 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3612 -1 and sets errno to the appropriate error code. 3614 For SCTP, the port given in each socket address must be the same, or 3615 sctp_bindx() will fail, setting errno to EINVAL. 3617 The flags parameter is formed from the bitwise OR of zero or more of 3618 the following currently defined flags: 3619 o SCTP_BINDX_ADD_ADDR 3620 o SCTP_BINDX_REM_ADDR 3621 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3622 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3623 addresses from the association. The two flags are mutually 3624 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3625 caller may not remove all addresses from an association; sctp_bindx() 3626 will reject such an attempt with EINVAL. 3628 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3629 additional addresses with an endpoint after calling bind(). Or use 3630 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3631 socket is associated with, so that no new association accepted will 3632 be associated with these addresses. If the endpoint supports dynamic 3633 address reconfiguration an SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR 3634 may cause an endpoint to send the appropriate message to the peer to 3635 change the peer's address lists. 3637 Adding and removing addresses from a connected association is an 3638 optional functionality. Implementations that do not support this 3639 functionality should return EOPNOTSUPP. 3641 sctp_bindx() can be called on an already bound socket or on an 3642 unbound socket. If the socket is unbound and the first port number 3643 in the addrs is zero, the kernel will choose a port number. All port 3644 numbers after the first one being 0 must also be zero. If the first 3645 port number is not zero, the following port numbers must be zero or 3646 have the same value as the first one. For an already bound socket, 3647 all port numbers provided must be the bound one or 0. 3649 sctp_bindx() is an atomic operation. Therefore, the binding will be 3650 either successful on all addresses or fail on all addresses. If 3651 multiple addresses are provided and the sctp_bindx() call fails there 3652 is no indication which address is responsible for the failure. The 3653 only way to get a specific error indication is to call sctp_bindx() 3654 with only one address sequentially. 3656 8.2. sctp_peeloff() 3658 After an association is established on a one-to-many style socket, 3659 the application may wish to branch off the association into a 3660 separate socket/file descriptor. 3662 This is particularly desirable when, for instance, the application 3663 wishes to have a number of sporadic message senders/receivers remain 3664 under the original one-to-many style socket, but branch off these 3665 associations carrying high volume data traffic into their own 3666 separate socket descriptors. 3668 The application uses the sctp_peeloff() call to branch off an 3669 association into a separate socket (Note the semantics are somewhat 3670 changed from the traditional one-to-one style accept() call). Note 3671 that the new socket is a one-to-one style socket. Thus it will be 3672 confined to operations allowed for a one-to-one style socket. 3674 The function prototype is 3676 int sctp_peeloff(int sd, 3677 sctp_assoc_t assoc_id); 3679 and the arguments are 3680 sd: The original one-to-many style socket descriptor returned from 3681 the socket() system call (see Section 3.1.1). 3682 assoc_id: the specified identifier of the association that is to be 3683 branched off to a separate file descriptor (Note, in a traditional 3684 one-to-one style accept() call, this would be an out parameter, 3685 but for the one-to-many style call, this is an in parameter). 3686 The function returns a non-negative file descriptor representing the 3687 branched-off association, or -1 if an error occurred. The variable 3688 errno is then set appropriately. 3690 8.3. sctp_getpaddrs() 3692 sctp_getpaddrs() returns all peer addresses in an association. 3694 The function protoype is: 3696 int sctp_getpaddrs(int sd, 3697 sctp_assoc_t id, 3698 struct sockaddr **addrs); 3700 On return, addrs will point to an array dynamically allocated 3701 sockaddr structures of the appropriate type for the socket type. The 3702 caller should use sctp_freepaddrs() to free the memory. Note that 3703 the in/out parameter addrs must not be NULL. 3705 If sd is an IPv4 socket, the addresses returned will be all IPv4 3706 addresses. If sd is an IPv6 socket, the addresses returned can be a 3707 mix of IPv4 or IPv6 addresses. 3709 For one-to-many style sockets, id specifies the association to query. 3710 For one-to-one style sockets, id is ignored. 3712 On success, sctp_getpaddrs() returns the number of peer addresses in 3713 the association. If there is no association on this socket, 3714 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3715 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3716 is undefined. 3718 8.4. sctp_freepaddrs() 3720 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 3722 The function prototype is 3724 void sctp_freepaddrs(struct sockaddr *addrs); 3726 and addrs is the array of peer addresses returned by 3727 sctp_getpaddrs(). 3729 8.5. sctp_getladdrs() 3731 sctp_getladdrs() returns all locally bound address(es) on a socket. 3733 The function prototype is 3735 int sctp_getladdrs(int sd, 3736 sctp_assoc_t id, 3737 struct sockaddr **addrs); 3739 On return, addrs will point to a dynamically allocated array of 3740 sockaddr structures of the appropriate type for the socket type. The 3741 caller should use sctp_freeladdrs() to free the memory. Note that 3742 the in/out parameter addrs must not be NULL. 3744 If sd is an IPv4 socket, the addresses returned will be all IPv4 3745 addresses. If sd is an IPv6 socket, the addresses returned can be a 3746 mix of IPv4 or IPv6 addresses. 3748 For one-to-many style sockets, id specifies the association to query. 3749 For one-to-one style sockets, id is ignored. 3751 If the id field is set to the value '0' then the locally bound 3752 addresses are returned without regard to any particular association. 3754 On success, sctp_getladdrs() returns the number of local addresses 3755 bound to the socket. If the socket is unbound, sctp_getladdrs() 3756 returns 0, and the value of *addrs is undefined. If an error occurs, 3757 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3759 8.6. sctp_freeladdrs() 3761 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 3763 The function prototype is 3765 void sctp_freeladdrs(struct sockaddr *addrs); 3767 and addrs is the array of peer addresses returned by 3768 sctp_getladdrs(). 3770 8.7. sctp_sendmsg() 3772 An implementation may provide a library function (or possibly system 3773 call) to assist the user with the advanced features of SCTP. 3775 The function prototype is 3777 ssize_t sctp_sendmsg(int sd, 3778 const void *msg, 3779 size_t len, 3780 const struct sockaddr *to, 3781 socklen_t tolen, 3782 uint32_t ppid, 3783 uint32_t flags, 3784 uint16_t stream_no, 3785 uint32_t pr_value, 3786 uint32_t context); 3788 and the arguments are: 3790 sd: The socket descriptor. 3791 msg: The message to be sent. 3792 len: The length of the message. 3793 to: The destination address of the message. 3794 tolen: The length of the destination address. 3795 ppid: The same as sinfo_ppid (see Section 5.2.2). 3796 flags: The same as sinfo_flags (see Section 5.2.2). 3797 stream_no: The same as sinfo_stream (see Section 5.2.2). 3798 pr_value: The same as sinfo_pr_value (see Section 5.2.2). 3799 context: The same as sinfo_context (see Section 5.2.2). 3800 The call returns the number of characters sent, or -1 if an error 3801 occurred. The variable errno is then set appropriately. 3803 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 3804 marking is enabled on the socket specified by sd). 3806 Using sctp_sendmsg() on a non-connected one-to-one style socket for 3807 implicit connection setup may or may not work depending on the SCTP 3808 implementation. 3810 8.8. sctp_recvmsg() 3812 This function is deprecated. 3814 An implementation may provide a library function (or possibly system 3815 call) to assist the user with the advanced features of SCTP. Note 3816 that in order for the sctp_sndrcvinfo structure to be filled in by 3817 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3818 the SCTP_EVENTS option. Note that the setting of the 3819 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 3820 sctp_sndrcvinfo information to be extended. 3822 The function prototype is 3824 ssize_t sctp_recvmsg(int sd, 3825 void *msg, 3826 size_t len, 3827 struct sockaddr *from, 3828 socklen_t *fromlen 3829 struct sctp_sndrcvinfo *sinfo 3830 int *msg_flags); 3832 and the arguments are 3833 sd: The socket descriptor. 3835 msg: The message buffer to be filled. 3836 len: The length of the message buffer. 3837 from: A pointer to an address to be filled with the sender of this 3838 messages address. 3839 fromlen: An in/out parameter describing the from length. 3840 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 3841 receipt of the message. 3842 msg_flags: A pointer to an integer to be filled with any message 3843 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 3844 field. Options for the receive may also be passed into the value 3845 (e.g. MSG_PEEK). On return from the call, the msg_flags value 3846 will be different than what was sent in to the call. If 3847 implemented via a recvmsg() call, the msg_flags should only 3848 contain the value of the flags from the recvmsg() call. 3849 The call returns the number of bytes received, or -1 if an error 3850 occurred. The variable errno is then set appropriately. 3852 8.9. sctp_connectx() 3854 An implementation may provide a library function (or possibly system 3855 call) to assist the user with associating to an endpoint that is 3856 multi-homed. Much like sctp_bindx() this call allows a caller to 3857 specify multiple addresses at which a peer can be reached. The way 3858 the SCTP stack uses the list of addresses to set up the association 3859 is implementation dependent. This function only specifies that the 3860 stack will try to make use of all the addresses in the list when 3861 needed. 3863 Note that the list of addresses passed in is only used for setting up 3864 the association. It does not necessarily equal the set of addresses 3865 the peer uses for the resulting association. If the caller wants to 3866 find out the set of peer addresses, it must use sctp_getpaddrs() to 3867 retrieve them after the association has been set up. 3869 The function prototype is 3871 int sctp_connectx(int sd, 3872 struct sockaddr *addrs, 3873 int addrcnt, 3874 sctp_assoc_t *id); 3876 and the arguments are: 3877 sd: The socket descriptor. 3878 addrs: An (packed) array of addresses. 3880 addrcnt: The number of addresses in the array. 3881 id: An output parameter that if passed in as a non-NULL will return 3882 the association identification for the newly created association 3883 (if successful). 3885 The call returns 0 on success or -1 if an error occurred. The 3886 variable errno is then set appropriately. 3888 8.10. sctp_send() 3890 This function is deprecated. 3892 An implementation may provide another alternative function or system 3893 call to assist an application with the sending of data without the 3894 use of the CMSG header structures. 3896 The function prototype is 3898 ssize_t sctp_send(int sd, 3899 const void *msg, 3900 size_t len, 3901 const struct sctp_sndrcvinfo *sinfo, 3902 int flags); 3904 and the arguments are 3905 sd: The socket descriptor. 3906 msg: The message to be sent. 3907 len: The length of the message. 3908 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 3909 in Section 5.2.2 for a sendmsg call. 3910 flags: The same flags as used by the sendmsg() call flags (e.g. 3911 MSG_DONTROUTE). 3912 The call returns the number of bytes sent, or -1 if an error 3913 occurred. The variable errno is then set appropriately. 3915 This function call may also be used to terminate an association using 3916 an association identification by setting the sinfo.sinfo_flags to 3917 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3918 to be terminated. In such a case the len of the message would be 3919 zero. 3921 Using sctp_send() on a non-connected one-to-one style socket for 3922 implicit connection setup may or may not work depending on the SCTP 3923 implementation. 3925 Sending a message using sctp_send() is atomic unless explicit EOR 3926 marking is enabled on the socket specified by sd. 3928 8.11. sctp_sendx() 3930 This function is deprecated. 3932 An implementation may provide another alternative function or system 3933 call to assist an application with the sending of data without the 3934 use of the CMSG header structures that also gives a list of 3935 addresses. The list of addresses is provided for implicit 3936 association setup. In such a case the list of addresses serves the 3937 same purpose as the addresses given in sctp_connectx() (see 3938 Section 8.9). 3940 The function prototype is 3942 ssize_t sctp_sendx(int sd, 3943 const void *msg, 3944 size_t len, 3945 struct sockaddr *addrs, 3946 int addrcnt, 3947 struct sctp_sndrcvinfo *sinfo, 3948 int flags); 3950 and the arguments are: 3951 sd: The socket descriptor. 3952 msg: The message to be sent. 3953 len: The length of the message. 3954 addrs: is an array of addresses. 3955 addrcnt: The number of addresses in the array. 3956 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3957 Section 5.2.2 for a sendmsg() call. 3958 flags: The same flags as used by the sendmsg() call flags (e.g. 3959 MSG_DONTROUTE). 3960 The call returns the number of bytes sent, or -1 if an error 3961 occurred. The variable errno is then set appropriately. 3963 Note that on return from this call the sinfo structure will have 3964 changed in that the sinfo_assoc_id will be filled in with the new 3965 association id. 3967 This function call may also be used to terminate an association using 3968 an association identification by setting the sinfo.sinfo_flags to 3969 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3970 to be terminated. In such a case the len of the message would be 3971 zero. 3973 Sending a message using sctp_send() is atomic unless explicit EOR 3974 marking is enabled on the socket specified by sd. 3976 Using sctp_sendx() on a non-connected one-to-one style socket for 3977 implicit connection setup may or may not work depending on the SCTP 3978 implementation. 3980 8.12. sctp_recvxxx() 3982 An implementation may provide a library function (or possibly system 3983 call) to assist the user with the advanced features of SCTP. Note 3984 that in order for the sctp_recvinfo structure to be filled in by 3985 sctp_recvxxx() the caller must set the SCTP_RECVRCVINFO and 3986 SCTP_RECVNXTINFO socket option. 3988 The function prototype is 3990 struct sctp_recvinfo { 3991 uint16_t recv_version; 3992 uint16_t recv_length; 3993 struct sctp_rcvinfo recv_rcvinfo; 3994 struct sctp_rcvinfo recv_nxtinfo; 3995 }; 3997 ssize_t sctp_recvxxx(int sd, 3998 void *msg, 3999 size_t len, 4000 struct sockaddr *from, 4001 socklen_t *fromlen 4002 struct sctp_recvinfo *info 4003 int *msg_flags); 4005 and the arguments are 4006 sd: The socket descriptor. 4007 msg: The message buffer to be filled. 4008 len: The length of the message buffer. 4009 from: A pointer to an address to be filled with the sender of this 4010 messages address. 4011 fromlen: An in/out parameter describing the from length. 4012 info: A pointer to an sctp_recvinfo structure to be filled upon 4013 receipt of the message. 4014 msg_flags: A pointer to an integer to be filled with any message 4015 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4016 field. Options for the receive may also be passed into the value 4017 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4018 will be different than what was sent in to the call. If 4019 implemented via a recvmsg() call, the msg_flags should only 4020 contain the value of the flags from the recvmsg() call. 4021 The call returns the number of bytes received, or -1 if an error 4022 occurred. The variable errno is then set appropriately. 4024 8.13. sctp_sendxxx() 4026 An implementation may provide another alternative function or system 4027 call to assist an application with the sending of data without the 4028 use of the CMSG header structures that also gives a list of 4029 addresses. The list of addresses is provided for implicit 4030 association setup. In such a case the list of addresses serves the 4031 same purpose as the addresses given in sctp_connectx() (see 4032 Section 8.9). 4034 The function prototype is 4036 struct sctp_sendinfo { 4037 uint16_t send_version; 4038 uint16_t send_length; 4039 struct sctp_sndinfo send_sndinfo; 4040 struct sctp_prinfo send_prinfo; 4041 struct sctp_authinfo send_authinfo; 4042 }; 4044 ssize_t sctp_sendxxx(int sd, 4045 const void *msg, 4046 size_t len, 4047 struct sockaddr *addrs, 4048 int addrcnt, 4049 struct sctp_sendinfo *info, 4050 int flags); 4052 and the arguments are: 4053 sd: The socket descriptor. 4054 msg: The message to be sent. 4055 len: The length of the message. 4056 addrs: is an array of addresses. 4057 addrcnt: The number of addresses in the array. 4058 sinfo: A pointer to a sctp_sendinfo structure. 4059 flags: The same flags as used by the sendmsg() call flags (e.g. 4060 MSG_DONTROUTE). 4061 The call returns the number of bytes sent, or -1 if an error 4062 occurred. The variable errno is then set appropriately. 4064 Note that on return from this call the sinfo structure will have 4065 changed in that the send_sndinfo.snd_sid will be filled in with the 4066 new association id. 4068 This function call may also be used to terminate an association using 4069 an association identification by setting the send_sndinfo.snd_flags 4070 to SCTP_EOF and the send_sndinfo.snd_sid to the association that 4071 needs to be terminated. In such a case the len of the message would 4072 be zero. 4074 Sending a message using sctp_sendxxx() is atomic unless explicit EOR 4075 marking is enabled on the socket specified by sd. 4077 Using sctp_sendxxx() on a non-connected one-to-one style socket for 4078 implicit connection setup may or may not work depending on the SCTP 4079 implementation. 4081 9. IANA Considerations 4083 This document requires no actions from IANA. 4085 10. Security Considerations 4087 Many TCP and UDP implementations reserve port numbers below 1024 for 4088 privileged users. If the target platform supports privileged users, 4089 the SCTP implementation should restrict the ability to call bind() or 4090 sctp_bindx() on these port numbers to privileged users. 4092 Similarly unprivileged users should not be able to set protocol 4093 parameters that could result in the congestion control algorithm 4094 being more aggressive than permitted on the public Internet. These 4095 parameters are: 4096 o struct sctp_rtoinfo 4098 If an unprivileged user inherits a one-to-many style socket with open 4099 associations on a privileged port, it may be permitted to accept new 4100 associations, but it should not be permitted to open new 4101 associations. This could be relevant for the r* family of protocols. 4103 Applications using the one-to-many style sockets and using the 4104 interleave level if 0 are subject to denial of service attacks as 4105 described in Section 7.1.20. 4107 11. Acknowledgments 4109 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4110 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4111 early formation of this document. 4113 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 4114 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 4115 Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG 4116 mailing list for contributing valuable comments. 4118 A special thanks to Phillip Conrad, for his suggested text, quick and 4119 constructive insights, and most of all his persistent fighting to 4120 keep the interface to SCTP usable for the application programmer. 4122 12. References 4124 12.1. Normative References 4126 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4127 Stevens, "Basic Socket Interface Extensions for IPv6", 4128 RFC 3493, February 2003. 4130 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4131 "Advanced Sockets Application Program Interface (API) for 4132 IPv6", RFC 3542, May 2003. 4134 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4135 Conrad, "Stream Control Transmission Protocol (SCTP) 4136 Partial Reliability Extension", RFC 3758, May 2004. 4138 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4139 "Authenticated Chunks for the Stream Control Transmission 4140 Protocol (SCTP)", RFC 4895, August 2007. 4142 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4143 RFC 4960, September 2007. 4145 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4146 Kozuka, "Stream Control Transmission Protocol (SCTP) 4147 Dynamic Address Reconfiguration", RFC 5061, 4148 September 2007. 4150 12.2. Informative References 4152 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4153 RFC 793, September 1981. 4155 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4156 August 1980. 4158 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4159 Functional Specification", RFC 1644, July 1994. 4161 Appendix A. One-to-One Style Code Example 4163 The following code is a simple implementation of an echo server over 4164 SCTP. The example shows how to use some features of one-to-one style 4165 IPv4 SCTP sockets, including: 4166 o Opening, binding, and listening for new associations on a socket 4167 o Enabling ancillary data 4168 o Enabling notifications 4169 o Using ancillary data with sendmsg() and recvmsg() 4170 o Using MSG_EOR to determine if an entire message has been read 4171 o Handling notifications 4173 #include 4174 #include 4175 #include 4176 #include 4177 #include 4178 #include 4179 #include 4180 #include 4181 #include 4183 #define BUFLEN 100 4185 static void 4186 handle_event(void *buf) 4187 { 4188 struct sctp_assoc_change *sac; 4189 struct sctp_send_failed *ssf; 4190 struct sctp_paddr_change *spc; 4191 struct sctp_remote_error *sre; 4192 union sctp_notification *snp; 4193 char addrbuf[INET6_ADDRSTRLEN]; 4194 const char *ap; 4195 struct sockaddr_in *sin; 4196 struct sockaddr_in6 *sin6; 4198 snp = buf; 4200 switch (snp->sn_header.sn_type) { 4201 case SCTP_ASSOC_CHANGE: 4202 sac = &snp->sn_assoc_change; 4203 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 4204 "outstr=%hu\n", sac->sac_state, sac->sac_error, 4205 sac->sac_inbound_streams, sac->sac_outbound_streams); 4206 break; 4207 case SCTP_SEND_FAILED: 4208 ssf = &snp->sn_send_failed; 4209 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 4210 ssf->ssf_error); 4211 break; 4213 case SCTP_PEER_ADDR_CHANGE: 4214 spc = &snp->sn_paddr_change; 4215 if (spc->spc_aaddr.ss_family == AF_INET) { 4216 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4217 ap = inet_ntop(AF_INET, &sin->sin_addr, 4218 addrbuf, INET6_ADDRSTRLEN); 4219 } else { 4220 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4221 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4222 addrbuf, INET6_ADDRSTRLEN); 4223 } 4224 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 4225 spc->spc_state, spc->spc_error); 4226 break; 4227 case SCTP_REMOTE_ERROR: 4228 sre = &snp->sn_remote_error; 4229 printf("^^^ remote_error: err=%hu len=%hu\n", 4230 ntohs(sre->sre_error), ntohs(sre->sre_length)); 4231 break; 4232 case SCTP_SHUTDOWN_EVENT: 4233 printf("^^^ shutdown event\n"); 4234 break; 4235 default: 4236 printf("unknown type: %hu\n", snp->sn_header.sn_type); 4237 break; 4238 }; 4239 } 4241 static void * 4242 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 4243 ssize_t *nrp, size_t cmsglen) 4244 { 4245 ssize_t nr = 0, nnr = 0; 4246 struct iovec iov; 4248 *nrp = 0; 4249 iov.iov_base = buf; 4250 iov.iov_len = *buflen; 4251 msg->msg_iov = &iov; 4252 msg->msg_iovlen = 1; 4254 for (;;) { 4255 #ifndef MSG_XPG4_2 4256 #define MSG_XPG4_2 0 4257 #endif 4258 msg->msg_flags = MSG_XPG4_2; 4259 msg->msg_controllen = cmsglen; 4260 nnr = recvmsg(fd, msg, 0); 4261 if (nnr <= 0) { 4262 /* EOF or error */ 4263 *nrp = nr; 4264 return (NULL); 4265 } 4266 nr += nnr; 4268 if ((msg->msg_flags & MSG_EOR) != 0) { 4269 *nrp = nr; 4270 return (buf); 4271 } 4273 /* Realloc the buffer? */ 4274 if (*buflen == (size_t)nr) { 4275 buf = realloc(buf, *buflen * 2); 4276 if (buf == 0) { 4277 fprintf(stderr, "out of memory\n"); 4278 exit(1); 4279 } 4280 *buflen *= 2; 4281 } 4282 /* Set the next read offset */ 4283 iov.iov_base = (char *)buf + nr; 4284 iov.iov_len = *buflen - nr; 4285 } 4286 } 4288 static void 4289 echo(int fd, int socketModeone_to_many) 4290 { 4291 ssize_t nr; 4292 struct sctp_sndrcvinfo *sri; 4293 struct msghdr msg; 4294 struct cmsghdr *cmsg; 4295 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 4296 char *buf; 4297 size_t buflen; 4298 struct iovec iov; 4299 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 4300 /* Allocate the initial data buffer */ 4301 buflen = BUFLEN; 4302 if (!(buf = malloc(BUFLEN))) { 4303 fprintf(stderr, "out of memory\n"); 4304 exit(1); 4305 } 4307 /* Set up the msghdr structure for receiving */ 4308 memset(&msg, 0, sizeof (msg)); 4309 msg.msg_control = cbuf; 4310 msg.msg_controllen = cmsglen; 4311 msg.msg_flags = 0; 4312 cmsg = (struct cmsghdr *)cbuf; 4313 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 4315 /* Wait for something to echo */ 4316 while (buf = mysctp_recvmsg(fd, &msg, 4317 buf, &buflen, &nr, cmsglen)) { 4319 /* Intercept notifications here */ 4320 if (msg.msg_flags & MSG_NOTIFICATION) { 4321 handle_event(buf); 4322 continue; 4323 } 4325 iov.iov_base = buf; 4326 iov.iov_len = nr; 4327 msg.msg_iov = &iov; 4328 msg.msg_iovlen = 1; 4330 printf("got %u bytes on stream %hu:\n", nr, 4331 sri->sinfo_stream); 4332 write(0, buf, nr); 4334 /* Echo it back */ 4335 msg.msg_flags = MSG_XPG4_2; 4336 if (sendmsg(fd, &msg, 0) < 0) { 4337 perror("sendmsg"); 4338 exit(1); 4339 } 4340 } 4342 if (nr < 0) { 4343 perror("recvmsg"); 4344 } 4345 if(socketModeone_to_many == 0) 4346 close(fd); 4347 } 4349 int main() 4350 { 4351 struct sctp_event_subscribe event; 4352 int lfd, cfd; 4353 int onoff = 1; 4354 struct sockaddr_in sin; 4355 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 4356 perror("socket"); 4357 exit(1); 4358 } 4360 sin.sin_family = AF_INET; 4361 sin.sin_port = htons(7); 4362 sin.sin_addr.s_addr = INADDR_ANY; 4363 if (bind(lfd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4364 perror("bind"); 4365 exit(1); 4366 } 4368 if (listen(lfd, 1) == -1) { 4369 perror("listen"); 4370 exit(1); 4371 } 4373 /* Wait for new associations */ 4374 for (;;) { 4375 if ((cfd = accept(lfd, NULL, 0)) == -1) { 4376 perror("accept"); 4377 exit(1); 4378 } 4380 /* Enable all events */ 4381 event.sctp_data_io_event = 1; 4382 event.sctp_association_event = 1; 4383 event.sctp_address_event = 1; 4384 event.sctp_send_failure_event = 1; 4385 event.sctp_peer_error_event = 1; 4386 event.sctp_shutdown_event = 1; 4387 event.sctp_partial_delivery_event = 1; 4388 event.sctp_adaptation_layer_event = 1; 4389 if (setsockopt(cfd, IPPROTO_SCTP, 4390 SCTP_EVENTS, &event, 4391 sizeof(event)) != 0) { 4392 perror("setevent failed"); 4393 exit(1); 4394 } 4395 /* Echo back any and all data */ 4396 echo(cfd,0); 4397 } 4398 } 4400 Appendix B. One-to-Many Style Code Example 4402 The following code is a simple implementation of an echo server over 4403 SCTP. The example shows how to use some features of one-to-many 4404 style IPv4 SCTP sockets, including: 4405 o Opening and binding of a socket 4406 o Enabling ancillary data 4407 o Enabling notifications 4408 o Using ancillary data with sendmsg() and recvmsg() 4409 o Using MSG_EOR to determine if an entire message has been read 4410 o Handling notifications 4412 Note most functions defined in Appendix A are reused in this example. 4414 int main() 4415 { 4416 int fd; 4417 int idleTime = 2; 4418 struct sockaddr_in sin; 4419 struct sctp_event_subscribe event; 4421 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 4422 perror("socket"); 4423 exit(1); 4424 } 4426 sin.sin_family = AF_INET; 4427 sin.sin_port = htons(7); 4428 sin.sin_addr.s_addr = INADDR_ANY; 4429 if (bind(fd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4430 perror("bind"); 4431 exit(1); 4432 } 4434 /* Enable all notifications and events */ 4435 event.sctp_data_io_event = 1; 4436 event.sctp_association_event = 1; 4437 event.sctp_address_event = 1; 4438 event.sctp_send_failure_event = 1; 4439 event.sctp_peer_error_event = 1; 4440 event.sctp_shutdown_event = 1; 4441 event.sctp_partial_delivery_event = 1; 4442 event.sctp_adaptation_layer_event = 1; 4443 if (setsockopt(fd, IPPROTO_SCTP, 4444 SCTP_EVENTS, &event, 4445 sizeof(event)) != 0) { 4446 perror("setevent failed"); 4447 exit(1); 4449 } 4450 /* Set associations to auto-close in 2 seconds of 4451 * inactivity 4452 */ 4453 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4454 &idleTime, 4) < 0) { 4455 perror("setsockopt SCTP_AUTOCLOSE"); 4456 exit(1); 4457 } 4459 /* Allow new associations to be accepted */ 4460 if (listen(fd, 1) < 0) { 4461 perror("listen"); 4462 exit(1); 4463 } 4465 /* Wait for new associations */ 4466 while(1){ 4467 /* Echo back any and all data */ 4468 echo(fd,1); /* from appendix a */ 4469 } 4470 } 4472 Authors' Addresses 4474 Randall R. Stewart 4475 Huawei 4476 Chapin, SC 29036 4477 USA 4479 Email: rstewart@huawei.com 4481 Kacheong Poon 4482 Oracle Corporation 4484 Email: ka-cheong.poon@oracle.com 4486 Michael Tuexen 4487 Muenster University of Applied Sciences 4488 Stegerwaldstr. 39 4489 48565 Steinfurt 4490 Germany 4492 Email: tuexen@fh-muenster.de 4493 Vladislav Yasevich 4494 HP 4495 110 Spitrook Rd 4496 Nashua, NH 03062 4497 USA 4499 Email: vladislav.yasevich@hp.com 4501 Peter Lei 4502 Cisco Systems, Inc. 4503 8735 West Higgins Road 4504 Suite 300 4505 Chicago, IL 60631 4506 USA 4508 Email: peterlei@cisco.com