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