idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 22. -- Found old boilerplate from RFC 3978, Section 5.5 on line 3641. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3618. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3625. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3631. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC2960]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1045 has weird spacing: '...g_level cms...' == Line 1099 has weird spacing: '...g_level cms...' == Line 1252 has weird spacing: '..._change sn_a...' == Line 1253 has weird spacing: '..._change sn_p...' == Line 1254 has weird spacing: '...e_error sn_r...' == (5 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The chunk types for INIT, INIT-ACK, COOKIE-ECHO, COOKIE-ACK, SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are used an error MUST be returned. The usage of this option enables SCTP-AUTH in cases where it is not required by other means (for example the use of ADD-IP). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 17, 2006) is 6636 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 1509 -- Looks like a reference, but probably isn't: '1' on line 3510 == Unused Reference: 'RFC2026' is defined on line 3230, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 3233, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (Obsoleted by RFC 4960) Summary: 9 errors (**), 0 flaws (~~), 12 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Cisco Systems, Inc. 4 Expires: August 21, 2006 Q. Xie 5 Motorola, Inc. 6 L. Yarroll 7 TimeSys Corp 8 K. Poon 9 Sun Microsystems, Inc. 10 M. Tuexen 11 Univ. of Applied Sciences Muenster 12 February 17, 2006 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-12.txt 17 Status of this Memo 19 By submitting this Internet-Draft, each author represents that any 20 applicable patent or other IPR claims of which he or she is aware 21 have been or will be disclosed, and any of which he or she becomes 22 aware will be disclosed, in accordance with Section 6 of BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on August 21, 2006. 42 Copyright Notice 44 Copyright (C) The Internet Society (2006). 46 Abstract 48 This document describes a mapping of the Stream Control Transmission 49 Protocol SCTP RFC2960 [RFC2960] into a sockets API. The benefits of 50 this mapping include compatibility for TCP applications, access to 51 new SCTP features and a consolidated error and event notification 52 scheme. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6 60 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 61 3.1.1. socket() - one-to-many style socket . . . . . . . . . 7 62 3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8 63 3.1.3. listen() - One-to-many style socket . . . . . . . . . 9 64 3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9 65 3.1.5. close() - one-to-many style socket . . . . . . . . . . 11 66 3.1.6. connect() - one-to-many style socket . . . . . . . . . 11 67 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 68 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 69 3.4. Special considerations . . . . . . . . . . . . . . . . . . 13 70 4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15 71 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15 72 4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16 73 4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 16 74 4.1.3. listen() - one-to-one style socket . . . . . . . . . . 17 75 4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18 76 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18 77 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19 78 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19 79 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20 80 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20 81 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 82 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21 83 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22 84 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23 85 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24 86 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 27 87 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 27 88 5.4. Ancillary Data Considerations and Semantics . . . . . . . 38 89 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 38 90 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 38 91 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 39 92 6. Common Operations for Both Styles . . . . . . . . . . . . . . 40 93 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 40 94 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 41 95 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 42 96 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 42 97 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 42 98 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 44 99 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 44 100 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 45 101 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 46 102 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 47 103 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 47 104 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 47 105 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 47 106 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 48 107 7.1.9. Set Peer Primary Address 108 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 48 109 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 48 110 7.1.11. Set Adaptation Layer Indicator 111 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 49 112 7.1.12. Enable/Disable message fragmentation 113 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 49 114 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 49 115 7.1.14. Set default send parameters 116 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 52 117 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 52 118 7.1.16. Set/clear IPv4 mapped addresses 119 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 53 120 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) . . . 53 121 7.1.18. Add a chunk that must be authenticated 122 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 53 123 7.1.19. Set the endpoint pair shared key (SCTP_AUTH_KEY) . . . 54 124 7.1.20. Get the list of chunks the peer requires to be 125 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 54 126 7.1.21. Get the list of chunks the local endpoint requires 127 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 55 128 7.1.22. Set the list of supported HMAC Identifiers 129 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 55 130 7.1.23. Get or set the active key 131 (SCTP_AUTH_SETKEY_ACTIVE) . . . . . . . . . . . . . . 55 132 7.1.24. Get or set delayed ack timer 133 (SCTP_DELAYED_ACK_TIME) . . . . . . . . . . . . . . . 56 134 7.1.25. Get or set fragmented interleave 135 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 57 136 7.1.26. Set or Get the sctp partial delivery point 137 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 57 138 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 58 139 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 58 140 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 59 141 7.3. Ancillary Data and Notification Interest Options . . . . . 60 142 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 62 143 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 62 144 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 63 145 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 64 146 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 64 147 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 65 148 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 65 149 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 66 150 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 66 151 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 67 152 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 67 153 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 68 154 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 69 155 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 69 156 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 70 157 11. Security Considerations . . . . . . . . . . . . . . . . . . . 70 158 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 70 159 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 71 160 13.1. Normative references . . . . . . . . . . . . . . . . . . . 71 161 13.2. Informational References . . . . . . . . . . . . . . . . . 71 162 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 71 163 Appendix B. one-to-many style Code Example . . . . . . . . . . . 76 164 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 79 165 Intellectual Property and Copyright Statements . . . . . . . . . . 81 167 1. Introduction 169 The sockets API has provided a standard mapping of the Internet 170 Protocol suite to many operating systems. Both TCP RFC793 [RFC0793] 171 and UDP RFC768 [RFC0768] have benefited from this standard 172 representation and access method across many diverse platforms. SCTP 173 is a new protocol that provides many of the characteristics of TCP 174 but also incorporates semantics more akin to UDP. This document 175 defines a method to map the existing sockets API for use with SCTP, 176 providing both a base for access to new features and compatibility so 177 that most existing TCP applications can be migrated to SCTP with few 178 (if any) changes. 180 There are three basic design objectives: 182 1) Maintain consistency with existing sockets APIs: 183 We define a sockets mapping for SCTP that is consistent with other 184 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 185 IPv6). 186 2) Support a one-to-many style interface 187 This set of semantics is similar to that defined for connection- 188 less protocols, such as UDP. A one-to-many style SCTP socket 189 should be able to control multiple SCTP associations. This is 190 similar to an UDP socket, which can communicate with many peer end 191 points. Each of these associations is assigned an association ID 192 so that an applications can use the ID to differentiate them. 193 Note that SCTP is connection-oriented in nature, and it does not 194 support broadcast or multicast communications, as UDP does. 195 3) Support a one-to-one style interface 196 This interface supports a similar semantics as sockets for 197 connection-oriented protocols, such as TCP. A one-to-one style 198 SCTP socket should only control one SCTP association. 199 One purpose of defining this interface is to allow existing 200 applications built on other connection-oriented protocols be 201 ported to use SCTP with very little effort. And developers 202 familiar with those semantics can easily adapt to SCTP. Another 203 purpose is to make sure that existing mechanisms in most OSes to 204 deal with socket, such as select(), should continue to work with 205 this style of socket. 206 Extensions are added to this mapping to provide mechanisms to 207 exploit new features of SCTP. 209 Goals 2 and 3 are not compatible, so in this document we define two 210 modes of mapping, namely the one-to-many style mapping and the one- 211 to-one style mapping. These two modes share some common data 212 structures and operations, but will require the use of two different 213 application programming styles. Note that all new SCTP features can 214 be used with both styles of socket. The decision on which one to use 215 depends mainly on the nature of applications. 217 A mechanism is defined to extract a one-to-many style SCTP 218 association into a one-to-one style socket. 220 Some of the SCTP mechanisms cannot be adequately mapped to existing 221 socket interface. In some cases, it is more desirable to have new 222 interface instead of using existing socket calls. Section 8 of this 223 document describes those new interface. 225 2. Conventions 227 2.1. Data Types 229 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 230 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 231 (e.g., uint16_t). We also assume the argument data types from 232 1003.1g when possible (e.g., the final argument to setsockopt() is a 233 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 234 size_t data type is used. 236 3. one-to-many style Interface 238 The one-to-many style interface has the following characteristics: 240 A) Outbound association setup is implicit. 242 B) Messages are delivered in complete messages (with one notable 243 exception). 245 C) There is a 1 to MANY relationship between socket and association. 247 3.1. Basic Operation 249 A typical server in this style uses the following socket calls in 250 sequence to prepare an endpoint for servicing requests: 252 1. socket() 253 2. bind() 254 3. listen() 255 4. recvmsg() 256 5. sendmsg() 257 6. close() 259 A typical client uses the following calls in sequence to setup an 260 association with a server to request services: 262 1. socket() 263 2. sendmsg() 264 3. recvmsg() 265 4. close() 267 In this style, by default, all the associations connected to the 268 endpoint are represented with a single socket. Each associations is 269 assigned an association ID (type is sctp_assoc_t) so that an 270 application can use it to differentiate between them. In some 271 implementations, the peer end point's addresses can also be used for 272 this purpose. But this is not required for performance reasons. If 273 an implementation does not support using addresses to differentiate 274 between different associations, the sendto() call can only be used to 275 setup an association implicitly. It cannot be used to send data to 276 an established association as the association ID cannot be specified. 278 Once as association ID is assigned to an SCTP association, that ID 279 will not be reused until the application explicitly terminates the 280 association. The resources belonged to that association will not be 281 freed until that happens. This is similar to the close() operation 282 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 283 option (section 7.1.8) is set. In this case, after the association 284 is terminated gracefully automatically, the association ID assigned 285 to it can be reused. All applications using this option should be 286 aware of this to avoid the possible problem of sending data to an 287 incorrect peer end point. 289 If the server or client wishes to branch an existing association off 290 to a separate socket, it is required to call sctp_peeloff() and in 291 the parameter specifies the association identification. The 292 sctp_peeloff() call will return a new socket which can then be used 293 with recv() and send() functions for message passing. See 294 Section 8.2 for more on branched-off associations. 296 Once an association is branched off to a separate socket, it becomes 297 completely separated from the original socket. All subsequent 298 control and data operations to that association must be done through 299 the new socket. For example, the close operation on the original 300 socket will not terminate any associations that have been branched 301 off to a different socket. 303 We will discuss the one-to-many style socket calls in more details in 304 the following subsections. 306 3.1.1. socket() - one-to-many style socket 308 Applications use socket() to create a socket descriptor to represent 309 an SCTP endpoint. 311 The syntax is, 313 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 315 or, 317 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 319 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 320 socket. 322 The first form creates an endpoint which can use only IPv4 addresses, 323 while, the second form creates an endpoint which can use both IPv6 324 and IPv4 addresses. 326 3.1.2. bind() - one-to-many style socket 328 Applications use bind() to specify which local address the SCTP 329 endpoint should associate itself with. 331 An SCTP endpoint can be associated with multiple addresses. To do 332 this, sctp_bindx() is introduced in section Section 8.1 to help 333 applications do the job of associating multiple addresses. 335 These addresses associated with a socket are the eligible transport 336 addresses for the endpoint to send and receive data. The endpoint 337 will also present these addresses to its peers during the association 338 initialization process, see RFC2960 [RFC2960]. 340 After calling bind(), if the endpoint wishes to accept new 341 associations on the socket, it must call listen() (see section 342 Section 3.1.3). 344 The syntax of bind() is, 346 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 348 sd - the socket descriptor returned by socket(). 349 addr - the address structure (struct sockaddr_in or struct 350 sockaddr_in6 RFC2553 [RFC2553]). 351 addrlen - the size of the address structure. 353 If sd is an IPv4 socket, the address passed must be an IPv4 address. 354 If the sd is an IPv6 socket, the address passed can either be an IPv4 355 or an IPv6 address. 357 Applications cannot call bind() multiple times to associate multiple 358 addresses to an endpoint. After the first call to bind(), all 359 subsequent calls will return an error. 361 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 362 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 363 operating system will associate the endpoint with an optimal address 364 set of the available interfaces. 366 If a bind() is not called prior to a sendmsg() call that initiates a 367 new association, the system picks an ephemeral port and will choose 368 an address set equivalent to binding with a wildcard address. One of 369 those addresses will be the primary address for the association. 370 This automatically enables the multi-homing capability of SCTP. 372 3.1.3. listen() - One-to-many style socket 374 By default, new associations are not accepted for one-to-many style 375 sockets. An application uses listen() to mark a socket as being able 376 to accept new associations. The syntax is, 378 int listen(int sd, int backlog); 380 sd - the socket descriptor of the endpoint. 381 backlog - if backlog is non-zero, enable listening else disable 382 listening. 384 Note that one-to-many style socket consumers do not need to call 385 accept to retrieve new associations. Calling accept() on a one-to- 386 many style socket should return EOPNOTSUPP. Rather, new associations 387 are accepted automatically, and notifications of the new associations 388 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 389 these notifications are enabled). Clients will typically not call 390 listen(), so that they can be assured that the only associations on 391 the socket will be ones they actively initiated. Server or peer-to- 392 peer sockets, on the other hand, will always accept new associations, 393 so a well-written application using server one-to-many style sockets 394 must be prepared to handle new associations from unwanted peers. 396 Also note that the SCTP_ASSOC_CHANGE event provides the association 397 ID for a new association, so if applications wish to use the 398 association ID as input to other socket calls, they should ensure 399 that the SCTP_ASSOC_CHANGE event is enabled. 401 3.1.4. sendmsg() and recvmsg() - one-to-many style socket 403 An application uses sendmsg() and recvmsg() call to transmit data to 404 and receive data from its peer. 406 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 408 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 410 sd - the socket descriptor of the endpoint. 411 message: pointer to the msghdr structure which contains a single user 412 message and possibly some ancillary data. See Section 5 for 413 complete description of the data structures. 414 flags - No new flags are defined for SCTP at this level. See Section 415 5 for SCTP-specific flags used in the msghdr structure. 417 As we will see in Section 5, along with the user data, the ancillary 418 data field is used to carry the sctp_sndrcvinfo and/or the 419 sctp_initmsg structures to perform various SCTP functions including 420 specifying options for sending each user message. Those options, 421 depending on whether sending or receiving, include stream number, 422 stream sequence number, various flags, context and payload protocol 423 Id, etc. 425 When sending user data with sendmsg(), the msg_name field in msghdr 426 structure will be filled with one of the transport addresses of the 427 intended receiver. If there is no association existing between the 428 sender and the intended receiver, the sender's SCTP stack will set up 429 a new association and then send the user data (see Section 3.2 for 430 more on implicit association setup). 432 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 433 be delivered if that notification has been enabled, and no more data 434 can be sent to that association. Any attempt to send more data will 435 cause sendmsg() to return with an ESHUTDOWN error. Note that the 436 socket is still open for reading at this point so it is possible to 437 retrieve notifications. 439 When receiving a user message with recvmsg(), the msg_name field in 440 msghdr structure will be populated with the source transport address 441 of the user data. The caller of recvmsg() can use this address 442 information to determine to which association the received user 443 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 444 applications must use the peer transport address provided in the 445 msg_name field by recvmsg() to perform correlation to an association, 446 since they will not have the association ID. 448 If all data in a single message has been delivered, MSG_EOR will be 449 set in the msg_flags field of the msghdr structure (see section 450 Section 5.1). 452 If the application does not provide enough buffer space to completely 453 receive a data message, MSG_EOR will not be set in msg_flags. 455 Successive reads will consume more of the same message until the 456 entire message has been delivered, and MSG_EOR will be set. 458 If the SCTP stack is running low on buffers, it may partially deliver 459 a message. In this case, MSG_EOR will not be set, and more calls to 460 recvmsg() will be necessary to completely consume the message. Only 461 one message at a time per stream can be partially delivered. 463 Note, if the socket is a branched-off socket that only represents one 464 association (see Section 3.1), the msg_name field can be used to 465 override the primary address when sending data. 467 3.1.5. close() - one-to-many style socket 469 Applications use close() to perform graceful shutdown (as described 470 in Section 10.1 of RFC2960 [RFC2960]) on ALL the associations 471 currently represented by a one-to-many style socket. 473 The syntax is: 475 ret = close(int sd); 477 sd - the socket descriptor of the associations to be closed. 479 To gracefully shutdown a specific association represented by the one- 480 to-many style socket, an application should use the sendmsg() call, 481 and including the SCTP_EOF flag. A user may optionally terminate an 482 association non-gracefully by sending with the SCTP_ABORT flag and 483 possibly passing a user specified abort code in the data field. Both 484 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 485 Section 5.2.2) in the sendmsg call. 487 If sd in the close() call is a branched-off socket representing only 488 one association, the shutdown is performed on that association only. 490 3.1.6. connect() - one-to-many style socket 492 An application may use the connect() call in the one-to-many style to 493 initiate an association without sending data. 495 The syntax is: 497 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 498 sd - the socket descriptor to have a new association added to. 499 nam - the address structure (either struct sockaddr_in or struct 500 sockaddr_in6 defined in RFC2553 [RFC2553]). 501 len - the size of the address. 502 Multiple connect() calls can be made on the same socket to create 503 multiple associations. This is different from the semantics of 504 connect() on a UDP socket. 506 3.2. Implicit Association Setup 508 Once the bind() call is complete on a one-to-many style socket, the 509 application can begin sending and receiving data using the sendmsg()/ 510 recvmsg() or sendto()/recvfrom() calls, without going through any 511 explicit association setup procedures (i.e., no connect() calls 512 required). 514 Whenever sendmsg() or sendto() is called and the SCTP stack at the 515 sender finds that there is no association existing between the sender 516 and the intended receiver (identified by the address passed either in 517 the msg_name field of msghdr structure in the sendmsg() call or the 518 dest_addr field in the sendto() call), the SCTP stack will 519 automatically setup an association to the intended receiver. 521 Upon the successful association setup a SCTP_COMM_UP notification 522 will be dispatched to the socket at both the sender and receiver 523 side. This notification can be read by the recvmsg() system call 524 (see Section 3.1.3). 526 Note, if the SCTP stack at the sender side supports bundling, the 527 first user message may be bundled with the COOKIE ECHO message 528 RFC2960 [RFC2960]. 530 When the SCTP stack sets up a new association implicitly, it first 531 consults the sctp_initmsg structure, which is passed along within the 532 ancillary data in the sendmsg() call (see Section 5.2.1 for details 533 of the data structures), for any special options to be used on the 534 new association. 536 If this information is not present in the sendmsg() call, or if the 537 implicit association setup is triggered by a sendto() call, the 538 default association initialization parameters will be used. These 539 default association parameters may be set with respective 540 setsockopt() calls or be left to the system defaults. 542 Implicit association setup cannot be initiated by send()/recv() 543 calls. 545 3.3. Non-blocking mode 547 Some SCTP users might want to avoid blocking when they call socket 548 interface function. 550 Once all bind() calls are complete on a one-to-many style socket, the 551 application must set the non-blocking option by a fcntl() (such as 552 O_NONBLOCK). After which the sendmsg() function returns immediately, 553 and the success or failure of the data message (and possible 554 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 555 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 556 be sent (due to a CANT_START_ASSOC), the sender will also receive a 557 SCTP_SEND_FAILED event. Those event(s) can be received by the user 558 calling of recvmsg(). A server (having called listen()) is also 559 notified of an association up event by the reception of a 560 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 561 possibly the reception of the first data message. 563 In order to shutdown the association gracefully, the user must call 564 sendmsg() with no data and with the SCTP_EOF flag set. The function 565 returns immediately, and completion of the graceful shutdown is 566 indicated by an SCTP_ASSOC_CHANGE notification of type 567 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be 568 done using the sctp_send() call described in Section 8.10. 570 An application is recommended to use caution when using select() (or 571 poll()) for writing on a one-to-many style socket. The reason being 572 that interpretation of select on write is implementation specific. 573 Generally a positive return on a select on write would only indicate 574 that one of the associations represented by the one-to-many socket is 575 writable. An application that writes after the select return may 576 still block since the association that was writeable is not the 577 destination association of the write call. Likewise select (or 578 poll()) for reading from a one-to-many socket will only return an 579 indication that one of the associations represented by the socket has 580 data to be read. 582 An application that wishes to know that a particular association is 583 ready for reading or writing should either use the one-to-one style 584 or use the sctp_peelloff() (see Section 8.2) function to seperate the 585 association of interest from the one-to-many socket. 587 3.4. Special considerations 589 The fact that a one-to-many style socket can provide access to many 590 SCTP associations through a single socket descriptor has important 591 implications for both application programmers and system programmers 592 implementing this API. A key issue is how buffer space inside the 593 sockets layer is managed. Because this implementation detail 594 directly affects how application programmers must write their code to 595 ensure correct operation and portability, this section provides some 596 guidance to both implementors and application programmers. 598 An important feature that SCTP shares with TCP is flow control: 599 specifically, a sender may not send data faster than the receiver can 600 consume it. 602 For TCP, flow control is typically provided for in the sockets API as 603 follows. If the reader stops reading, the sender queues messages in 604 the socket layer until it uses all of its socket buffer space 605 allocation creating a "stalled connection". Further attempts to 606 write to the socket will block or return the error EAGAIN or 607 EWOULDBLOCK for a non-blocking socket. At some point, either the 608 connection is closed, or the receiver begins to read again freeing 609 space in the output queue. 611 For one-to-one style SCTP sockets (this includes sockets descriptors 612 that were separated from a one-to-many style socket with 613 sctp_peeloff()) the behavior is identical. For one-to-many style 614 SCTP sockets, the fact that we have multiple associations on a single 615 socket makes the situation more complicated. If the implementation 616 uses a single buffer space allocation shared by all associations, a 617 single stalled association can prevent the further sending of data on 618 all associations active on a particular one-to-many style socket. 620 For a blocking socket, it should be clear that a single stalled 621 association can block the entire socket. For this reason, 622 application programmers may want to use non-blocking one-to-many 623 style sockets. The application should at least be able to send 624 messages to the non-stalled associations. 626 But a non-blocking socket is not sufficient if the API implementor 627 has chosen a single shared buffer allocation for the socket. A 628 single stalled association would eventually cause the shared 629 allocation to fill, and it would become impossible to send even to 630 non-stalled associations. 632 The API implementor can solve this problem by providing each 633 association with its own allocation of outbound buffer space. Each 634 association should conceptually have as much buffer space as it would 635 have if it had its own socket. As a bonus, this simplifies the 636 implementation of sctp_peeloff(). 638 To ensure that a given stalled association will not prevent other 639 non-stalled associations from being writable, application programmers 640 should either: 642 (a) demand that the underlying implementation dedicates independent 643 buffer space allotments to each association (as suggested above), 644 or 645 (b) verify that their application layer protocol does not permit 646 large amounts of unread data at the receiver (this is true of some 647 request-response protocols, for example), or 648 (c) use one-to-one style sockets for association which may 649 potentially stall (either from the beginning, or by using 650 sctp_peeloff before sending large amounts of data that may cause a 651 stalled condition). 652 An implemenation which dedicates independent buffer space for each 653 association should define HAVE_SCTP_MULTIBUF to 1. 655 4. one-to-one style Interface 657 The goal of this style is to follow as closely as possible the 658 current practice of using the sockets interface for a connection 659 oriented protocol, such as TCP. This style enables existing 660 applications using connection oriented protocols to be ported to SCTP 661 with very little effort. 663 Note that some new SCTP features and some new SCTP socket options can 664 only be utilized through the use of sendmsg() and recvmsg() calls, 665 see Section 4.1.8. Also note that some socket interfaces may not be 666 able to provide data on the third leg of the association set up with 667 this interface style. 669 4.1. Basic Operation 671 A typical server in one-to-one style uses the following system call 672 sequence to prepare an SCTP endpoint for servicing requests: 674 1. socket() 676 2. bind() 678 3. listen() 680 4. accept() 682 The accept() call blocks until a new association is set up. It 683 returns with a new socket descriptor. The server then uses the new 684 socket descriptor to communicate with the client, using recv() and 685 send() calls to get requests and send back responses. 687 Then it calls 688 5. close() 690 to terminate the association. 692 A typical client uses the following system call sequence to setup an 693 association with a server to request services: 695 1. socket() 697 2. connect() 699 After returning from connect(), the client uses send() and recv() 700 calls to send out requests and receive responses from the server. 702 The client calls 704 3. close() 706 to terminate this association when done. 708 4.1.1. socket() - one-to-one style socket 710 Applications calls socket() to create a socket descriptor to 711 represent an SCTP endpoint. 713 The syntax is: 715 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 717 or, 719 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 721 Here, SOCK_STREAM indicates the creation of a one-to-one style 722 socket. 724 The first form creates an endpoint which can use only IPv4 addresses, 725 while the second form creates an endpoint which can use both IPv6 and 726 IPv4 addresses. 728 4.1.2. bind() - one-to-one style socket 730 Applications use bind() to pass an address to be associated with an 731 SCTP endpoint to the system. bind() allows only either a single 732 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 733 endpoint can be associated with multiple addresses. To do this, 734 sctp_bindx() is introduced in Section 8.1 to help applications do the 735 job of associating multiple addresses. 737 These addresses associated with a socket are the eligible transport 738 addresses for the endpoint to send and receive data. The endpoint 739 will also present these addresses to its peers during the association 740 initialization process, see RFC2960 [RFC2960]. 742 The syntax is: 744 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 746 sd: the socket descriptor returned by socket() call. 747 addr: the address structure (either struct sockaddr_in or struct 748 sockaddr_in6 defined in RFC2553 [RFC2553]). 749 addrlen: the size of the address structure. 751 If sd is an IPv4 socket, the address passed must be an IPv4 address. 752 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 753 either be an IPv4 or an IPv6 address. 755 Applications cannot call bind() multiple times to associate multiple 756 addresses to the endpoint. After the first call to bind(), all 757 subsequent calls will return an error. 759 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 760 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 761 operating system will associate the endpoint with an optimal address 762 set of the available interfaces. 764 If a bind() is not called prior to the connect() call, the system 765 picks an ephemeral port and will choose an address set equivalent to 766 binding with a wildcard address. One of those addresses will be the 767 primary address for the association. This automatically enables the 768 multi-homing capability of SCTP. 770 The completion of this bind() process does not ready the SCTP 771 endpoint to accept inbound SCTP association requests. Until a 772 listen() system call, described below, is performed on the socket, 773 the SCTP endpoint will promptly reject an inbound SCTP INIT request 774 with an SCTP ABORT. 776 4.1.3. listen() - one-to-one style socket 778 Applications use listen() to ready the SCTP endpoint for accepting 779 inbound associations. 781 The syntax is: 783 int listen(int sd, int backlog); 784 sd: the socket descriptor of the SCTP endpoint. 785 backlog: this specifies the max number of outstanding associations 786 allowed in the socket's accept queue. These are the associations 787 that have finished the four-way initiation handshake (see Section 788 5 of RFC2960 [RFC2960]) and are in the ESTABLISHED state. Note, a 789 backlog of '0' indicates that the caller no longer wishes to 790 receive new associations. 792 4.1.4. accept() - one-to-one style socket 794 Applications use accept() call to remove an established SCTP 795 association from the accept queue of the endpoint. A new socket 796 descriptor will be returned from accept() to represent the newly 797 formed association. 799 The syntax is: 801 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 803 new_sd - the socket descriptor for the newly formed association. 804 sd - the listening socket descriptor. 805 addr - on return, will contain the primary address of the peer 806 endpoint. 807 addrlen - on return, will contain the size of addr. 809 4.1.5. connect() - one-to-one style socket 811 Applications use connect() to initiate an association to a peer. 813 The syntax is: 815 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 817 sd - the socket descriptor of the endpoint. 818 addr - the peer's address. 819 addrlen - the size of the address. 821 This operation corresponds to the ASSOCIATE primitive described in 822 section 10.1 of RFC2960 [RFC2960]. 824 By default, the new association created has only one outbound stream. 825 The SCTP_INITMSG option described in Section 7.1.3 should be used 826 before connecting to change the number of outbound streams. 828 If a bind() is not called prior to the connect() call, the system 829 picks an ephemeral port and will choose an address set equivalent to 830 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 831 respectively. One of those addresses will be the primary address for 832 the association. This automatically enables the multi-homing 833 capability of SCTP. 835 Note that SCTP allows data exchange, similar to T/TCP RFC1644 836 [RFC1644], during the association set up phase. If an application 837 wants to do this, it cannot use connect() call. Instead, it should 838 use sendto() or sendmsg() to initiate an association. If it uses 839 sendto() and it wants to change initialization behavior, it needs to 840 use the SCTP_INITMSG socket option before calling sendto(). Or it 841 can use SCTP_INIT type sendmsg() to initiate an association without 842 doing the setsockopt(). Note that some sockets implementations may 843 not support the sending of data to initiate an assocation with the 844 one-to-one style (implementations that do not support T/TCP normally 845 have this restriction). Implementations which allow sending of data 846 to initiate an association without calling connect() define the 847 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 849 SCTP does not support half close semantics. This means that unlike 850 T/TCP, MSG_EOF should not be set in the flags parameter when calling 851 sendto() or sendmsg() when the call is used to initiate a connection. 852 MSG_EOF is not an acceptable flag with SCTP socket. 854 4.1.6. close() - one-to-one style socket 856 Applications use close() to gracefully close down an association. 858 The syntax is: 860 int close(int sd); 862 sd - the socket descriptor of the association to be closed. 864 After an application calls close() on a socket descriptor, no further 865 socket operations will succeed on that descriptor. 867 4.1.7. shutdown() - one-to-one style socket 869 SCTP differs from TCP in that it does not have half closed semantics. 870 Hence the shutdown() call for SCTP is an approximation of the TCP 871 shutdown() call, and solves some different problems. Full TCP- 872 compatibility is not provided, so developers porting TCP applications 873 to SCTP may need to recode sections that use shutdown(). (Note that 874 it is possible to achieve the same results as half close in SCTP 875 using SCTP streams.) 877 The syntax is: 879 int shutdown(int sd, int how); 881 sd - the socket descriptor of the association to be closed. 882 how - Specifies the type of shutdown. The values are as follows: 883 SHUT_RD - Disables further receive operations. No SCTP protocol 884 action is taken. 885 SHUT_WR - Disables further send operations, and initiates the SCTP 886 shutdown sequence. 887 SHUT_RDWR - Disables further send and receive operations and 888 initiates the SCTP shutdown sequence. 890 The major difference between SCTP and TCP shutdown() is that SCTP 891 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 892 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 893 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 894 the SCTP association while still leaving the socket descriptor open, 895 so that the caller can receive back any data SCTP was unable to 896 deliver (see Section 5.3.1.4 for more information). 898 To perform the ABORT operation described in RFC2960 [RFC2960] section 899 10.1, an application can use the socket option SO_LINGER. It is 900 described in Section 7.1.4. 902 4.1.8. sendmsg() and recvmsg() - one-to-one style socket 904 With a one-to-one style socket, the application can also use 905 sendmsg() and recvmsg() to transmit data to and receive data from its 906 peer. The semantics is similar to those used in the one-to-many 907 style (section Section 3.1.3), with the following differences: 909 1) When sending, the msg_name field in the msghdr is not used to 910 specify the intended receiver, rather it is used to indicate a 911 preferred peer address if the sender wishes to discourage the stack 912 from sending the message to the primary address of the receiver. If 913 the transport address given is not part of the current association, 914 the data will not be sent and a SCTP_SEND_FAILED event will be 915 delivered to the application if send failure events are enabled. 917 4.1.9. getpeername() 919 Applications use getpeername() to retrieve the primary socket address 920 of the peer. This call is for TCP compatibility, and is not multi- 921 homed. It does not work with one-to-many style sockets. See 922 Section 8.3 for a multi-homed/one-to-many style version of the call. 924 The syntax is: 926 int getpeername(int sd, struct sockaddr *address, 927 socklen_t *len); 929 sd - the socket descriptor to be queried. 930 address - On return, the peer primary address is stored in this 931 buffer. If the socket is an IPv4 socket, the address will be 932 IPv4. If the socket is an IPv6 socket, the address will be either 933 an IPv6 or IPv4 address. 934 len - The caller should set the length of address here. On return, 935 this is set to the length of the returned address. 937 If the actual length of the address is greater than the length of the 938 supplied sockaddr structure, the stored address will be truncated. 940 5. Data Structures 942 We discuss in this section important data structures which are 943 specific to SCTP and are used with sendmsg() and recvmsg() calls to 944 control SCTP endpoint operations and to access ancillary information 945 and notifications. 947 5.1. The msghdr and cmsghdr Structures 949 The msghdr structure used in the sendmsg() and recvmsg() calls, as 950 well as the ancillary data carried in the structure, is the key for 951 the application to set and get various control information from the 952 SCTP endpoint. 954 The msghdr and the related cmsghdr structures are defined and 955 discussed in details in RFC2292 [RFC2292]. Here we will cite their 956 definitions from RFC2292 [RFC2292]. 958 The msghdr structure: 960 struct msghdr { 961 void *msg_name; /* ptr to socket address structure */ 962 socklen_t msg_namelen; /* size of socket address structure */ 963 struct iovec *msg_iov; /* scatter/gather array */ 964 size_t msg_iovlen; /* # elements in msg_iov */ 965 void *msg_control; /* ancillary data */ 966 socklen_t msg_controllen; /* ancillary data buffer length */ 967 int msg_flags; /* flags on received message */ 968 }; 970 The cmsghdr structure: 972 struct cmsghdr { 973 socklen_t cmsg_len; /* #bytes, including this header */ 974 int cmsg_level; /* originating protocol */ 975 int cmsg_type; /* protocol-specific type */ 976 /* followed by unsigned char cmsg_data[]; */ 977 }; 979 In the msghdr structure, the usage of msg_name has been discussed in 980 previous sections (see Section 3.1.3 and Section 4.1.8). 982 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 983 field) are treated as a single SCTP data chunk, rather than multiple 984 chunks, for both sendmsg() and recvmsg(). 986 The msg_flags are not used when sending a message with sendmsg(). 988 If a notification has arrived, recvmsg() will return the notification 989 with the MSG_NOTIFICATION flag set in msg_flags. If the 990 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 991 Section 5.3 for more information about notifications. 993 If all portions of a data frame or notification have been read, 994 recvmsg() will return with MSG_EOR set in msg_flags. 996 5.2. SCTP msg_control Structures 998 A key element of all SCTP-specific socket extensions is the use of 999 ancillary data to specify and access SCTP-specific data via the 1000 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1001 Fine-grained control over initialization and sending parameters are 1002 handled with ancillary data. 1004 Each ancillary data item is proceeded by a struct cmsghdr (see 1005 Section 5.1), which defines the function and purpose of the data 1006 contained in in the cmsg_data[] member. 1008 There are two kinds of ancillary data used by SCTP: initialization 1009 data, and, header information (SNDRCV). Initialization data (one-to- 1010 many style only) sets protocol parameters for new associations. 1011 Section 5.2.1 provides more details. Header information can set or 1012 report parameters on individual messages in a stream. See 1013 Section 5.2.2 for how to use SNDRCV ancillary data. 1015 By default on a one-to-one style socket, SCTP will pass no ancillary 1016 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1017 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1018 be enabled with socket options defined for SCTP; see Section 7.3. 1020 Note that all ancillary types are fixed length; see Section 5.4 for 1021 further discussion on this. These data structures use struct 1022 sockaddr_storage (defined in RFC2553 [RFC2553]) as a portable, fixed 1023 length address format. 1025 Other protocols may also provide ancillary data to the socket layer 1026 consumer. These ancillary data items from other protocols may 1027 intermingle with SCTP data. For example, the IPv6 socket API 1028 definitions (RFC2292 [RFC2292] and RFC2553 [RFC2553]) define a number 1029 of ancillary data items. If a socket API consumer enables delivery 1030 of both SCTP and IPv6 ancillary data, they both may appear in the 1031 same msg_control buffer in any order. An application may thus need 1032 to handle other types of ancillary data besides that passed by SCTP. 1034 The sockets application must provide a buffer large enough to 1035 accommodate all ancillary data provided via recvmsg(). If the buffer 1036 is not large enough, the ancillary data will be truncated and the 1037 msghdr's msg_flags will include MSG_CTRUNC. 1039 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1041 This cmsghdr structure provides information for initializing new SCTP 1042 associations with sendmsg(). The SCTP_INITMSG socket option uses 1043 this same data structure. This structure is not used for recvmsg(). 1045 cmsg_level cmsg_type cmsg_data[] 1046 ------------ ------------ ---------------------- 1047 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1049 Here is the definition of the sctp_initmsg structure: 1051 struct sctp_initmsg { 1052 uint16_t sinit_num_ostreams; 1053 uint16_t sinit_max_instreams; 1054 uint16_t sinit_max_attempts; 1055 uint16_t sinit_max_init_timeo; 1056 }; 1058 sinit_num_ostreams: 16 bits (unsigned integer) 1060 This is an integer number representing the number of streams that the 1061 application wishes to be able to send to. This number is confirmed 1062 in the SCTP_COMM_UP notification and must be verified since it is a 1063 negotiated number with the remote endpoint. The default value of 0 1064 indicates to use the endpoint default value. 1066 sinit_max_instreams: 16 bits (unsigned integer) 1067 This value represents the maximum number of inbound streams the 1068 application is prepared to support. This value is bounded by the 1069 actual implementation. In other words the user MAY be able to 1070 support more streams than the Operating System. In such a case, the 1071 Operating System limit overrides the value requested by the user. 1072 The default value of 0 indicates to use the endpoint's default value. 1074 sinit_max_attempts: 16 bits (unsigned integer) 1076 This integer specifies how many attempts the SCTP endpoint should 1077 make at resending the INIT. This value overrides the system SCTP 1078 'Max.Init.Retransmits' value. The default value of 0 indicates to 1079 use the endpoint's default value. This is normally set to the 1080 system's default 'Max.Init.Retransmit' value. 1082 sinit_max_init_timeo: 16 bits (unsigned integer) 1084 This value represents the largest Time-Out or RTO value (in 1085 milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is 1086 used to limit the doubling of the RTO upon timeout. For the INIT 1087 message this value MAY override 'RTO.Max'. This value MUST NOT 1088 influence 'RTO.Max' during data transmission and is only used to 1089 bound the initial setup time. A default value of 0 indicates to use 1090 the endpoint's default value. This is normally set to the system's 1091 'RTO.Max' value (60 seconds). 1093 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1095 This cmsghdr structure specifies SCTP options for sendmsg() and 1096 describes SCTP header information about a received message through 1097 recvmsg(). 1099 cmsg_level cmsg_type cmsg_data[] 1100 ------------ ------------ ---------------------- 1101 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1103 Here is the definition of sctp_sndrcvinfo: 1105 struct sctp_sndrcvinfo { 1106 uint16_t sinfo_stream; 1107 uint16_t sinfo_ssn; 1108 uint16_t sinfo_flags; 1109 uint32_t sinfo_ppid; 1110 uint32_t sinfo_context; 1111 uint32_t sinfo_timetolive; 1112 uint32_t sinfo_tsn; 1113 uint32_t sinfo_cumtsn; 1114 sctp_assoc_t sinfo_assoc_id; 1116 }; 1118 sinfo_stream: 16 bits (unsigned integer) 1120 For recvmsg() the SCTP stack places the message's stream number in 1121 this value. For sendmsg() this value holds the stream number that 1122 the application wishes to send this message to. If a sender 1123 specifies an invalid stream number an error indication is returned 1124 and the call fails. 1126 sinfo_ssn: 16 bits (unsigned integer) 1128 For recvmsg() this value contains the stream sequence number that the 1129 remote endpoint placed in the DATA chunk. For fragmented messages 1130 this is the same number for all deliveries of the message (if more 1131 than one recvmsg() is needed to read the message). The sendmsg() 1132 call will ignore this parameter. 1134 sinfo_ppid: 32 bits (unsigned integer) 1136 This value in sendmsg() is an unsigned integer that is passed to the 1137 remote end in each user message. In recvmsg() this value is the same 1138 information that was passed by the upper layer in the peer 1139 application. Please note that the SCTP stack performs no byte order 1140 modification of this field. For example, if the DATA chunk has to 1141 contain a given value in network byte order, the SCTP user has to 1142 perform the htonl() computation. 1144 sinfo_context: 32 bits (unsigned integer) 1146 This value is an opaque 32 bit context datum that is used in the 1147 sendmsg() function. This value is passed back to the upper layer if 1148 a error occurs on the send of a message and is retrieved with each 1149 undelivered message (Note: if a endpoint has done multiple sends, all 1150 of which fail, multiple different sinfo_context values will be 1151 returned. One with each user data message). 1153 sinfo_flags: 16 bits (unsigned integer) 1155 This field may contain any of the following flags and is composed of 1156 a bitwise OR of these values. 1158 recvmsg() flags: 1160 SCTP_UNORDERED - This flag is present when the message was sent non- 1161 ordered. 1163 sendmsg() flags: 1164 SCTP_UNORDERED - This flag requests the un-ordered delivery of the 1165 message. If this flag is clear the datagram is considered an 1166 ordered send. 1167 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the 1168 SCTP stack to override the primary destination address with the 1169 address found with the sendto/sendmsg call. 1170 SCTP_ABORT - Setting this flag causes the specified association to 1171 abort by sending an ABORT message to the peer (one-to-many style 1172 only). The ABORT chunk will contain an error cause 'User 1173 Initiated Abort' with cause code 12. The cause specific 1174 information of this error cause is provided in msg_iov. 1175 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown 1176 procedures on the specified association. Graceful shutdown 1177 assures that all data enqueued by both endpoints is successfully 1178 transmitted before closing the association (one-to-many style 1179 only). 1180 SCTP_SENDALL - This flag, if set, will cause a one-to-many model 1181 socket to send the message to all associations that are currently 1182 established on this socket. For the one-to-one socket, this flag 1183 has no effect. 1185 sinfo_timetolive: 32 bit (unsigned integer) 1187 For the sending side, this field contains the message time to live in 1188 milliseconds. The sending side will expire the message within the 1189 specified time period if the message as not been sent to the peer 1190 within this time period. This value will override any default value 1191 set using any socket option. Also note that the value of 0 is 1192 special in that it indicates no timeout should occur on this message. 1194 sinfo_tsn: 32 bit (unsigned integer) 1196 For the receiving side, this field holds a TSN that was assigned to 1197 one of the SCTP Data Chunks. 1199 sinfo_cumtsn: 32 bit (unsigned integer) 1201 This field will hold the current cumulative TSN as known by the 1202 underlying SCTP layer. Note this field is ignored when sending and 1203 only valid for a receive operation when sinfo_flags are set to 1204 SCTP_UNORDERED. 1206 sinfo_assoc_id: sizeof (sctp_assoc_t) 1207 The association handle field, sinfo_assoc_id, holds the identifier 1208 for the association announced in the SCTP_COMM_UP notification. All 1209 notifications for a given association have the same identifier. 1210 Ignored for one-to-one style sockets. 1212 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1214 5.3. SCTP Events and Notifications 1216 An SCTP application may need to understand and process events and 1217 errors that happen on the SCTP stack. These events include network 1218 status changes, association startups, remote operational errors and 1219 undeliverable messages. All of these can be essential for the 1220 application. 1222 When an SCTP application layer does a recvmsg() the message read is 1223 normally a data message from a peer endpoint. If the application 1224 wishes to have the SCTP stack deliver notifications of non-data 1225 events, it sets the appropriate socket option for the notifications 1226 it wants. See Section 7.3 for these socket options. When a 1227 notification arrives, recvmsg() returns the notification in the 1228 application-supplied data buffer via msg_iov, and sets 1229 MSG_NOTIFICATION in msg_flags. 1231 This section details the notification structures. Every notification 1232 structure carries some common fields which provides general 1233 information. 1235 A recvmsg() call will return only one notification at a time. Just 1236 as when reading normal data, it may return part of a notification if 1237 the msg_iov buffer is not large enough. If a single read is not 1238 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1239 reading the notification before subsequent data can arrive. 1241 5.3.1. SCTP Notification Structure 1243 The notification structure is defined as the union of all 1244 notification types. 1246 union sctp_notification { 1247 struct { 1248 uint16_t sn_type; /* Notification type. */ 1249 uint16_t sn_flags; 1250 uint32_t sn_length; 1251 } sn_header; 1252 struct sctp_assoc_change sn_assoc_change; 1253 struct sctp_paddr_change sn_paddr_change; 1254 struct sctp_remote_error sn_remote_error; 1255 struct sctp_send_failed sn_send_failed; 1256 struct sctp_shutdown_event sn_shutdown_event; 1257 struct sctp_adaption_event sn_adaptation_event; 1258 struct sctp_pdapi_event sn_pdapi_event; 1259 struct sctp_authkey_event sn_auth_event; 1260 }; 1262 sn_type: 16 bits (unsigned integer) 1264 The following list describes the SCTP notification and event types 1265 for the field sn_type. 1267 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1268 been opened or closed. Refer to Section 5.3.1.1 for details. 1269 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1270 part of an existing association has experienced a change of state 1271 (e.g. a failure or return to service of the reachability of a 1272 endpoint via a specific transport address). Please see 1273 Section 5.3.1.2 for data structure details. 1274 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1275 received from the remote peer. It includes the complete TLV sent 1276 by the remote endpoint. See Section 5.3.1.3 for the detailed 1277 format. 1278 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1279 remote endpoint. This structure includes the original 1280 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1281 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1282 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1283 should be sent on this socket. 1284 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1285 indicated adaptation layer. Please see Section 5.3.1.6. 1286 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1287 receiver that the partial delivery has been aborted. This may 1288 indicate the association is about to be aborted. Please see 1289 Section 5.3.1.7 1291 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1292 receiver that either an error occured on authentication, or a new 1293 key was made active. Section 5.3.1.8 1295 All standard values for sn_type are greater than 2^15. Values from 1296 2^15 and down are reserved. 1298 sn_flags: 16 bits (unsigned integer) 1300 These are notification-specific flags. 1302 sn_length: 32 bits (unsigned integer) 1304 This is the length of the whole sctp_notification structure including 1305 the sn_type, sn_flags, and sn_length fields. 1307 5.3.1.1. SCTP_ASSOC_CHANGE 1309 Communication notifications inform the ULP that an SCTP association 1310 has either begun or ended. The identifier for a new association is 1311 provided by this notification. The notification information has the 1312 following format: 1314 struct sctp_assoc_change { 1315 uint16_t sac_type; 1316 uint16_t sac_flags; 1317 uint32_t sac_length; 1318 uint16_t sac_state; 1319 uint16_t sac_error; 1320 uint16_t sac_outbound_streams; 1321 uint16_t sac_inbound_streams; 1322 sctp_assoc_t sac_assoc_id; 1323 uint8_t sac_info[0]; 1324 }; 1326 sac_type: 1328 It should be SCTP_ASSOC_CHANGE. 1330 sac_flags: 16 bits (unsigned integer) 1332 Currently unused. 1334 sac_length: 32 bits (unsigned integer) 1336 This field is the total length of the notification data, including 1337 the notification header. 1339 sac_state: 16 bits (signed integer) 1341 This field holds one of a number of values that communicate the event 1342 that happened to the association. They include: 1344 Event Name Description 1346 ---------------- --------------- 1347 SCTP_COMM_UP - A new association is now ready and data may be 1348 exchanged with this peer. 1349 SCTP_COMM_LOST - The association has failed. The association is now 1350 in the closed state. If SEND FAILED notifications are turned on, 1351 a SCTP_COMM_LOST is followed by a series of SCTP_SEND_FAILED 1352 events, one for each outstanding message. 1353 SCTP_RESTART - SCTP has detected that the peer has restarted. 1354 SCTP_SHUTDOWN_COMP - The association has gracefully closed. 1355 SCTP_CANT_STR_ASSOC - The association failed to setup. If non 1356 blocking mode is set and data was sent (in the udp mode), a 1357 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED 1358 events, one for each outstanding message. 1360 sac_error: 16 bits (signed integer) 1362 If the state was reached due to a error condition (e.g. 1363 SCTP_COMM_LOST) any relevant error information is available in this 1364 field. This corresponds to the protocol error codes defined in 1365 RFC2960 [RFC2960]. 1367 sac_outbound_streams: 16 bits (unsigned integer) 1369 sac_inbound_streams: 16 bits (unsigned integer) 1371 The maximum number of streams allowed in each direction are available 1372 in sac_outbound_streams and sac_inbound streams. 1374 sac_assoc_id: sizeof (sctp_assoc_t) 1376 The association id field, holds the identifier for the association. 1377 All notifications for a given association have the same association 1378 identifier. For one-to-one style socket, this field is ignored. 1380 sac_info: variable 1382 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1383 for this association, sac_info[] contains the complete ABORT chunk as 1384 defined in the SCTP specification RFC2960 [RFC2960] section 3.3.7. 1386 5.3.1.2. SCTP_PEER_ADDR_CHANGE 1388 When a destination address on a multi-homed peer encounters a change 1389 an interface details event is sent. The information has the 1390 following structure: 1392 struct sctp_paddr_change { 1393 uint16_t spc_type; 1394 uint16_t spc_flags; 1395 uint32_t spc_length; 1396 struct sockaddr_storage spc_aaddr; 1397 uint32_t spc_state; 1398 uint32_t spc_error; 1399 sctp_assoc_t spc_assoc_id; 1400 } 1402 spc_type: 1404 It should be SCTP_PEER_ADDR_CHANGE. 1406 spc_flags: 16 bits (unsigned integer) 1408 Currently unused. 1410 spc_length: 32 bits (unsigned integer) 1412 This field is the total length of the notification data, including 1413 the notification header. 1415 spc_aaddr: sizeof (struct sockaddr_storage) 1417 The affected address field, holds the remote peer's address that is 1418 encountering the change of state. 1420 spc_state: 32 bits (signed integer) 1422 This field holds one of a number of values that communicate the event 1423 that happened to the address. They include: 1425 Event Name Description 1427 ---------------- --------------- 1428 SCTP_ADDR_AVAILABLE - This address is now reachable. 1430 SCTP_ADDR_UNREACHABLE - The address specified can no longer be 1431 reached. Any data sent to this address is rerouted to an 1432 alternate until this address becomes reachable. 1433 SCTP_ADDR_REMOVED - The address is no longer part of the association. 1434 SCTP_ADDR_ADDED - The address is now part of the association. 1435 SCTP_ADDR_MADE_PRIM - This address has now been made to be the 1436 primary destination address. 1438 spc_error: 32 bits (signed integer) 1440 If the state was reached due to any error condition (e.g. 1441 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1442 this field. 1444 spc_assoc_id: sizeof (sctp_assoc_t) 1446 The association id field, holds the identifier for the association. 1447 All notifications for a given association have the same association 1448 identifier. For one-to-one style socket, this field is ignored. 1450 5.3.1.3. SCTP_REMOTE_ERROR 1452 A remote peer may send an Operational Error message to its peer. 1453 This message indicates a variety of error conditions on an 1454 association. The entire ERROR chunk as it appears on the wire is 1455 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1456 specification RFC2960 [RFC2960] and any extensions for a list of 1457 possible error formats. SCTP error notifications have the format: 1459 struct sctp_remote_error { 1460 uint16_t sre_type; 1461 uint16_t sre_flags; 1462 uint32_t sre_length; 1463 uint16_t sre_error; 1464 sctp_assoc_t sre_assoc_id; 1465 uint8_t sre_data[0]; 1466 }; 1468 sre_type: 1470 It should be SCTP_REMOTE_ERROR. 1472 sre_flags: 16 bits (unsigned integer) 1474 Currently unused. 1476 sre_length: 32 bits (unsigned integer) 1478 This field is the total length of the notification data, including 1479 the notification header and the contents of sre_data. 1481 sre_error: 16 bits (unsigned integer) 1483 This value represents one of the Operational Error causes defined in 1484 the SCTP specification, in network byte order. 1486 sre_assoc_id: sizeof (sctp_assoc_t) 1488 The association id field, holds the identifier for the association. 1489 All notifications for a given association have the same association 1490 identifier. For one-to-one style socket, this field is ignored. 1492 sre_data: variable 1494 This contains the ERROR chunk as defined in the SCTP specification 1495 RFC2960 [RFC2960] section 3.3.10. 1497 5.3.1.4. SCTP_SEND_FAILED 1499 If SCTP cannot deliver a message it may return the message as a 1500 notification. 1502 struct sctp_send_failed { 1503 uint16_t ssf_type; 1504 uint16_t ssf_flags; 1505 uint32_t ssf_length; 1506 uint32_t ssf_error; 1507 struct sctp_sndrcvinfo ssf_info; 1508 sctp_assoc_t ssf_assoc_id; 1509 uint8_t ssf_data[0]; 1510 }; 1512 ssf_type: 1514 It should be SCTP_SEND_FAILED. 1516 The flag value will take one of the following values: 1518 SCTP_DATA_UNSENT - Indicates that the data was never put on the wire. 1519 SCTP_DATA_SENT - Indicates that the data was put on the wire. Note 1520 that this does not necessarily mean that the data was (or was not) 1521 successfully delivered. 1523 ssf_length: 32 bits (unsigned integer) 1525 This field is the total length of the notification data, including 1526 the notification header and the payload in ssf_data. 1528 ssf_error: 16 bits (unsigned integer) 1530 This value represents the reason why the send failed, and if set, 1531 will be a SCTP protocol error code as defined in RFC2960 [RFC2960] 1532 section 3.3.10. 1534 ssf_info: sizeof (struct sctp_sndrcvinfo) 1536 The original send information associated with the undelivered 1537 message. 1539 ssf_assoc_id: sizeof (sctp_assoc_t) 1541 The association id field, sf_assoc_id, holds the identifier for the 1542 association. All notifications for a given association have the same 1543 association identifier. For one-to-one style socket, this field is 1544 ignored. 1546 ssf_data: variable length 1548 The undelivered message, exactly as delivered by the caller to the 1549 original send*() call. 1551 5.3.1.5. SCTP_SHUTDOWN_EVENT 1553 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1554 inform the application that it should cease sending data. 1556 struct sctp_shutdown_event { 1557 uint16_t sse_type; 1558 uint16_t sse_flags; 1559 uint32_t sse_length; 1560 sctp_assoc_t sse_assoc_id; 1561 }; 1563 sse_type 1565 It should be SCTP_SHUTDOWN_EVENT 1566 sse_flags: 16 bits (unsigned integer) 1568 Currently unused. 1570 sse_length: 32 bits (unsigned integer) 1572 This field is the total length of the notification data, including 1573 the notification header. It will generally be sizeof (struct 1574 sctp_shutdown_event). 1576 sse_flags: 16 bits (unsigned integer) 1578 Currently unused. 1580 sse_assoc_id: sizeof (sctp_assoc_t) 1582 The association id field, holds the identifier for the association. 1583 All notifications for a given association have the same association 1584 identifier. For one-to-one style socket, this field is ignored. 1586 5.3.1.6. SCTP_ADAPTATION_INDICATION 1588 When a peer sends a Adaptation Layer Indication parameter , SCTP 1589 delivers this notification to inform the application that of the 1590 peers requested adaptation layer. 1592 struct sctp_adaptation_event { 1593 uint16_t sai_type; 1594 uint16_t sai_flags; 1595 uint32_t sai_length; 1596 uint32_t sai_adaptation_ind; 1597 sctp_assoc_t sai_assoc_id; 1598 }; 1600 sai_type 1602 It should be SCTP_ADAPTATION_INDICATION 1604 sai_flags: 16 bits (unsigned integer) 1606 Currently unused. 1608 sai_length: 32 bits (unsigned integer) 1610 This field is the total length of the notification data, including 1611 the notification header. It will generally be sizeof (struct 1612 sctp_adaptation_event). 1614 sai_adaptation_ind: 32 bits (unsigned integer) 1616 This field holds the bit array sent by the peer in the adaptation 1617 layer indication parameter. The bits are in network byte order. 1619 sai_assoc_id: sizeof (sctp_assoc_t) 1621 The association id field, holds the identifier for the association. 1622 All notifications for a given association have the same association 1623 identifier. For one-to-one style socket, this field is ignored. 1625 5.3.1.7. SCTP_PARTIAL_DELIVERY_EVENT 1627 When a receiver is engaged in a partial delivery of a message this 1628 notification will be used to indicate various events. 1630 struct sctp_pdapi_event { 1631 uint16_t pdapi_type; 1632 uint16_t pdapi_flags; 1633 uint32_t pdapi_length; 1634 uint32_t pdapi_indication; 1635 sctp_assoc_t pdapi_assoc_id; 1636 }; 1638 pdapi_type 1640 It should be SCTP_PARTIAL_DELIVERY_EVENT 1642 pdapi_flags: 16 bits (unsigned integer) 1644 Currently unused. 1646 pdapi_length: 32 bits (unsigned integer) 1648 This field is the total length of the notification data, including 1649 the notification header. It will generally be sizeof (struct 1650 sctp_pdapi_event). 1652 pdapi_indication: 32 bits (unsigned integer) 1654 This field holds the indication being sent to the application 1655 possible values include: 1657 SCTP_PARTIAL_DELIVERY_ABORTED 1659 pdapi_assoc_id: sizeof (sctp_assoc_t) 1661 The association id field, holds the identifier for the association. 1663 All notifications for a given association have the same association 1664 identifier. For one-to-one style socket, this field is ignored. 1666 5.3.1.8. SCTP_AUTHENTICATION_EVENT 1668 When a receiver is using authentication this message will provide 1669 notifications regarding new keys being made active as well as errors. 1671 struct sctp_authkey_event { 1672 uint16_t auth_type; 1673 uint16_t auth_flags; 1674 uint32_t auth_length; 1675 uint32_t auth_keynumber; 1676 uint32_t auth_altkeynumber; 1677 uint32_t auth_indication; 1678 sctp_assoc_t auth_assoc_id; 1679 }; 1681 auth_type 1683 It should be SCTP_AUTHENTICATION_EVENT 1685 auth_flags: 16 bits (unsigned integer) 1687 Currently unused. 1689 auth_length: 32 bits (unsigned integer) 1691 This field is the total length of the notification data, including 1692 the notification header. It will generally be sizeof (struct 1693 sctp_authkey_event). 1695 auth_keynumber: 32 bits (unsigned integer) 1697 This field holds the keynumber set by the user for the effected key. 1698 If more than one key is involved, this will contain one of the keys 1699 involved in the notification. 1701 auth_altkeynumber: 32 bits (unsigned integer) 1703 This field holds an alternate keynumber which is used by some 1704 notifications. 1706 auth_indication: 32 bits (unsigned integer) 1708 This field hold the error or indication being reported. The 1709 following values are currently defined: 1711 SCTP_AUTH_NEWKEY - this report indicates that a new key has been made 1712 active (used for the first time by the peer) and is now the active 1713 key. The auth_keynumber field holds the user specified key 1714 number. 1715 SCTP_KEY_CONFLICT - this report indicates that an association was 1716 attempting to be formed and that two seperate keys were discovered 1717 for the same peer endpoint. In other words, two distinct keys 1718 would have been active for the same association due to multi- 1719 homing. The field auth_keynumber contains one of the conflicting 1720 keys and the field auth_altkeynumber contains one of the other 1721 keys. Note that more than two key COULD be in conflict. 1723 auth_assoc_id: sizeof (sctp_assoc_t) 1725 The association id field, holds the identifier for the association. 1726 All notifications for a given association have the same association 1727 identifier. 1729 5.4. Ancillary Data Considerations and Semantics 1731 Programming with ancillary socket data contains some subtleties and 1732 pitfalls, which are discussed below. 1734 5.4.1. Multiple Items and Ordering 1736 Multiple ancillary data items may be included in any call to 1737 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1738 items, or both. 1740 The ordering of ancillary data items (either by SCTP or another 1741 protocol) is not significant and is implementation-dependent, so 1742 applications must not depend on any ordering. 1744 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1745 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1746 sendmsg() or recvmsg() call. 1748 5.4.2. Accessing and Manipulating Ancillary Data 1750 Applications can infer the presence of data or ancillary data by 1751 examining the msg_iovlen and msg_controllen msghdr members, 1752 respectively. 1754 Implementations may have different padding requirements for ancillary 1755 data, so portable applications should make use of the macros 1756 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1757 RFC2292 [RFC2292] and your SCTP implementation's documentation for 1758 more information. Following is an example, from RFC2292 [RFC2292], 1759 demonstrating the use of these macros to access ancillary data: 1761 struct msghdr msg; 1762 struct cmsghdr *cmsgptr; 1764 /* fill in msg */ 1766 /* call recvmsg() */ 1768 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1769 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1770 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1771 u_char *ptr; 1773 ptr = CMSG_DATA(cmsgptr); 1774 /* process data pointed to by ptr */ 1775 } 1776 } 1778 5.4.3. Control Message Buffer Sizing 1780 The information conveyed via SCTP_SNDRCV events will often be 1781 fundamental to the correct and sane operation of the sockets 1782 application. This is particularly true of the one-to-many semantics, 1783 but also of the one-ton-one semantics. For example, if an 1784 application needs to send and receive data on different SCTP streams, 1785 SCTP_SNDRCV events are indispensable. 1787 Given that some ancillary data is critical, and that multiple 1788 ancillary data items may appear in any order, applications should be 1789 carefully written to always provide a large enough buffer to contain 1790 all possible ancillary data that can be presented by recvmsg(). If 1791 the buffer is too small, and crucial data is truncated, it may pose a 1792 fatal error condition. 1794 Thus it is essential that applications be able to deterministically 1795 calculate the maximum required buffer size to pass to recvmsg(). One 1796 constraint imposed on this specification that makes this possible is 1797 that all ancillary data definitions are of a fixed length. One way 1798 to calculate the maximum required buffer size might be to take the 1799 sum the sizes of all enabled ancillary data item structures, as 1800 calculated by CMSG_SPACE. For example, if we enabled 1801 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [RFC2292], we would 1802 calculate and allocate the buffer size as follows: 1804 size_t total; 1805 void *buf; 1807 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1808 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1810 buf = malloc(total); 1812 We could then use this buffer for msg_control on each call to 1813 recvmsg() and be assured that we would not lose any ancillary data to 1814 truncation. 1816 6. Common Operations for Both Styles 1818 6.1. send(), recv(), sendto(), recvfrom() 1820 Applications can use send() and sendto() to transmit data to the peer 1821 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1822 data from the peer. 1824 The syntax is: 1826 ssize_t send(int sd, const void *msg, size_t len, int flags); 1827 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1828 const struct sockaddr *to, socklen_t tolen); 1829 ssize_t recv(int sd, void *buf, size_t len, int flags); 1830 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1831 struct sockaddr *from, socklen_t *fromlen); 1833 sd - the socket descriptor of an SCTP endpoint. 1834 msg - the message to be sent. 1835 len - the size of the message or the size of buffer. 1836 to - one of the peer addresses of the association to be used to send 1837 the message. 1838 tolen - the size of the address. 1839 buf - the buffer to store a received message. 1840 from - the buffer to store the peer address used to send the received 1841 message. 1842 fromlen - the size of the from address 1843 flags - (described below). 1845 These calls give access to only basic SCTP protocol features. If 1846 either peer in the association uses multiple streams, or sends 1847 unordered data these calls will usually be inadequate, and may 1848 deliver the data in unpredictable ways. 1850 SCTP has the concept of multiple streams in one association. The 1851 above calls do not allow the caller to specify on which stream a 1852 message should be sent. The system uses stream 0 as the default 1853 stream for send() and sendto(). recv() and recvfrom() return data 1854 from any stream, but the caller can not distinguish the different 1855 streams. This may result in data seeming to arrive out of order. 1856 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1857 provide no indication. 1859 SCTP is message based. The msg buffer above in send() and sendto() 1860 is considered to be a single message. This means that if the caller 1861 wants to send a message which is composed by several buffers, the 1862 caller needs to combine them before calling send() or sendto(). 1863 Alternately, the caller can use sendmsg() to do that without 1864 combining them. recv() and recvfrom() cannot distinguish message 1865 boundaries. 1867 In receiving, if the buffer supplied is not large enough to hold a 1868 complete message, the receive call acts like a stream socket and 1869 returns as much data as will fit in the buffer. 1871 Note, the send() and recv() calls may not be used for a one-to-many 1872 style socket. 1874 Note, if an application calls a send function with no user data and 1875 no ancillary data the SCTP implementation should reject the request 1876 with an appropriate error message. An implementation is NOT allowed 1877 to send a Data chunk with no user data RFC2960 [RFC2960]. 1879 6.2. setsockopt(), getsockopt() 1881 Applications use setsockopt() and getsockopt() to set or retrieve 1882 socket options. Socket options are used to change the default 1883 behavior of sockets calls. They are described in Section 7 1885 The syntax is: 1887 ret = getsockopt(int sd, int level, int optname, void *optval, 1888 socklen_t *optlen); 1889 ret = setsockopt(int sd, int level, int optname, const void *optval, 1890 socklen_t optlen); 1892 sd - the socket descriptor. 1893 level - set to IPPROTO_SCTP for all SCTP options. 1895 optname - the option name. 1896 optval - the buffer to store the value of the option. 1897 optlen - the size of the buffer (or the length of the option 1898 returned). 1900 6.3. read() and write() 1902 Applications can use read() and write() to send and receive data to 1903 and from peer. They have the same semantics as send() and recv() 1904 except that the flags parameter cannot be used. 1906 Note, these calls, when used in the one-to-many style, may only be 1907 used with branched off socket descriptors (see Section 8.2). 1909 6.4. getsockname() 1911 Applications use getsockname() to retrieve the locally-bound socket 1912 address of the specified socket. This is especially useful if the 1913 caller let SCTP chose a local port. This call is for where the 1914 endpoint is not multi-homed. It does not work well with multi-homed 1915 sockets. See Section 8.5 for a multi-homed version of the call. 1917 The syntax is: 1919 int getsockname(int sd, struct sockaddr *address, 1920 socklen_t *len); 1922 sd - the socket descriptor to be queried. 1923 address - On return, one locally bound address (chosen by the SCTP 1924 stack) is stored in this buffer. If the socket is an IPv4 socket, 1925 the address will be IPv4. If the socket is an IPv6 socket, the 1926 address will be either an IPv6 or IPv4 address. 1927 len - The caller should set the length of address here. On return, 1928 this is set to the length of the returned address. 1930 If the actual length of the address is greater than the length of the 1931 supplied sockaddr structure, the stored address will be truncated. 1933 If the socket has not been bound to a local name, the value stored in 1934 the object pointed to by address is unspecified. 1936 7. Socket Options 1938 The following sub-section describes various SCTP level socket options 1939 that are common to both styles. SCTP associations can be multi- 1940 homed. Therefore, certain option parameters include a 1941 sockaddr_storage structure to select which peer address the option 1942 should be applied to. 1944 For the one-to-many style sockets, an sctp_assoc_t structure 1945 (association ID) is used to identify the the association instance 1946 that the operation affects. So it must be set when using this style. 1948 For the one-to-one style sockets and branched off one-to-many style 1949 sockets (see Section 8.2) this association ID parameter is ignored. 1951 Note that socket or IP level options are set or retrieved per socket. 1952 This means that for one-to-many style sockets, those options will be 1953 applied to all associations belonging to the socket. And for one-to- 1954 one style, those options will be applied to all peer addresses of the 1955 association controlled by the socket. Applications should be very 1956 careful in setting those options. 1958 For some IP stacks getsockopt() is read-only; so a new interface will 1959 be needed when information must be passed both in to and out of the 1960 SCTP stack. The syntax for sctp_opt_info() is, 1962 int sctp_opt_info(int sd, 1963 sctp_assoc_t id, 1964 int opt, 1965 void *arg, 1966 socklen_t *size); 1968 The sctp_opt_info() call is a replacement for getsockopt() only and 1969 will not set any options associated with the specified socket. A 1970 setsockopt() must be used to set any writeable option. 1972 For one-to-many style sockets, id specifies the association to query. 1973 For one-to-one style sockets, id is ignored. 1975 opt specifies which SCTP socket option to get. It can get any socket 1976 option currently supported that requests information (either read/ 1977 write options or read only) such as: 1978 SCTP_RTOINFO 1979 SCTP_ASSOCINFO 1980 SCTP_DEFAULT_SEND_PARAM 1981 SCTP_GET_PEER_ADDR_INFO 1982 SCTP_PRIMARY_ADDR 1983 SCTP_PEER_ADDR_PARAMS 1984 SCTP_STATUS 1985 SCTP_AUTH_CHUNKS 1986 SCTP_AUTH_SECRET 1988 arg is an option-specific structure buffer provided by the caller. 1989 See Section 8.5) subsections for more information on these options 1990 and option-specific structures. 1992 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1993 sets errno to the appropriate error code. 1995 All options that support specific settings on an association by 1996 filling in either an association id variable or a sockaddr_storage 1997 SHOULD also support setting of the same value for the entire endpoint 1998 (i.e. future associations). To accomplish this the following logic 1999 is used when setting one of these options: 2001 a) If an address is specified via a sockaddr_storage that is included 2002 in the structure, the address is used to lookup the association 2003 and the settings are applied to the specific address (if 2004 appropriate) or to the entire association. 2005 b) If an association identification is filled in but not a 2006 sockaddr_storage (if present), the association is found using the 2007 association identification and the settings should be applied to 2008 the entire association (since a specific address is not 2009 specified). Note this also applies to options that hold an 2010 association identification in their structure but do not have a 2011 sockaddr_storage field. 2012 c) If neither the sockaddr_storage or association identification is 2013 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2014 the association identification is 0, the settings are a default 2015 and to be applied to the endpoint (all future associations). 2017 7.1. Read / Write Options 2019 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2021 The protocol parameters used to initialize and bound retransmission 2022 timeout (RTO) are tunable. See RFC2960 [RFC2960] for more 2023 information on how these parameters are used in RTO calculation. 2025 The following structure is used to access and modify these 2026 parameters: 2028 struct sctp_rtoinfo { 2029 sctp_assoc_t srto_assoc_id; 2030 uint32_t srto_initial; 2031 uint32_t srto_max; 2032 uint32_t srto_min; 2033 }; 2034 srto_initial - This contains the initial RTO value. 2035 srto_max and srto_min - These contain the maximum and minimum bounds 2036 for all RTOs. 2037 srto_assoc_id - (one-to-many style socket) This is filled in the 2038 application, and identifies the association for this query. If 2039 this parameter is '0' (on a one-to-many style socket), then the 2040 change effects the entire endpoint. 2042 All parameters are time values, in milliseconds. A value of 0, when 2043 modifying the parameters, indicates that the current value should not 2044 be changed. 2046 To access or modify these parameters, the application should call 2047 getsockopt or setsockopt() respectively with the option name 2048 SCTP_RTOINFO. 2050 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2052 This option is used to both examine and set various association and 2053 endpoint parameters. 2055 See RFC2960 [RFC2960] for more information on how this parameter is 2056 used. The peer address parameter is ignored for one-to-one style 2057 socket. 2059 The following structure is used to access and modify this parameters: 2061 struct sctp_assocparams { 2062 sctp_assoc_t sasoc_assoc_id; 2063 uint16_t sasoc_asocmaxrxt; 2064 uint16_t sasoc_number_peer_destinations; 2065 uint32_t sasoc_peer_rwnd; 2066 uint32_t sasoc_local_rwnd; 2067 uint32_t sasoc_cookie_life; 2068 }; 2070 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2071 to make for the association. 2072 sasoc_number_peer_destinations - This is the number of destination 2073 addresses that the peer has. 2074 sasoc_peer_rwnd - This holds the current value of the peers rwnd 2075 (reported in the last SACK) minus any outstanding data (i.e. data 2076 inflight). 2077 sasoc_local_rwnd - This holds the last reported rwnd that was sent to 2078 the peer. 2080 sasoc_cookie_life - This is the associations cookie life value used 2081 when issuing cookies. 2082 sasoc_assoc_id - This is filled in the application, and identifies 2083 the association for this query. 2085 This information may be examined for either the endpoint or a 2086 specific association. To examine a endpoints default parameters the 2087 association id (sasoc_assoc_id) should must be set to the value '0'. 2088 The values of the sasoc_peer_rwnd is meaningless when examining 2089 endpoint information. 2091 All parameters are time values, in milliseconds. A value of 0, when 2092 modifying the parameters, indicates that the current value should not 2093 be changed. 2095 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2096 on either an endpoint or association basis. The rwnd and destination 2097 counts (sasoc_number_peer_destinations, 2098 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2099 placed in these is ignored. 2101 To access or modify these parameters, the application should call 2102 getsockopt or setsockopt() respectively with the option name 2103 SCTP_ASSOCINFO. 2105 The maximum number of retransmissions before an address is considered 2106 unreachable is also tunable, but is address-specific, so it is 2107 covered in a separate option. If an application attempts to set the 2108 value of the association maximum retransmission parameter to more 2109 than the sum of all maximum retransmission parameters, setsockopt() 2110 shall return an error. The reason for this, from RFC2960 [RFC2960] 2111 section 8.2: 2113 Note: When configuring the SCTP endpoint, the user should avoid 2114 having the value of 'Association.Max.Retrans' larger than the 2115 summation of the 'Path.Max.Retrans' of all the destination addresses 2116 for the remote endpoint. Otherwise, all the destination addresses 2117 may become inactive while the endpoint still considers the peer 2118 endpoint reachable. 2120 7.1.3. Initialization Parameters (SCTP_INITMSG) 2122 Applications can specify protocol parameters for the default 2123 association initialization. The structure used to access and modify 2124 these parameters is defined in Section 5.2.1). The option name 2125 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2127 Setting initialization parameters is effective only on an unconnected 2128 socket (for one-to-many style sockets only future associations are 2129 effected by the change). With one-to-one style sockets, this option 2130 is inherited by sockets derived from a listener socket. 2132 7.1.4. SO_LINGER 2134 An application using the one-to-one style socket can use this option 2135 to perform the SCTP ABORT primitive. The linger option structure is: 2137 struct linger { 2138 int l_onoff; /* option on/off */ 2139 int l_linger; /* linger time */ 2140 }; 2142 To enable the option, set l_onoff to 1. If the l_linger value is set 2143 to 0, calling close() is the same as the ABORT primitive. If the 2144 value is set to a negative value, the setsockopt() call will return 2145 an error. If the value is set to a positive value linger_time, the 2146 close() can be blocked for at most linger_time ms. If the graceful 2147 shutdown phase does not finish during this period, close() will 2148 return but the graceful shutdown phase continues in the system. 2150 Note, this is a socket level option NOT an SCTP level option. So 2151 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2152 setsockopt() call. 2154 7.1.5. SCTP_NODELAY 2156 Turn on/off any Nagle-like algorithm. This means that packets are 2157 generally sent as soon as possible and no unnecessary delays are 2158 introduced, at the cost of more packets in the network. Expects an 2159 integer boolean flag. 2161 7.1.6. SO_RCVBUF 2163 Sets receive buffer size in octets. For SCTP one-to-one style 2164 sockets, this controls the receiver window size. For one-to-many 2165 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2166 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2167 as 1, this controls the receiver window size for each association 2168 bound to the socket descriptor. If the implementation defines 2169 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2170 buffer for the whole socket. The call expects an integer. 2172 7.1.7. SO_SNDBUF 2174 Sets send buffer size. For SCTP one-to-one style sockets, this 2175 controls the amount of data SCTP may have waiting in internal buffers 2176 to be sent. This option therefore bounds the maximum size of data 2177 that can be sent in a single send call. For one-to-many style 2178 sockets, the effect is the same, except that it applies to one or all 2179 associations (see Section 3.4) bound to the socket descriptor used in 2180 the setsockopt() or getsockopt() call. The option applies to each 2181 association's window size separately. The call expects an integer. 2183 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) 2185 This socket option is applicable to the one-to-many style socket 2186 only. When set it will cause associations that are idle for more 2187 than the specified number of seconds to automatically close using the 2188 graceful shutdown procedure. An association being idle is defined as 2189 an association that has NOT sent or received user data. The special 2190 value of '0' indicates that no automatic close of any associations 2191 should be performed, this is the default value. The option expects 2192 an integer defining the number of seconds of idle time before an 2193 association is closed. 2195 An application using this option should enable receiving the 2196 association change notification. This is the only mechanism an 2197 application is informed about the closing of an association. After 2198 an association is closed, the association ID assigned to it can be 2199 reused. An application should be aware of this to avoid the possible 2200 problem of sending data to an incorrect peer end point. 2202 7.1.9. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2204 Requests that the peer mark the enclosed address as the association 2205 primary. The enclosed address must be one of the association's 2206 locally bound addresses. The following structure is used to make a 2207 set primary request: 2209 struct sctp_setpeerprim { 2210 sctp_assoc_t sspp_assoc_id; 2211 struct sockaddr_storage sspp_addr; 2212 }; 2214 sspp_addr - The address to set as primary 2215 sspp_assoc_id - This is filled in by the application, and identifies 2216 the association for this request. 2218 This functionality is optional. Implementations that do not support 2219 this functionality should return EOPNOTSUPP. 2221 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) 2223 Requests that the local SCTP stack use the enclosed peer address as 2224 the association primary. The enclosed address must be one of the 2225 association peer's addresses. The following structure is used to 2226 make a set peer primary request: 2228 struct sctp_setprim { 2229 sctp_assoc_t ssp_assoc_id; 2230 struct sockaddr_storage ssp_addr; 2231 }; 2233 ssp_addr - The address to set as primary 2234 ssp_assoc_id - This is filled in by the application, and identifies 2235 the association for this request. 2237 7.1.11. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2239 Requests that the local endpoint set the specified Adaptation Layer 2240 Indication parameter for all future INIT and INIT-ACK exchanges. 2242 struct sctp_setadaptation { 2243 uint32_t ssb_adaptation_ind; 2244 }; 2246 ssb_adaptation_ind - The adaptation layer indicator that will be 2247 included in any outgoing Adaptation Layer Indication parameter 2249 7.1.12. Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2251 This option is a on/off flag and is passed an integer where a non- 2252 zero is on and a zero is off. If enabled no SCTP message 2253 fragmentation will be performed. Instead if a message being sent 2254 exceeds the current PMTU size, the message will NOT be sent and 2255 instead a error will be indicated to the user. 2257 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2259 Applications can enable or disable heartbeats for any peer address of 2260 an association, modify an address's heartbeat interval, force a 2261 heartbeat to be sent immediately, and adjust the address's maximum 2262 number of retransmissions sent before an address is considered 2263 unreachable. The following structure is used to access and modify an 2264 address's parameters: 2266 struct sctp_paddrparams { 2267 sctp_assoc_t spp_assoc_id; 2268 struct sockaddr_storage spp_address; 2269 uint32_t spp_hbinterval; 2270 uint16_t spp_pathmaxrxt; 2271 uint32_t spp_pathmtu; 2272 uint32_t spp_sackdelay; 2273 uint32_t spp_flags; 2274 uint32_t spp_ipv6_flowlabel; 2275 uint8_t spp_ipv4_tos; 2276 }; 2278 spp_assoc_id - (one-to-many style socket) This is filled in the 2279 application, and identifies the association for this query. 2280 spp_address - This specifies which address is of interest. 2281 spp_hbinterval - This contains the value of the heartbeat interval, 2282 in milliseconds. Note that unless the spp_flag is set to 2283 SPP_HB_ENABLE the value of this field is ignored. Note also that 2284 a value of zero indicates the current setting should be left 2285 unchanged. To set an actual value of zero the use of the flag 2286 SPP_HB_TIME_IS_ZERO should be used. 2287 spp_pathmaxrxt - This contains the maximum number of retransmissions 2288 before this address shall be considered unreachable. Note that 2289 unless the spp_flag is set to SPP_PMTUD_ENABLE the value of this 2290 field is ignored. Note also that a value of zero indicates the 2291 current setting should be left unchanged. 2292 spp_pathmtu - When Path MTU discovery is disabled the value specified 2293 here will be the "fixed" path mtu (i.e. the value of the spp_flags 2294 field must include the flag SPP_PMTUD_DISABLE for this field to 2295 have any effect). Note that if the spp_address field is empty 2296 then all associations on this address will have this fixed path 2297 mtu set upon them. If an address is specified, then only that 2298 address will be effected. 2299 spp_sackdelay - When delayed sack is enabled, this value specifies 2300 the number of milliseconds that sacks will be delayed for. This 2301 value will apply to all addresses of an association if the 2302 spp_address field is empty. Note that unless the spp_flag is set 2303 to SPP_SACKDELAY_ENABLE the value of this field is ignored. Note 2304 also that a value of zero indicates the current setting should be 2305 left unchanged. 2306 spp_ipv6_flowlabel- This field is used in conjunction with the 2307 SPP_IPV4_FLOWLABEL flag. 2308 spp_ipv4_tos- This field is used in conjunction with the SPP_IPV4_TOS 2309 flag. 2311 spp_flags- These flags are used to control various features on an 2312 association. The flag field may contain zero or more of the 2313 following options. 2315 SPP_HB_ENABLE - Enable heartbeats on the specified address. Note 2316 that if the address field is empty all addresses for the 2317 association have heartbeats enabled upon them. 2318 SPP_HB_DISABLE - Disable heartbeats on the speicifed address. 2319 Note that if the address field is empty all addresses for the 2320 association will have their heartbeats disabled. Note also 2321 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2322 only one of these two should be specified. Enabling both 2323 fields will have undetermined results. 2324 SPP_HB_DEMAND - Request a user initiated heartbeat to be made 2325 immediately. 2326 SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay 2327 is to be set to the value of 0 milliseconds. 2328 SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the 2329 specified address. Note that if the address feild is empty 2330 then all addresses on the association are effected. 2331 SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon 2332 the specified address. Note that if the address feild is empty 2333 then all addresses on the association are effected. Not also 2334 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2335 exclusive. Enabling both will have undetermined results. 2336 SPP_SACKDELAY_ENABLE - Setting this flag turns on delayed sack. 2337 The time specified in spp_sackdelay is used to specify the sack 2338 delay for this address. Note that if spp_address is empty then 2339 all addresses will enable delayed sack and take on the sack 2340 delay value specified in spp_sackdelay. 2341 SPP_SACKDELAY_DISABLE - Setting this flag turns off delayed sack. 2342 If the spp_address field is blank then delayed sack is disabled 2343 for the entire association. Note also that this field is 2344 mutually exclusive to SPP_SACKDELAY_ENABLE, setting both will 2345 have undefined results. 2346 SPP_IPV6_FLOWLABEL - Setting this flag enables setting of the IPV6 2347 flowlabel value associated with either the association or the 2348 specific address. If the address field is filled in, then the 2349 specific destination address has this value set upon it. If 2350 the association is specified, but not the address, then the 2351 flowlabel value is set for any future destination addresses 2352 that may be added. The value is obtained in the 2353 spp_ipv6_flowlabel field. 2355 Upon retrieval, this flag will be set to indicate that the 2356 spp_ipv6_flowlabel field has a valid value returned. If a 2357 specific destination addresses is set (in the spp_address 2358 field) when called then the value returned is that of the 2359 address. If just an assocaition is specified (and no address) 2360 then the association default flowlabel is returned. If neither 2361 an association nor an destination is specified, then the 2362 sockets default flowlabel is returned. For non IPv6 sockets, 2363 then this flag will be left cleared. 2364 SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos 2365 value associated with either the association or specific 2366 address. If the address field is filled in, then the specific 2367 destination address has this value set upon it. If the 2368 association is specified, but not the address, then the tos 2369 value is set for any future destination addresses that may be 2370 added. The value is obtained in the spp_ipv4_tos field. 2372 Upon retrieval, this flag will be set to indicate that the 2373 spp_ipv4_tos field has a valid value returned. If a specific 2374 destination addresses is set when called (in the spp_address 2375 field) then that specific destination addresses tos value is 2376 returned. If just an assocaition is specified then the 2377 association default tos is returned. If neither an association 2378 nor an destination is specified, then the sockets default tos 2379 is returned. For non IPv4 sockets, then this flag will be left 2380 cleared. 2382 To read or modify these parameters, the application should call 2383 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2385 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2387 Applications that wish to use the sendto() system call may wish to 2388 specify a default set of parameters that would normally be supplied 2389 through the inclusion of ancillary data. This socket option allows 2390 such an application to set the default sctp_sndrcvinfo structure. 2391 The application that wishes to use this socket option simply passes 2392 in to this call the sctp_sndrcvinfo structure defined in 2393 Section 5.2.2) The input parameters accepted by this call include 2394 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2395 sinfo_timetolive. The user must set the sinfo_assoc_id field to 2396 identify the association to affect if the caller is using the one-to- 2397 many style. 2399 7.1.15. Set notification and ancillary events (SCTP_EVENTS) 2401 This socket option is used to specify various notifications and 2402 ancillary data the user wishes to receive. Please see Section 7.3) 2403 for a full description of this option and its usage. 2405 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2407 This socket option is a boolean flag which turns on or off mapped V4 2408 addresses. If this option is turned on and the socket is type 2409 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2410 If this option is turned off, then no mapping will be done of V4 2411 addresses and a user will receive both PF_INET6 and PF_INET type 2412 addresses on the socket. 2414 By default this option is turned on and expects an integer to be 2415 passed where non-zero turns on the option and zero turns off the 2416 option. 2418 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) 2420 This socket option specifies the maximum size to put in any outgoing 2421 SCTP DATA chunk. If a message is larger than this size it will be 2422 fragmented by SCTP into the specified size. Note that the underlying 2423 SCTP implementation may fragment into smaller sized chunks when the 2424 PMTU of the underlying association is smaller than the value set by 2425 the user. The option expects an integer. 2427 The default value for this option is '0' which indicates the user is 2428 NOT limiting fragmentation and only the PMTU will effect SCTP's 2429 choice of DATA chunk size. 2431 7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK) 2433 This option adds a chunk type that the user is requesting to be 2434 received only in an authenticated way. Changes to the list of chunks 2435 will only effect associations that have not been formed. 2437 struct sctp_authchunks { 2438 uint8_t sauth_chunk; 2439 }; 2441 sauth_chunks - This parameter contains a chunk type 2442 that the user is requesting to be authenticated. 2444 The chunk types for INIT, INIT-ACK, COOKIE-ECHO, COOKIE-ACK, 2445 SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are 2446 used an error MUST be returned. The usage of this option enables 2447 SCTP-AUTH in cases where it is not required by other means (for 2448 example the use of ADD-IP). 2450 7.1.19. Set the endpoint pair shared key (SCTP_AUTH_KEY) 2452 This option will set the endpoint pair shared key which is used to 2453 build the association shared key. 2455 struct sctp_authkey { 2456 sctp_assoc_t sca_assoc_id; 2457 uint32_t sca_keynumber; 2458 struct sockaddr_storage sca_address; 2459 uint8_t sca_key[]; 2460 }; 2462 sca_assoc_id - This parameter, if non-zero, indicates what 2463 association that the shared key is being set upon. Note that if 2464 this element contains zero, then the secret is set upon the 2465 endpoint and all future associations will use this secret (if not 2466 changed by subsequent calls to SCTP_AUTH_KEY). 2467 sca_address - this parameter contains either a zero filled address, 2468 in which case it has no effect on the call. Or this parameter may 2469 contain an existing association. An address may also be specified 2470 for a future association including the IP layer address and the 2471 transport port, or just the IP layer address. Note that if 2472 multiple keys are defined for addresses of the same endpoint (for 2473 a multihomed endpoint) then an error will be returned and NO 2474 association will be formed on recipt of the INIT or INIT-ACK. 2475 sca_keynumber - this parameter is the key index by which the 2476 application will refer to this key. If a key of the specified 2477 index already exists, then this new key will replace the old key. 2478 sca_key - This parameter contains an array of bytes that is to be 2479 used by the endpoint (or association) as the shared secret. 2481 7.1.20. Get the list of chunks the peer requires to be authenticated 2482 (SCTP_PEER_AUTH_CHUNKS) 2484 This option gets a list of chunks for a specified association that 2485 the peer requires to be received authenticated only. 2487 struct sctp_authchunks { 2488 sctp_assoc_t gauth_assoc_id; 2489 uint8_t gauth_chunks[]; 2490 }; 2491 gauth_assoc_id - This parameter, indicates for which association the 2492 user is requesting the list of peer authenticated chunks. 2493 gauth_chunks - This parameter contains an array of chunks that the 2494 peer is requesting to be authenticated. 2496 7.1.21. Get the list of chunks the local endpoint requires to be 2497 authenticated (SCTP_LOCAL_AUTH_CHUNKS) 2499 This option gets a list of chunks for a specified association that 2500 the local endpoint requires to be received authenticated only. 2502 struct sctp_authchunks { 2503 sctp_assoc_t gauth_assoc_id; 2504 uint8_t gauth_chunks[]; 2505 }; 2507 gauth_assoc_id - This parameter, indicates for which association the 2508 user is requesting the list of local authenticated chunks. 2509 gauth_chunks - This parameter contains an array of chunks that the 2510 local endpoint is requesting to be authenticated. 2512 7.1.22. Set the list of supported HMAC Identifiers (SCTP_HMAC_IDENT) 2514 This option sets a list of algorithms for a specified association 2515 that the local endpoint requires the peer to use. 2517 struct sctp_hmacalgo { 2518 sctp_assoc_t shmac_assoc_id; 2519 uint32_t shmac_idents[]; 2520 }; 2522 shmac_assoc_id - This parameter, indicates for which association the 2523 user is setting the list of HMAC Identifiers. 2524 shmac_idents - This parameter contains an array of HMAC Identifiers 2525 that the local endpoint is requesting the peer to use. 2527 7.1.23. Get or set the active key (SCTP_AUTH_SETKEY_ACTIVE) 2529 This options will get or set the active key. 2531 struct sctp_authkey { 2532 sctp_assoc_t scact_assoc_id; 2533 uint32_t scact_keynumber; 2534 uint32_t scact_sec_old; 2535 uint32_t scact_sec_new; 2536 struct sockaddr_storage scact_address; 2538 }; 2540 scact_assoc_id - This parameter, if non-zero, indicates what 2541 association that the shared key is being set upon. Note that if 2542 this element contains zero, then the secret activation applys to 2543 the endpoint and all future associations will use this secret (if 2544 not changed by subsequent calls). 2545 scact_address - this parameter contains either a zero filled address, 2546 in which case it has no effect on the call. Or this parameter may 2547 contain an existing association address. An address may also be 2548 specified for a future association including the IP layer address 2549 and the transport port, or just the IP layer address. Note that 2550 if multiple keys are defined for addresses of the same endpoint 2551 (for a multihomed endpoint) then an error will be returned and NO 2552 association will be formed on recipt of the INIT or INIT-ACK. 2553 scact_keynumber - this parameter is the key index by which the 2554 application will refer to this key. If a key of the specified 2555 index already exists, then this new key will replace the old key. 2556 scact_sec_old - this parameter list the number of seconds for which 2557 both keys will be accepted. If this value is 0, then the new key 2558 is made active immediately and packets with the old key will be 2559 discarded. If this value is non-zero, then for the specified time 2560 in seconds both keys will be accepted. 2561 scact_sec_new - this parameter indicates the number of seconds until 2562 the new key will start being used as the active key. If this 2563 value is '0' then the new key will start being used immediately. 2564 If this value is non-zero then the specified number of seconds 2565 will be delayed until new chunks being transmitted begin using the 2566 new key. 2568 7.1.24. Get or set delayed ack timer (SCTP_DELAYED_ACK_TIME) 2570 This options will get or set the delayed ack timer. The time is set 2571 in milliseconds. If the assoc_id is 0, then this sets or gets the 2572 endpoints default delayed ack timer value. If the assoc_id field is 2573 non-zero, then the set or get effects the specified association. 2575 struct sctp_assoc_value { 2576 sctp_assoc_t assoc_id; 2577 uint32_t assoc_value; 2578 }; 2580 assoc_id - This parameter, indicates which association the user is 2581 preforming an action upon. Note that if this field's value is 2582 zero then the endpoints default value is changed (effecting future 2583 associations only). 2584 assoc_value - This parameter contains the number of milliseconds that 2585 the user is requesting the delayed ACK timer be set to. Note that 2586 this value is defined in the standard to be between 200 and 500 2587 milliseconds. 2589 7.1.25. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE) 2591 This options will at a minimum specify if the implementation is doing 2592 fragmented interleave. Fragmented interleave, for a one to many 2593 socket, is when subsequent calls to receive a message may return 2594 parts of messages from different associations. Some implementations 2595 may allow you to turn this value on or off. If so, when turned off, 2596 no fragment interleave will occur (which will cause a head of line 2597 blocking amongst multiple associations sharing the same one to many 2598 socket). When this option is turned on, then each receive call may 2599 come from a different association (thus the user must receive data 2600 with the extended calls (e.g. sctp_recvmsg) to keep track of which 2601 association each receive belongs to. 2603 This option takes a boolean value. A non-zero value indicates that 2604 fragmented interleave is on. A value of zero indicates that 2605 fragmented interleave is off. 2607 Note that it is important that an implementation that allows this 2608 option to be turned on, have it off by default. Otherwise an unaware 2609 application using the one to many model may become confused and act 2610 incorrectly. 2612 7.1.26. Set or Get the sctp partial delivery point 2613 (SCTP_PARTIAL_DELIVERY_POINT) 2615 This option will set or get the SCTP partial delivery point. This 2616 point is the size of a message where the partial delivery API will be 2617 invoked to help free up rwnd space for the peer. Setting this to a 2618 lower value will cause partial delivery's to happen more often. The 2619 call's argument is an integer that sets or gets the partial delivery 2620 point. 2622 7.2. Read-Only Options 2624 7.2.1. Association Status (SCTP_STATUS) 2626 Applications can retrieve current status information about an 2627 association, including association state, peer receiver window size, 2628 number of unacked data chunks, and number of data chunks pending 2629 receipt. This information is read-only. The following structure is 2630 used to access this information: 2632 struct sctp_status { 2633 sctp_assoc_t sstat_assoc_id; 2634 int32_t sstat_state; 2635 uint32_t sstat_rwnd; 2636 uint16_t sstat_unackdata; 2637 uint16_t sstat_penddata; 2638 uint16_t sstat_instrms; 2639 uint16_t sstat_outstrms; 2640 uint32_t sstat_fragmentation_point; 2641 struct sctp_paddrinfo sstat_primary; 2642 }; 2644 sstat_state - This contains the association's current state one of 2645 the following values: 2646 SCTP_CLOSED 2647 SCTP_BOUND 2648 SCTP_LISTEN 2649 SCTP_COOKIE_WAIT 2650 SCTP_COOKIE_ECHOED 2651 SCTP_ESTABLISHED 2652 SCTP_SHUTDOWN_PENDING 2653 SCTP_SHUTDOWN_SENT 2654 SCTP_SHUTDOWN_RECEIVED 2655 SCTP_SHUTDOWN_ACK_SENT 2656 sstat_rwnd - This contains the association peer's current receiver 2657 window size. 2658 sstat_unackdata - This is the number of unacked data chunks. 2659 sstat_penddata - This is the number of data chunks pending receipt. 2660 sstat_primary - This is information on the current primary peer 2661 address. 2662 sstat_assoc_id - (one-to-many style socket) This holds the an 2663 identifier for the association. All notifications for a given 2664 association have the same association identifier. 2666 sstat_instrms - The number of streams that the peer will be using 2667 inbound. 2668 sstat_outstrms - The number of streams that the endpoint is allowed 2669 to use outbound. 2670 sstat_fragmentation_point - The size at which SCTP fragmentation will 2671 occur. 2673 To access these status values, the application calls getsockopt() 2674 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2675 ignored for one-to-one style socket. 2677 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2679 Applications can retrieve information about a specific peer address 2680 of an association, including its reachability state, congestion 2681 window, and retransmission timer values. This information is read- 2682 only. The following structure is used to access this information: 2684 struct sctp_paddrinfo { 2685 sctp_assoc_t spinfo_assoc_id; 2686 struct sockaddr_storage spinfo_address; 2687 int32_t spinfo_state; 2688 uint32_t spinfo_cwnd; 2689 uint32_t spinfo_srtt; 2690 uint32_t spinfo_rto; 2691 uint32_t spinfo_mtu; 2692 }; 2694 spinfo_address - This is filled in the application, and contains the 2695 peer address of interest. 2697 On return from getsockopt(): 2698 spinfo_state - This contains the peer addresses's state (either 2699 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifer 2700 SCTP_UNCONFIRMED) 2701 spinfo_cwnd - This contains the peer addresses's current congestion 2702 window. 2703 spinfo_srtt - This contains the peer addresses's current smoothed 2704 round-trip time calculation in milliseconds. 2705 spinfo_rto - This contains the peer addresses's current 2706 retransmission timeout value in milliseconds. 2707 spinfo_mtu - The current P-MTU of this address. 2709 spinfo_assoc_id - (one-to-many style socket) This is filled in the 2710 application, and identifies the association for this query. 2712 To retrieve this information, use sctp_opt_info() with the 2713 SCTP_GET_PEER_ADDR_INFO options. 2715 7.3. Ancillary Data and Notification Interest Options 2717 Applications can receive per-message ancillary information and 2718 notifications of certain SCTP events with recvmsg(). 2720 The following optional information is available to the application: 2722 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 2723 stream number, TSN, SSN, etc. described in Section 5.2.2) 2724 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 2725 Section 5.3.1.1) 2726 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in 2727 Section 5.3.1.2) 2728 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in 2729 Section 5.3.1.4) 2730 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in 2731 Section 5.3.1.3) 2732 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in 2733 Section 5.3.1.5) 2734 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 2735 (described in Section 5.3.1.7) 2736 8. SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): 2737 (described in Section 5.3.1.6) 2738 9. SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event): 2739 (described in Section 5.3.1.8) 2741 To receive any ancillary data or notifications, first the application 2742 registers it's interest by calling the SCTP_EVENTS setsockopt() with 2743 the following structure. 2745 struct sctp_event_subscribe{ 2746 uint8_t sctp_data_io_event; 2747 uint8_t sctp_association_event; 2748 uint8_t sctp_address_event; 2749 uint8_t sctp_send_failure_event; 2750 uint8_t sctp_peer_error_event; 2751 uint8_t sctp_shutdown_event; 2752 uint8_t sctp_partial_delivery_event; 2753 uint8_t sctp_adaptation_layer_event; 2754 uint8_t sctp_authentication_event; 2755 }; 2756 sctp_data_io_event - Setting this flag to 1 will cause the reception 2757 of SCTP_SNDRCV information on a per message basis. The application 2758 will need to use the recvmsg() interface so that it can receive the 2759 event information contained in the msg_control field. Please see 2760 Section 5.2 for further details. Setting the flag to 0 will disable 2761 reception of the message control information. 2763 sctp_association_event - Setting this flag to 1 will enable the 2764 reception of association event notifications. Setting the flag to 0 2765 will disable association event notifications. For more information 2766 on event notifications please see Section 5.3. 2768 sctp_address_event - Setting this flag to 1 will enable the reception 2769 of address event notifications. Setting the flag to 0 will disable 2770 address event notifications. For more information on event 2771 notifications please see Section 5.3. 2773 sctp_send_failure_event - Setting this flag to 1 will enable the 2774 reception of send failure event notifications. Setting the flag to 0 2775 will disable send failure event notifications. For more information 2776 on event notifications please see Section 5.3. 2778 sctp_peer_error_event - Setting this flag to 1 will enable the 2779 reception of peer error event notifications. Setting the flag to 0 2780 will disable peer error event notifications. For more information on 2781 event notifications please see Section 5.3. 2783 sctp_shutdown_event - Setting this flag to 1 will enable the 2784 reception of shutdown event notifications. Setting the flag to 0 2785 will disable shutdown event notifications. For more information on 2786 event notifications please see Section 5.3. 2788 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2789 reception of partial delivery notifications. Setting the flag to 0 2790 will disable partial delivery event notifications. For more 2791 information on event notifications please see Section 5.3. 2793 sctp_adaptation_layer_event - Setting this flag to 1 will enable the 2794 reception of adaptation layer notifications. Setting the flag to 0 2795 will disable adaptation layer event notifications. For more 2796 information on event notifications please see Section 5.3. 2798 sctp_authentication_event - Setting this flag to 1 will enable the 2799 receiption of authentication layer notifications. Setting the flag 2800 to 0 will disable authentication layer event notifications. For More 2801 information please see Section 5.3. 2803 An example where an application would like to receive data io events 2804 and association events but no others would be as follows: 2806 { 2807 struct sctp_event_subscribe event; 2809 memset(&event,0,sizeof(event)); 2811 event.sctp_data_io_event = 1; 2812 event.sctp_association_event = 1; 2814 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 2815 } 2817 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2818 receives ancillary data and notifications for ALL associations bound 2819 to the file descriptor. For one-to-one style SCTP sockets, the 2820 caller receives ancillary data and notifications for only the single 2821 association bound to the file descriptor. 2823 By default both the one-to-one style and one-to-many style socket has 2824 all options off. 2826 8. New Interfaces 2828 Depending on the system, the following interface can be implemented 2829 as a system call or library function. 2831 8.1. sctp_bindx() 2833 The syntax of sctp_bindx() is, 2835 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 2836 int flags); 2838 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2839 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2840 or IPv6 addresses. 2842 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2843 Section 3.1.2 for this usage. 2845 addrs is a pointer to an array of one or more socket addresses. Each 2846 address is contained in its appropriate structure. For an IPv6 2847 socket, an array of sockaddr_in6 would be returned. For a IPv4 2848 socket, an array of sockaddr_in would be returned. The caller 2849 specifies the number of addresses in the array with addrcnt. Note 2850 that the wildcard addresses cannot be used with this function, doing 2851 so will result in an error. 2853 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2854 -1, and sets errno to the appropriate error code. 2856 For SCTP, the port given in each socket address must be the same, or 2857 sctp_bindx() will fail, setting errno to EINVAL. 2859 The flags parameter is formed from the bitwise OR of zero or more of 2860 the following currently defined flags: 2862 SCTP_BINDX_ADD_ADDR 2864 SCTP_BINDX_REM_ADDR 2866 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2867 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2868 addresses from the association. The two flags are mutually 2869 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2870 caller may not remove all addresses from an association; sctp_bindx() 2871 will reject such an attempt with EINVAL. 2873 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2874 additional addresses with an endpoint after calling bind(). Or use 2875 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2876 socket is associated with so that no new association accepted will be 2877 associated with those addresses. If the endpoint supports dynamic 2878 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2879 endpoint to send the appropriate message to the peer to change the 2880 peers address lists. 2882 Adding and removing addresses from a connected association is 2883 optional functionality. Implementations that do not support this 2884 functionality should return EOPNOTSUPP. 2886 8.2. Branched-off Association 2888 After an association is established on a one-to-many style socket, 2889 the application may wish to branch off the association into a 2890 separate socket/file descriptor. 2892 This is particularly desirable when, for instance, the application 2893 wishes to have a number of sporadic message senders/receivers remain 2894 under the original one-to-many style socket but branch off those 2895 associations carrying high volume data traffic into their own 2896 separate socket descriptors. 2898 The application uses sctp_peeloff() call to branch off an association 2899 into a separate socket (Note the semantics are somewhat changed from 2900 the traditional one-to-one style accept() call). Note that the new 2901 socket is a one-to-one style socket. Thus it will be confined to 2902 operations allowed for a one-to-one style socket. 2904 The syntax is: 2906 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 2908 the new socket descriptor representing the branched-off 2909 association. 2910 the original one-to-many style socket descriptor returned from the 2911 socket() system call (see Section 3.1.1). 2912 the specified identifier of the association that is to be branched 2913 off to a separate file descriptor (Note, in a traditional one-to- 2914 one style accept() call, this would be an out parameter, but for 2915 the one-to-many style call, this is an in parameter). 2917 8.3. sctp_getpaddrs() 2919 sctp_getpaddrs() returns all peer addresses in an association. The 2920 syntax is, 2922 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2923 struct sockaddr **addrs); 2925 On return, addrs will point to an array dynamically allocated 2926 sockaddr structures of the appropriate type for the socket type. The 2927 caller should use sctp_freepaddrs() to free the memory. Note that 2928 the in/out parameter addrs must not be NULL. 2930 If sd is an IPv4 socket, the addresses returned will be all IPv4 2931 addresses. If sd is an IPv6 socket, the addresses returned can be a 2932 mix of IPv4 or IPv6 addresses. 2934 For one-to-many style sockets, id specifies the association to query. 2935 For one-to-one style sockets, id is ignored. 2937 On success, sctp_getpaddrs() returns the number of peer addresses in 2938 the association. If there is no association on this socket, 2939 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2940 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2941 is undefined. 2943 8.4. sctp_freepaddrs() 2944 sctp_freepaddrs() frees all resources allocated by 2945 sctp_getpaddrs(). Its syntax is, 2947 void sctp_freepaddrs(struct sockaddr *addrs); 2948 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2950 8.5. sctp_getladdrs() 2952 sctp_getladdrs() returns all locally bound address(es) on a socket. 2953 The syntax is, 2955 int sctp_getladdrs(int sd, sctp_assoc_t id, 2956 struct sockaddr **ss); 2958 On return, addrs will point to a dynamically allocated array of 2959 sockaddr structures of the appropriate type for the socket type. The 2960 caller should use sctp_freeladdrs() to free the memory. Note that 2961 the in/out parameter addrs must not be NULL. 2963 If sd is an IPv4 socket, the addresses returned will be all IPv4 2964 addresses. If sd is an IPv6 socket, the addresses returned can be a 2965 mix of IPv4 or IPv6 addresses. 2967 For one-to-many style sockets, id specifies the association to query. 2968 For one-to-one style sockets, id is ignored. 2970 If the id field is set to the value '0' then the locally bound 2971 addresses are returned without regard to any particular association. 2973 On success, sctp_getladdrs() returns the number of local addresses 2974 bound to the socket. If the socket is unbound, sctp_getladdrs() 2975 returns 0, and the value of *addrs is undefined. If an error occurs, 2976 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2978 8.6. sctp_freeladdrs() 2980 sctp_freeladdrs() frees all resources allocated by 2981 sctp_getladdrs(). Its syntax is, 2983 void sctp_freeladdrs(struct sockaddr *addrs); 2985 addrs is the array of peer addresses returned by sctp_getladdrs(). 2987 8.7. sctp_sendmsg() 2989 An implementation may provide a library function (or possibly system 2990 call) to assist the user with the advanced features of SCTP. 2992 sctp_sendmsg(). Its syntax is, 2994 ssize_t sctp_sendmsg(int sd, 2995 const void *msg, 2996 size_t len, 2997 const struct sockaddr *to, 2998 socklen_t tolen, 2999 uint32_t ppid, 3000 uint32_t flags, 3001 uint16_t stream_no, 3002 uint32_t timetolive, 3003 uint32_t context) 3005 sd - is the socket descriptor 3006 msg - is the message to be sent. 3007 len - is the length of the message. 3008 to - is the destination address of the message. 3009 tolen - is the length of the destination address. 3010 ppid - is the same as sinfo_ppid (see section 5.2.2) 3011 flags - is the same as sinfo_flags (see section 5.2.2) 3012 stream_no - is the same as sinfo_stream (see section 5.2.2) 3013 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 3014 context - is the same as sinfo_context (see section 5.2.2) 3016 8.8. sctp_recvmsg() 3018 An implementation may provide a library function (or possibly system 3019 call) to assist the user with the advanced features of SCTP. Note 3020 that in order for the sctp_sndrcvinfo structure to be filled in by 3021 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3022 the SCTP_EVENTS option. 3024 sctp_recvmsg(). Its syntax is, 3026 ssize_t sctp_recvmsg(int sd, 3027 void *msg, 3028 size_t len, 3029 struct sockaddr *from, 3030 socklen_t *fromlen 3031 struct sctp_sndrcvinfo *sinfo 3032 int *msg_flags) 3034 sd - is the socket descriptor 3035 msg - is a message buffer to be filled. 3036 len - is the length of the message buffer. 3037 from - is a pointer to a address to be filled with the sender of this 3038 messages address. 3039 fromlen - is the from length. 3040 sinfo - A pointer to a sctp_sndrcvinfo structure to be filled upon 3041 receipt of the message. 3042 msg_flags - A pointer to a integer to be filled with any message 3043 flags (e.g. MSG_NOTIFICATION). 3045 8.9. sctp_connectx() 3047 An implementation may provide a library function (or possibly system 3048 call) to assist the user with associating to an endpoint that is 3049 multi-homed. Much like sctp_bindx() this call allows a caller to 3050 specify multiple addresses at which a peer can be reached. The way 3051 the SCTP stack uses the list of addresses to set up the association 3052 is implementation dependant. This function only specifies that the 3053 stack will try to make use of all the addresses in the list when 3054 needed. 3056 Note that the list of addresses passed in is only used for setting up 3057 the association. It does not necessarily equal the set of addresses 3058 the peer uses for the resulting association. If the caller wants to 3059 find out the set of peer addresses, it must use sctp_getpaddrs() to 3060 retrieve them after the association has been set up. 3062 sctp_connectx(). Its syntax is, 3064 int sctp_connectx(int sd, 3065 struct sockaddr *addrs, 3066 int addrcnt) 3068 sd - is the socket descriptor 3069 addrs - is an array of addresses. 3070 addrcnt - is the number of addresses in the array. 3072 8.10. sctp_send() 3074 An implementation may provide another alternative function or system 3075 call to assist an application with the sending of data without the 3076 use of the CMSG header structures. The function takes the following 3077 form: 3079 sctp_send(). Its syntax is, 3081 int sctp_send(int sd, 3082 const void *msg, 3083 size_t len, 3084 const struct sctp_sndrcvinfo *sinfo, 3085 int flags); 3087 sd - is the socket descriptor 3088 msg - The message to be sent 3089 len - The length of the message 3090 sinfo - A pointer to a sctp_sndrcvinfo struture used as described in 3091 5.2.2 for a sendmsg call. 3092 flags - is used in the same format as the sendmsg call flags (e.g. 3093 MSG_DONTROUTE). 3095 This function call may also be used to terminate an association using 3096 an association identification by setting the sinfo.sinfo_flags to 3097 SCTP_EOF and the sinfo.sinf_associd to the association that needs to 3098 be terminated. In such a case the len of the message would be zero. 3100 8.11. sctp_sendx() 3102 An implementation may provide another alternative function or system 3103 call to assist an application with the sending of data without the 3104 use of the CMSG header structures that also gives a list of 3105 addresses. The list of addresses is provided for implicit 3106 association setup. In such a case the list of addresses serves the 3107 same purpose as the addresses given in sctp_connectx (see 3108 Section 8.9). 3110 sctp_sendx(). Its syntax is, 3112 int sctp_sendx(int sd, 3113 const void *msg, 3114 size_t len, 3115 struct sockaddr *addrs, 3116 int addrcnt, 3117 struct sctp_sndrcvinfo *sinfo, 3118 int flags); 3120 sd - is the socket descriptor 3121 msg - The message to be sent 3122 len - The length of the message 3123 addrs - is an array of addresses. 3124 addrcnt - is the number of addresses in the array. 3125 sinfo - A pointer to a sctp_sndrcvinfo struture used as described in 3126 5.2.2 for a sendmsg call. 3127 flags - is used in the same format as the sendmsg call flags (e.g. 3128 MSG_DONTROUTE). 3130 Note that on return from this call the sinfo structure will have 3131 changed in that the sinfo_assoc_id will be filled in with the new 3132 association id. 3134 This function call may also be used to terminate an association using 3135 an association identification by setting the sinfo.sinfo_flags to 3136 SCTP_EOF and the sinfo.sinfo_associd to the association that needs to 3137 be terminated. In such a case the len of the message would be zero. 3139 8.12. sctp_getaddrlen 3141 For application binary portability it is sometimes desireable to know 3142 what the kernel thinks is the length of a socket address family. 3143 This function, when called with a valid family type will return the 3144 length that the operating system uses in the specified family's 3145 socket address structure. 3147 int sctp_getaddrlen(sa_family_t family); 3149 9. Preprocessor Constants 3151 For application portability it is desireable to define pre-processor 3152 constants for determination if sctp is present and supports various 3153 features. The following pre-processor constants should be defined in 3154 a include file, sctp.h. 3155 HAVE_SCTP - If this constant is defined to 1, then an implementation 3156 of SCTP is available. 3157 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 3158 SCTP implementation is available through the sockets interface. 3159 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 3160 implementation supports the partial reliablility extension to 3161 SCTP. 3163 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 3164 implementation supports the dynamic address extension to SCTP. 3165 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the 3166 SCTP implementation supports the ability to request setting of the 3167 remote primary address. 3168 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 3169 then the SCTP implementation supports the satellite network 3170 extension to SCTP. 3171 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 3172 implementation dedicates separate buffer space to each association 3173 on a one-to-many socket. If this constant is defined to 0, then 3174 the implementation provides a single block of shared buffer space 3175 for a one-to-many socket. 3176 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP 3177 implementation supports initiating an association on a one-to-one 3178 style socket without the use of connect(), as outlined in 3179 Section 4.1.5. 3181 10. IANA considerations 3183 This document contains no IANA considerations. 3185 11. Security Considerations 3187 Many TCP and UDP implementations reserve port numbers below 1024 for 3188 privileged users. If the target platform supports privileged users, 3189 the SCTP implementation SHOULD restrict the ability to call bind() or 3190 sctp_bindx() on these port numbers to privileged users. 3192 Similarly unpriviledged users should not be able to set protocol 3193 parameters which could result in the congestion control algorithm 3194 being more aggressive than permitted on the public Internet. These 3195 parameters are: 3197 struct sctp_rtoinfo 3199 If an unprivileged user inherits a one-to-many style socket with open 3200 associations on a privileged port, it MAY be permitted to accept new 3201 associations, but it SHOULD NOT be permitted to open new 3202 associations. This could be relevant for the r* family of protocols. 3204 12. Acknowledgments 3206 Special acknowledgment is given to Ken Fujita and Jonathan Woods who 3207 helped extensively in the early formation of this document. 3209 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3210 Berger, Mark Butler, Scott Kimble, Renee Revis, and many others on 3211 the TSVWG mailing list for contributing valuable comments. 3213 A special thanks to Phillip Conrad, for his suggested text, quick and 3214 constructive insights, and most of all his persistent fighting to 3215 keep the interface to SCTP usable for the application programmer. 3217 13. References 3219 13.1. Normative references 3221 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3222 RFC 793, September 1981. 3224 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3225 August 1980. 3227 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3228 Functional Specification", RFC 1644, July 1994. 3230 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3231 3", BCP 9, RFC 2026, October 1996. 3233 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3234 Requirement Levels", BCP 14, RFC 2119, March 1997. 3236 [RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for 3237 IPv6", RFC 2292, February 1998. 3239 [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, 3240 "Basic Socket Interface Extensions for IPv6", RFC 2553, 3241 March 1999. 3243 [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., 3244 Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., 3245 Zhang, L., and V. Paxson, "Stream Control Transmission 3246 Protocol", RFC 2960, October 2000. 3248 13.2. Informational References 3250 Appendix A. one-to-one style Code Example 3252 The following code is a simple implementation of an echo server over 3253 SCTP. The example shows how to use some features of one-to-one style 3254 IPv4 SCTP sockets, including: 3256 o Opening, binding, and listening for new associations on a socket; 3257 o Enabling ancillary data 3258 o Enabling notifications 3259 o Using ancillary data with sendmsg() and recvmsg() 3260 o Using MSG_EOR to determine if an entire message has been read 3261 o Handling notifications 3263 #include 3264 #include 3265 #include 3266 #include 3267 #include 3268 #include 3269 #include 3270 #include 3271 #include 3273 #define BUFLEN 100 3275 static void 3276 handle_event(void *buf) 3277 { 3278 struct sctp_assoc_change *sac; 3279 struct sctp_send_failed *ssf; 3280 struct sctp_paddr_change *spc; 3281 struct sctp_remote_error *sre; 3282 union sctp_notification *snp; 3283 char addrbuf[INET6_ADDRSTRLEN]; 3284 const char *ap; 3285 struct sockaddr_in *sin; 3286 struct sockaddr_in6 *sin6; 3288 snp = buf; 3290 switch (snp->sn_header.sn_type) { 3291 case SCTP_ASSOC_CHANGE: 3292 sac = &snp->sn_assoc_change; 3293 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3294 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3295 sac->sac_inbound_streams, sac->sac_outbound_streams); 3296 break; 3297 case SCTP_SEND_FAILED: 3298 ssf = &snp->sn_send_failed; 3299 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3300 ssf->ssf_error); 3301 break; 3303 case SCTP_PEER_ADDR_CHANGE: 3305 spc = &snp->sn_paddr_change; 3306 if (spc->spc_aaddr.ss_family == AF_INET) { 3307 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3308 ap = inet_ntop(AF_INET, &sin->sin_addr, 3309 addrbuf, INET6_ADDRSTRLEN); 3310 } else { 3311 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3312 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3313 addrbuf, INET6_ADDRSTRLEN); 3314 } 3315 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3316 spc->spc_state, spc->spc_error); 3317 break; 3318 case SCTP_REMOTE_ERROR: 3319 sre = &snp->sn_remote_error; 3320 printf("^^^ remote_error: err=%hu len=%hu\n", 3321 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3322 break; 3323 case SCTP_SHUTDOWN_EVENT: 3324 printf("^^^ shutdown event\n"); 3325 break; 3326 default: 3327 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3328 break; 3329 }; 3330 } 3332 static void * 3333 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3334 ssize_t *nrp, size_t cmsglen) 3335 { 3336 ssize_t nr = 0, nnr = 0; 3337 struct iovec iov[1]; 3339 *nrp = 0; 3340 iov->iov_base = buf; 3341 iov->iov_len = *buflen; 3342 msg->msg_iov = iov; 3343 msg->msg_iovlen = 1; 3345 for (;;) { 3346 #ifndef MSG_XPG4_2 3347 #define MSG_XPG4_2 0 3348 #endif 3349 msg->msg_flags = MSG_XPG4_2; 3350 msg->msg_controllen = cmsglen; 3351 nnr = recvmsg(fd, msg, 0); 3352 if (nnr <= 0) { 3353 /* EOF or error */ 3354 *nrp = nr; 3355 return (NULL); 3356 } 3357 nr += nnr; 3359 if ((msg->msg_flags & MSG_EOR) != 0) { 3360 *nrp = nr; 3361 return (buf); 3362 } 3364 /* Realloc the buffer? */ 3365 if (*buflen == (size_t)nr) { 3366 buf = realloc(buf, *buflen * 2); 3367 if (buf == 0) { 3368 fprintf(stderr, "out of memory\n"); 3369 exit(1); 3370 } 3371 *buflen *= 2; 3372 } 3373 /* Set the next read offset */ 3374 iov->iov_base = (char *)buf + nr; 3375 iov->iov_len = *buflen - nr; 3376 } 3377 } 3379 static void 3380 echo(int fd, int socketModeone_to_many) 3381 { 3382 ssize_t nr; 3383 struct sctp_sndrcvinfo *sri; 3384 struct msghdr msg[1]; 3385 struct cmsghdr *cmsg; 3386 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3387 char *buf; 3388 size_t buflen; 3389 struct iovec iov[1]; 3390 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3391 /* Allocate the initial data buffer */ 3392 buflen = BUFLEN; 3393 if (!(buf = malloc(BUFLEN))) { 3394 fprintf(stderr, "out of memory\n"); 3395 exit(1); 3396 } 3398 /* Set up the msghdr structure for receiving */ 3399 memset(msg, 0, sizeof (*msg)); 3400 msg->msg_control = cbuf; 3401 msg->msg_controllen = cmsglen; 3402 msg->msg_flags = 0; 3403 cmsg = (struct cmsghdr *)cbuf; 3404 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3406 /* Wait for something to echo */ 3407 while (buf = mysctp_recvmsg(fd, msg, 3408 buf, &buflen, &nr, cmsglen)) { 3410 /* Intercept notifications here */ 3411 if (msg->msg_flags & MSG_NOTIFICATION) { 3412 handle_event(buf); 3413 continue; 3414 } 3416 iov->iov_base = buf; 3417 iov->iov_len = nr; 3418 msg->msg_iov = iov; 3419 msg->msg_iovlen = 1; 3421 printf("got %u bytes on stream %hu:\n", nr, 3422 sri->sinfo_stream); 3423 write(0, buf, nr); 3425 /* Echo it back */ 3426 msg->msg_flags = MSG_XPG4_2; 3427 if (sendmsg(fd, msg, 0) < 0) { 3428 perror("sendmsg"); 3429 exit(1); 3430 } 3431 } 3433 if (nr < 0) { 3434 perror("recvmsg"); 3435 } 3436 if(socketModeone_to_many == 0) 3437 close(fd); 3438 } 3440 int main() 3441 { 3442 struct sctp_event_subscribe event; 3443 int lfd, cfd; 3444 int onoff = 1; 3445 struct sockaddr_in sin[1]; 3446 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3447 perror("socket"); 3448 exit(1); 3449 } 3451 sin->sin_family = AF_INET; 3452 sin->sin_port = htons(7); 3453 sin->sin_addr.s_addr = INADDR_ANY; 3454 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3455 perror("bind"); 3456 exit(1); 3457 } 3459 if (listen(lfd, 1) == -1) { 3460 perror("listen"); 3461 exit(1); 3462 } 3464 /* Wait for new associations */ 3465 for (;;) { 3466 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3467 perror("accept"); 3468 exit(1); 3469 } 3471 /* Enable all events */ 3472 event.sctp_data_io_event = 1; 3473 event.sctp_association_event = 1; 3474 event.sctp_address_event = 1; 3475 event.sctp_send_failure_event = 1; 3476 event.sctp_peer_error_event = 1; 3477 event.sctp_shutdown_event = 1; 3478 event.sctp_partial_delivery_event = 1; 3479 event.sctp_adaptation_layer_event = 1; 3480 if (setsockopt(cfd, IPPROTO_SCTP, 3481 SCTP_EVENTS, &event, 3482 sizeof(event)) != 0) { 3483 perror("setevent failed"); 3484 exit(1); 3485 } 3486 /* Echo back any and all data */ 3487 echo(cfd,0); 3488 } 3489 } 3491 Appendix B. one-to-many style Code Example 3493 The following code is a simple implementation of an echo server over 3494 SCTP. The example shows how to use some features of one-to-many 3495 style IPv4 SCTP sockets, including: 3497 o Opening and binding of a socket; 3498 o Enabling ancillary data 3499 o Enabling notifications 3500 o Using ancillary data with sendmsg() and recvmsg() 3501 o Using MSG_EOR to determine if an entire message has been read 3502 o Handling notifications 3504 Note most functions defined in Appendix A are reused in this example. 3506 int main() 3507 { 3508 int fd; 3509 int idleTime = 2; 3510 struct sockaddr_in sin[1]; 3511 struct sctp_event_subscribe event; 3513 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3514 perror("socket"); 3515 exit(1); 3516 } 3518 sin->sin_family = AF_INET; 3519 sin->sin_port = htons(7); 3520 sin->sin_addr.s_addr = INADDR_ANY; 3521 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3522 perror("bind"); 3523 exit(1); 3524 } 3526 /* Enable all notifications and events */ 3527 event.sctp_data_io_event = 1; 3528 event.sctp_association_event = 1; 3529 event.sctp_address_event = 1; 3530 event.sctp_send_failure_event = 1; 3531 event.sctp_peer_error_event = 1; 3532 event.sctp_shutdown_event = 1; 3533 event.sctp_partial_delivery_event = 1; 3534 event.sctp_adaptation_layer_event = 1; 3535 if (setsockopt(fd, IPPROTO_SCTP, 3536 SCTP_EVENTS, &event, 3537 sizeof(event)) != 0) { 3538 perror("setevent failed"); 3539 exit(1); 3540 } 3541 /* Set associations to auto-close in 2 seconds of 3542 * inactivity 3543 */ 3544 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3545 &idleTime, 4) < 0) { 3546 perror("setsockopt SCTP_AUTOCLOSE"); 3547 exit(1); 3548 } 3550 /* Allow new associations to be accepted */ 3551 if (listen(fd, 1) < 0) { 3552 perror("listen"); 3553 exit(1); 3554 } 3556 /* Wait for new associations */ 3557 while(1){ 3558 /* Echo back any and all data */ 3559 echo(fd,1); 3560 } 3561 } 3563 Authors' Addresses 3565 Randall R. Stewart 3566 Cisco Systems, Inc. 3567 4875 Forest Drive 3568 Suite 200 3569 Columbia, SC 29206 3570 USA 3572 Phone: 3573 Email: rrs@cisco.com 3575 Qiaobing Xie 3576 Motorola, Inc. 3577 1501 W. Shure Drive, #2309 3578 Arlington Heights, IL 60004 3579 USA 3581 Phone: 3582 Email: qxie1@email.mot.com 3584 La Monte H.P. Yarroll 3585 TimeSys Corp 3586 925 Liberty Ave. 3587 Pittsburgh, PA 15222 3588 USA 3590 Phone: 3591 Email: piggy@acm.org 3593 Kacheong Poon 3594 Sun Microsystems, Inc. 3595 4150 Network Circle 3596 Santa Clara, CA 95054 3597 USA 3599 Phone: 3600 Email: kacheong.poon@sun.com 3601 Michael Tuexen 3602 Univ. of Applied Sciences Muenster 3603 Stegerwaldstr. 39 3604 48565 Steinfurt 3605 Germany 3607 Email: tuexen@fh-muenster.de 3609 Intellectual Property Statement 3611 The IETF takes no position regarding the validity or scope of any 3612 Intellectual Property Rights or other rights that might be claimed to 3613 pertain to the implementation or use of the technology described in 3614 this document or the extent to which any license under such rights 3615 might or might not be available; nor does it represent that it has 3616 made any independent effort to identify any such rights. Information 3617 on the procedures with respect to rights in RFC documents can be 3618 found in BCP 78 and BCP 79. 3620 Copies of IPR disclosures made to the IETF Secretariat and any 3621 assurances of licenses to be made available, or the result of an 3622 attempt made to obtain a general license or permission for the use of 3623 such proprietary rights by implementers or users of this 3624 specification can be obtained from the IETF on-line IPR repository at 3625 http://www.ietf.org/ipr. 3627 The IETF invites any interested party to bring to its attention any 3628 copyrights, patents or patent applications, or other proprietary 3629 rights that may cover technology that may be required to implement 3630 this standard. Please address the information to the IETF at 3631 ietf-ipr@ietf.org. 3633 Disclaimer of Validity 3635 This document and the information contained herein are provided on an 3636 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3637 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3638 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3639 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3640 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3641 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3643 Copyright Statement 3645 Copyright (C) The Internet Society (2006). This document is subject 3646 to the rights, licenses and restrictions contained in BCP 78, and 3647 except as set forth therein, the authors retain all their rights. 3649 Acknowledgment 3651 Funding for the RFC Editor function is currently provided by the 3652 Internet Society.