idnits 2.17.1 draft-ietf-taps-transports-usage-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([FJ16]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 14 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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). -- The document date (August 25, 2017) is 2429 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 872, but not defined == Unused Reference: 'RFC2119' is defined on line 2134, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-taps-transports-usage-udp-04 == Outdated reference: A later version (-13) exists of draft-ietf-tsvwg-sctp-ndata-08 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) ** Obsolete normative reference: RFC 6824 (Obsoleted by RFC 8684) ** Obsolete normative reference: RFC 7053 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 6093 (Obsoleted by RFC 9293) Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS M. Welzl 3 Internet-Draft University of Oslo 4 Intended status: Informational M. Tuexen 5 Expires: February 26, 2018 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 August 25, 2017 10 On the Usage of Transport Features Provided by IETF Transport Protocols 11 draft-ietf-taps-transports-usage-07 13 Abstract 15 This document describes how the transport protocols Transmission 16 Control Protocol (TCP), MultiPath TCP (MPTCP), Stream Control 17 Transmission Protocol (SCTP), User Datagram Protocol (UDP) and 18 Lightweight User Datagram Protocol (UDP-Lite) expose services to 19 applications and how an application can configure and use the 20 features that make up these services. It also discusses the service 21 provided by the Low Extra Delay Background Transport (LEDBAT) 22 congestion control mechanism. The description results in a set of 23 transport abstractions that can be exported in a TAPS API. For UDP 24 and UDP-Lite, the first step of the protocol analysis -- a discussion 25 of relevant RFC text -- is documented in [FJ16]. XX RFC ED - PLEASE 26 REPLACE [FJ16] WITH THE CORRECT RFC NUMBER XXX 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on February 26, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . . 5 66 3.1.1. Excluded Primitives or Parameters . . . . . . . . . . 9 67 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . . 9 68 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 11 69 3.3.1. Excluded Primitives or Parameters . . . . . . . . . . 17 70 3.4. Primitives Provided by UDP and UDP-Lite . . . . . . . . . 18 71 3.5. The service of LEDBAT . . . . . . . . . . . . . . . . . . 18 72 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 73 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 20 74 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . . 32 75 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 76 5.1. CONNECTION Related Transport Features . . . . . . . . . . 34 77 5.2. DATA Transfer Related Transport Features . . . . . . . . . 40 78 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . . 40 79 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . . 41 80 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . 42 81 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 42 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 84 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 43 85 9.1. Normative References . . . . . . . . . . . . . . . . . . . 43 86 9.2. Informative References . . . . . . . . . . . . . . . . . . 46 87 Appendix A. Overview of RFCs used as input for pass 1 . . . . . . 47 88 Appendix B. How this document was developed . . . . . . . . . . . 47 89 Appendix C. Revision information . . . . . . . . . . . . . . . . 49 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 50 92 1. Terminology 94 Transport Feature: a specific end-to-end feature that the transport 95 layer provides to an application. Examples include 96 confidentiality, reliable delivery, ordered delivery, message- 97 versus-stream orientation, etc. 98 Transport Service: a set of Transport Features, without an 99 association to any given framing protocol, which provides a 100 complete service to an application. 101 Transport Protocol: an implementation that provides one or more 102 transport services using a specific framing and header format on 103 the wire. 104 Transport Protocol Component: an implementation of a Transport 105 Feature within a protocol. 106 Transport Service Instance: an arrangement of transport protocols 107 with a selected set of features and configuration parameters that 108 implements a single transport service, e.g., a protocol stack (RTP 109 over UDP). 110 Application: an entity that uses the transport layer for end-to-end 111 delivery of data across the network (this may also be an upper 112 layer protocol or tunnel encapsulation). 113 Endpoint: an entity that communicates with one or more other 114 endpoints using a transport protocol. 115 Connection: shared state of two or more endpoints that persists 116 across messages that are transmitted between these endpoints. 117 Primitive: a function call that is used to locally communicate 118 between an application and a transport endpoint. A primitive is 119 related to one or more Transport Features. 120 Event: a primitive that is invoked by a transport endpoint. 121 Parameter: a value passed between an application and a transport 122 protocol by a primitive. 123 Socket: the combination of a destination IP address and a 124 destination port number. 125 Transport Address: the combination of an IP address, transport 126 protocol and the port number used by the transport protocol. 128 2. Introduction 130 This specification describes an (abstract) interface for applications 131 to make use of Transport Services, such that applications are no 132 longer directly tied to a specific protocol. Breaking this strict 133 connection can reduce the effort for an application programmer, yet 134 attain greater transport flexibility by pushing complexity into an 135 underlying TAPS system. 137 This design process has started with a survey of the services 138 provided by IETF transport protocols and congestion control 139 mechanisms [RFC8095]. The present document and [FJ16] complement 140 this survey with an in-depth look at the defined interactions between 141 applications and the following unicast transport protocols: 142 Transmission Control Protocol (TCP), MultiPath TCP (MPTCP), Stream 143 Control Transmission Protocol (SCTP), User Datagram Protocol (UDP), 144 Lightweight User Datagram Protocol (UDP-Lite). We also define a 145 primitive to enable/disable and configure the Low Extra Delay 146 Background Transport (LEDBAT) unicast congestion control mechanism. 147 For UDP and UDP-Lite, the first step of the protocol analysis -- a 148 discussion of relevant RFC text -- is documented in [FJ16]. 150 This snapshot in time analysis of the IETF transport protocols is 151 published as an RFC to document the authors' and working group's 152 analysis, generating a set of transport abstractions that can be 153 exported in a TAPS API. It provides the basis for the minimal set of 154 transport services that end systems supporting TAPS should implement 155 [I-D.draft-gjessing-taps-minset]. 157 The list of primitives, events and transport features in this 158 document is strictly based on the parts of protocol specifications 159 that describe what the protocol provides to an application using it 160 and how the application interacts with it. Transport protocols 161 provide communication between processes that operate on network 162 endpoints, which means that they allow for multiplexing of 163 communication between the same IP addresses, and this multiplexing is 164 achieved using port numbers. Port multiplexing is therefore assumed 165 to be always provided and not discussed in this document. 167 Parts of a protocol that are explicitly stated as optional to 168 implement are not covered. Interactions between the application and 169 a transport protocol that are not directly related to the operation 170 of the protocol are also not covered. For example, there are various 171 ways for an application to use socket options to indicate its 172 interest in receiving certain notifications [RFC6458]. However, for 173 the purpose of identifying primitives, events and transport features, 174 the ability to enable or disable the reception of notifications is 175 irrelevant. Similarly, "one-to-many style sockets" [RFC6458] just 176 affect the application programming style, not how the underlying 177 protocol operates, and they are therefore not discussed here. The 178 same is true for the ability to obtain the unchanged value of a 179 parameter that an application has previously set (e.g.,via "get" in 180 get/set operations [RFC6458]). 182 The document presents a three-pass process to arrive at a list of 183 transport features. In the first pass, the relevant RFC text is 184 discussed per protocol. In the second pass, this discussion is used 185 to derive a list of primitives and events that are uniformly 186 categorized across protocols. Here, an attempt is made to present or 187 -- where text describing primitives or events does not yet exist -- 188 construct primitives or events in a slightly generalized form to 189 highlight similarities. This is, for example, achieved by renaming 190 primitives or events of protocols or by avoiding a strict 1:1-mapping 191 between the primitives or events in the protocol specification and 192 primitives or events in the list. Finally, the third pass presents 193 transport features based on pass 2, identifying which protocols 194 implement them. 196 In the list resulting from the second pass, some transport features 197 are missing because they are implicit in some protocols, and they 198 only become explicit when we consider the superset of all transport 199 features offered by all protocols. For example, TCP always carries 200 out congestion control; we have to consider it together with a 201 protocol like UDP (which does not have congestion control) before we 202 can consider congestion control as a transport feature. The complete 203 list of transport features across all protocols is therefore only 204 available after pass 3. 206 Some protocols are connection-oriented. Connection-oriented 207 protocols often use an initial call to a specific primitive to open a 208 connection before communication can progress, and require 209 communication to be explicitly terminated by issuing another call to 210 a primitive (usually called "close"). A "connection" is the common 211 state that some transport primitives refer to, e.g., to adjust 212 general configuration settings. Connection establishment, 213 maintenance and termination are therefore used to categorize 214 transport primitives of connection-oriented transport protocols in 215 pass 2 and pass 3. For this purpose, UDP is assumed to be used with 216 "connected" sockets, i.e. sockets that are bound to a specific pair 217 of addresses and ports [FJ16]. 219 3. Pass 1 221 This first iteration summarizes the relevant text parts of the RFCs 222 describing the protocols, focusing on what each transport protocol 223 provides to the application and how it is used (abstract API 224 descriptions, where they are available). When presenting primitives, 225 events and parameters, the use of lower- and upper-case characters is 226 made uniform for the sake of readability. 228 3.1. Primitives Provided by TCP 230 The initial TCP specification [RFC0793] states: "The Transmission 231 Control Protocol (TCP) is intended for use as a highly reliable host- 232 to-host protocol between hosts in packet-switched computer 233 communication networks, and in interconnected systems of such 234 networks". Section 3.8 in this specification [RFC0793] further 235 specifies the interaction with the application by listing several 236 transport primitives. It is also assumed that an Operating System 237 provides a means for TCP to asynchronously signal the application; 238 the primitives representing such signals are called 'events' in this 239 section. This section describes the relevant primitives. 241 Open: this is either active or passive, to initiate a connection or 242 listen for incoming connections. All other primitives are 243 associated with a specific connection, which is assumed to first 244 have been opened. An active open call contains a socket. A 245 passive open call with a socket waits for a particular connection; 246 alternatively, a passive open call can leave the socket 247 unspecified to accept any incoming connection. A fully specified 248 passive call can later be made active by calling 'Send'. 249 Optionally, a timeout can be specified, after which TCP will abort 250 the connection if data has not been successfully delivered to the 251 destination (else a default timeout value is used). A procedure 252 for aborting the connection is used to avoid excessive 253 retransmissions, and an application is able to control the 254 threshold used to determine the condition for aborting; this 255 threshold may be measured in time units or as a count of 256 retransmission [RFC1122]. This indicates that the timeout could 257 also be specified as a count of retransmission. 259 Also optional, for multihomed hosts, the local IP address can be 260 provided [RFC1122]. If it is not provided, a default choice will 261 be made in case of active open calls. A passive open call will 262 await incoming connection requests to all local addresses and then 263 maintain usage of the local IP address where the incoming 264 connection request has arrived. Finally, the 'options' parameter 265 allows the application to specify IP options such as source route, 266 record route, or timestamp [RFC1122]. It is not stated on which 267 segments of a connection these options should be applied, but 268 probably all segments, as this is also stated in a specification 269 given for the usage of source route (section 4.2.3.8 of 270 [RFC1122]). Source route is the only non-optional IP option in 271 this parameter, allowing an application to specify a source route 272 when it actively opens a TCP connection. 274 Master Key Tuples (MKTs) for authentication can optionally be 275 configured when calling open (section 7.1 of [RFC5925]). When 276 authentication is in use, complete TCP segments are authenticated, 277 including the TCP IPv4 pseudoheader, TCP header, and TCP data. 279 TCP Fast Open (TFO) [RFC7413] allows to immediately hand over a 280 message from the active open to the passive open side of a TCP 281 connection together with the first message establishment packet 282 (the SYN). This can be useful for applications that are sensitive 283 to TCP's connection setup delay. TCP implementations MUST NOT use 284 TFO by default, but only use TFO if requested explicitly by the 285 application on a per-service-port basis. more than TCP's maximum 286 segment size (minus options used in the SYN). For the active open 287 side, it is recommended to change or replace the connect() call in 288 order to support a user data buffer argument [RFC7413]. For the 289 passive open side, the application needs to enable the reception 290 of Fast Open requests, e.g. via a new TCP_FASTOPEN setsockopt() 291 socket option before listen(). The receiving application must be 292 prepared to accept duplicates of the TFO message, as the first 293 data written to a socket can be delivered more than once to the 294 application on the remote host. 296 Send: this is the primitive that an application uses to give the 297 local TCP transport endpoint a number of bytes that TCP should 298 reliably send to the other side of the connection. The 'urgent' 299 flag, if set, states that the data handed over by this send call 300 is urgent and this urgency should be indicated to the receiving 301 process in case the receiving application has not yet consumed all 302 non-urgent data preceding it. An optional timeout parameter can 303 be provided that updates the connection's timeout (see 'open'). 304 Additionally, optional parameters allow to indicate the preferred 305 outgoing MKT (current_key) and/or the preferred incoming MKT 306 (rnext_key) of a connection (section 7.1 of [RFC5925]). 308 Receive: This primitive allocates a receiving buffer for a provided 309 number of bytes. It returns the number of received bytes provided 310 in the buffer when these bytes have been received and written into 311 the buffer by TCP. The application is informed of urgent data via 312 an 'urgent' flag: if it is on, there is urgent data. If it is 313 off, there is no urgent data or this call to 'receive' has 314 returned all the urgent data. The application is also informed 315 about the current_key and rnext_key information carried in a 316 recently received segment via an optional parameter (section 7.1 317 of [RFC5925]). 319 Close: This primitive closes one side of a connection. It is 320 semantically equivalent to "I have no more data to send" but does 321 not mean "I will not receive any more", as the other side may 322 still have data to send. This call reliably delivers any data 323 that has already been given to TCP (and if that fails, 'close' 324 becomes 'abort'). 326 Abort: This primitive causes all pending 'send' and 'receive' calls 327 to be aborted. A TCP "RESET" message is sent to the TCP endpoint 328 on the other side of the connection [RFC0793]. 330 Close Event: TCP uses this primitive to inform an application that 331 the application on the other side has called the 'close' 332 primitive, so the local application can also issue a 'close' and 333 terminate the connection gracefully. See [RFC0793], Section 3.5. 335 Abort Event: When TCP aborts a connection upon receiving a "RESET" 336 from the peer, it "advises the user and goes to the CLOSED state." 337 See [RFC0793], Section 3.4. 339 User Timeout Event: This event is executed when the user timeout 340 expires (see 'open') (section 3.9 of [RFC0793]). All queues are 341 flushed and the application is informed that the connection had to 342 be aborted due to user timeout. 344 Error_Report event: This event informs the application of "soft 345 errors" that can be safely ignored [RFC5461], including the 346 arrival of an ICMP error message or excessive retransmissions 347 (reaching a threshold below the threshold where the connection is 348 aborted). See section 4.2.4.1 of [RFC1122]. 350 Type-of-Service: Section 4.2.4.2 of the requirements for Internet 351 hosts [RFC1122] states that the application layer MUST be able to 352 specify the Type-of-Service (TOS) for segments that are sent on a 353 connection. The application should be able to change the TOS 354 during the connection lifetime, and the TOS value should be passed 355 to the IP layer unchanged. Since then the TOS field has been 356 redefined. The Differentiated Services (diffuser) model [RFC2475] 357 [RFC3260] replaces this field in the IP Header, assigning the six 358 most significant bits to carry the Differentiated Services Code 359 Point (DSCP) field [RFC2474]. 361 Nagle: The Nagle algorithm delays sending data for some time to 362 increase the likelihood of sending a full-sized segment (section 363 4.2.3.4 of [RFC1122]). An application can disable the Nagle 364 algorithm for an individual connection. 366 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 367 one end of a TCP connection to advertise its current user timeout 368 value so that the other end of the TCP connection can adapt its 369 own user timeout accordingly. In addition to the configurable 370 value of the User Timeout (see 'send'), there are three per- 371 connection state variables that an application can adjust to 372 control the operation of the User Timeout Option (UTO): 'adv_uto' 373 is the value of the UTO advertised to the remote TCP peer 374 (default: system-wide default user timeout); 'enabled' (default 375 false) is a boolean-type flag that controls whether the UTO option 376 is enabled for a connection. This applies to both sending and 377 receiving. 'changeable' is a boolean-type flag (default true) that 378 controls whether the user timeout may be changed based on a UTO 379 option received from the other end of the connection. 'changeable' 380 becomes false when an application explicitly sets the user timeout 381 (see 'send'). 383 Set / Get Authentication Parameters: The preferred outgoing MKT 384 (current_key) and/or the preferred incoming MKT (rnext_key) of a 385 connection can be configured. Information about current_key and 386 rnext_key carried in a recently received segment can be retrieved 387 (section 7.1 of [RFC5925]). 389 3.1.1. Excluded Primitives or Parameters 391 The 'open' primitive can be handed optional Precedence or security/ 392 compartment information [RFC0793], but this was not included here 393 because it is mostly irrelevant today [RFC7414]. 395 The 'Status' primitive was not included because the initial TCP 396 specification describes this primitive as "implementation dependent" 397 and states that it "could be excluded without adverse effect" 398 [RFC0793]. Moreover, while a data block containing specific 399 information is described, it is also stated that not all of this 400 information may always be available. While 'Status' SHOULD be 401 augmented to allow the MKTs of a current or pending connection to be 402 read (for confirmation), the same information is also available via 403 'Receive', which MUST be augmented with that functionality [RFC5925]. 404 The 'Send' primitive includes an optional 'push' flag which, if set, 405 requires data to be promptly transmitted to the receiver without 406 delay [RFC0793]; the 'Receive' primitive described in can (under some 407 conditions) yield the status of the 'push' flag. Because "push" 408 functionality is optional to implement for both the 'send' and 409 'receive' primitives [RFC1122], this functionality is not included 410 here. The requirements for Internet hosts [RFC1122] also introduce 411 keep-alives to TCP, but these are optional to implement and hence not 412 considered here. The same document also describes that "some TCP 413 implementations have included a FLUSH call", indicating that this 414 call is also optional to implement. It is therefore not considered 415 here. 417 3.2. Primitives Provided by MPTCP 419 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 420 multiple paths for a single data-stream. It achieves this by 421 creating different so-called TCP subflows for each of the interfaces 422 and scheduling the traffic across these TCP subflows. The service 423 provided by MPTCP is described as follows [RFC6182]: "Multipath TCP 424 MUST follow the same service model as TCP [RFC0793]: in- order, 425 reliable, and byte-oriented delivery. Furthermore, a Multipath TCP 426 connection SHOULD provide the application with no worse throughput or 427 resilience than it would expect from running a single TCP connection 428 over any one of its available paths." 430 Further, there are some constraints on the API exposed by MPTCP 431 [RFC6182]: "A multipath-capable equivalent of TCP MUST retain some 432 level of backward compatibility with existing TCP APIs, so that 433 existing applications can use the newer merely by upgrading the 434 operating systems of the end hosts." As such, the primitives 435 provided by MPTCP are equivalent to the ones provided by TCP. 436 Nevertheless, the MPTCP RFCs [RFC6824] and [RFC6897] clarify some 437 parts of TCP's primitives with respect to MPTCP and add some 438 extensions for better control on MPTCP's subflows. Hereafter is a 439 list of the clarifications and extensions the above cited RFCs 440 provide to TCP's primitives. 442 Open: "An application should be able to request to turn on or turn 443 off the usage of MPTCP" [RFC6897]. This functionality can be 444 provided through a socket-option called 'tcp_multipath_enable'. 445 Further, MPTCP must be disabled in case the application is binding 446 to a specific address [RFC6897]. 448 Send/Receive: The sending and receiving of data does not require any 449 changes to the application when MPTCP is being used [RFC6824]. 450 The MPTCP-layer will "take one input data stream from an 451 application, and split it into one or more subflows, with 452 sufficient control information to allow it to be reassembled and 453 delivered reliably and in order to the recipient application." 454 The use of the Urgent Pointer is special in MPTCP [RFC6824]: "a 455 TCP subflow MUST NOT use the Urgent Pointer to interrupt an 456 existing mapping." 458 Address and Subflow Management: MPTCP uses different addresses and 459 allows a host to announce these addresses as part of the protocol. 460 The MPTCP API Considerations RFC [RFC6897] says "An application 461 should be able to restrict MPTCP to binding to a given set of 462 addresses" and thus allows applications to limit the set of 463 addresses that are being used by MPTCP. Further, "An application 464 should be able to obtain information on the pairs of addresses 465 used by the MPTCP subflows". 467 3.3. Primitives Provided by SCTP 469 TCP has a number of limitations that SCTP removes (section 1.1 of 470 [RFC4960]). The following three removed limitations directly 471 translate into transport features that are visible to an application 472 using SCTP: 1) it allows for preservation of message delineations; 2) 473 it does not provide in-order or reliable delivery unless the 474 application wants that; 3) multi-homing is supported. In SCTP, 475 connections are called "associations" and they can be between not 476 only two (as in TCP) but multiple addresses at each endpoint. 478 Section 10 of the SCTP base protocol specification [RFC4960] 479 specifies the interaction with the application (which SCTP calls the 480 "Upper Layer Protocol" (ULP)). It is assumed that the Operating 481 System provides a means for SCTP to asynchronously signal the 482 application; the primitives representing such signals are called 483 'events' in this section. Here, we describe the relevant primitives. 484 In addition to the abstract API described in the section 10 of the 485 SCTP base protocol specification [RFC4960], an extension to the 486 socket API is described in [RFC6458]. This covers the functionality 487 of the base protocol [RFC4960] and some of its extensions [RFC3758], 488 [RFC4895], [RFC5061]. For other protocol extensions [RFC6525], 489 [RFC6951], [RFC7053], [RFC7496], [RFC7829], 490 [I-D.ietf-tsvwg-sctp-ndata], the corresponding extensions of the 491 socket API are specified in these protocol specifications. The 492 functionality exposed to the ULP through all these APIs is considered 493 here. 495 The abstract API contains a 'SetProtocolParameters' primitive that 496 allows to adjust elements of a parameter list [RFC4960]; it is stated 497 that SCTP implementations "may allow ULP to customize some of these 498 protocol parameters", indicating that none of the elements of this 499 parameter list are mandatory to make ULP-configurable. Thus, we only 500 consider the parameters in the abstract API that are also covered in 501 one of the other RFCs listed above, which leads us to exclude the 502 parameters RTO.Alpha, RTO.Beta and HB.Max.Burst. For clarity, we 503 also replace 'SetProtocolParameters' itself with primitives that 504 adjust parameters or groups of parameters that fit together. 506 Initialize: Initialize creates a local SCTP instance that it binds 507 to a set of local addresses (and, if provided, a local port 508 number) [RFC4960]. Initialize needs to be called only once per 509 set of local addresses. A number of per-association 510 initialization parameters can be used when an association is 511 created, but before it is connected (via the primitive 'Associate' 512 below): the maximum number of inbound streams the application is 513 prepared to support, the maximum number of attempts to be made 514 when sending the INIT (the first message of association 515 establishment), and the maximum retransmission timeout (RTO) value 516 to use when attempting an INIT [RFC6458]. At this point, before 517 connecting, an application can also enable UDP encapsulation by 518 configuring the remote UDP encapsulation port number [RFC6951]. 520 Associate: This creates an association (the SCTP equivalent of a 521 connection) that connects the local SCTP instance and a remote 522 SCTP instance. To identify the remote endpoint, it can be given 523 one or multiple (using "connectx") sockets (section 9.9 of 524 [RFC6458]). Most primitives are associated with a specific 525 association, which is assumed to first have been created. 526 Associate can return a list of destination transport addresses so 527 that multiple paths can later be used. One of the returned 528 sockets will be selected by the local endpoint as default primary 529 path for sending SCTP packets to this peer, but this choice can be 530 changed by the application using the list of destination 531 addresses. Associate is also given the number of outgoing streams 532 to request and optionally returns the number of negotiated 533 outgoing streams. An optional parameter of 32 bits, the 534 adaptation layer indication, can be provided [RFC5061]. If 535 authenticated chunks are used, the chunk types required to be sent 536 authenticated by the peer can be provided [RFC4895]. A 537 'SCTP_Cant_Str_Assoc' notification is used to inform the 538 application of a failure to create an association [RFC6458]. An 539 application could use sendto() or sendmsg() to implicitly setup an 540 association, thereby handing over a message that SCTP might send 541 during the association setup phase [RFC6458]. Note that this 542 mechanism is different from TCP's TFO mechanism: the message would 543 arrive only once, after at least one RTT, as it is sent together 544 with the third message exchanged during association setup, the 545 COOKIE-ECHO chunk). 547 Send: This sends a message of a certain length in bytes over an 548 association. A number can be provided to later refer to the 549 correct message when reporting an error, and a stream id is 550 provided to specify the stream to be used inside an association 551 (we consider this as a mandatory parameter here for simplicity: if 552 not provided, the stream id defaults to 0). A condition to 553 abandon the message can be specified (for example limiting the 554 number of retransmissions or the lifetime of the user message). 555 This allows to control the partial reliability extension 556 [RFC3758], [RFC7496]. An optional maximum life time can specify 557 the time after which the message should be discarded rather than 558 sent. A choice (advisory, i.e. not guaranteed) of the preferred 559 path can be made by providing a socket, and the message can be 560 delivered out-of-order if the unordered flag is set. An advisory 561 flag indicates that the peer should not delay the acknowledgement 562 of the user message provided [RFC7053]. Another advisory flag 563 indicates whether the application prefers to avoid bundling user 564 data with other outbound DATA chunks (i.e., in the same packet). 565 A payload protocol-id can be provided to pass a value that 566 indicates the type of payload protocol data to the peer. If 567 authenticated chunks are used, the key identifier for 568 authenticating DATA chunks can be provided [RFC4895]. 570 Receive: Messages are received from an association, and optionally a 571 stream within the association, with their size returned. The 572 application is notified of the availability of data via a 'Data 573 Arrive' notification. If the sender has included a payload 574 protocol-id, this value is also returned. If the received message 575 is only a partial delivery of a whole message, a partial flag will 576 indicate so, in which case the stream id and a stream sequence 577 number are provided to the application. A delivery number lets 578 the application detect reordering. 580 Shutdown: This primitive gracefully closes an association, reliably 581 delivering any data that has already been handed over to SCTP. A 582 parameter lets the application control whether further receive or 583 send operations or both are disabled when the call is issued. A 584 return code informs about success or failure of this procedure. 586 Abort: This ungracefully closes an association, by discarding any 587 locally queued data and informing the peer that the association 588 was aborted. Optionally, an abort reason to be passed to the peer 589 may be provided by the application. A return code informs about 590 success or failure of this procedure. 592 Change Heartbeat / Request Heartbeat: This allows the application to 593 enable/disable heartbeats and optionally specify a heartbeat 594 frequency as well as requesting a single heartbeat to be carried 595 out upon a function call, with a notification about success or 596 failure of transmitting the HEARTBEAT chunk to the destination. 598 Configure Max. Retransmissions of an Association: The parameter 599 Association.Max.Retrans [RFC4960] (called "sasoc_maxrxt" in the 600 SCTP socket API extensions [RFC6458]), allows to configure the 601 number of unsuccessful retransmissions after which an entire 602 association is considered as failed; this should invoke a 603 'Communication Lost' notification. 605 Set Primary: This allows to set a new primary default path for an 606 association by providing a socket. Optionally, a default source 607 address to be used in IP datagrams can be provided. 609 Change Local Address / Set Peer Primary: This allows an endpoint to 610 add/remove local addresses to/from an association. In addition, 611 the peer can be given a hint which address to use as the primary 612 address [RFC5061]. 614 Configure Path Switchover: The abstract API contains a primitive 615 called 'Set Failure Threshold' [RFC4960]. This configures the 616 parameter "Path.Max.Retrans", which determines after how many 617 retransmissions a particular transport address is considered as 618 unreachable. If there are more transport addresses available in 619 an association, reaching this limit will invoke a path switchover. 620 An extension called "SCTP-PF" adds a concept of "Potentially 621 Failed" (PF) paths to this method [RFC7829]. When a path is in PF 622 state, SCTP will not entirely give up sending on that path, but it 623 will preferably send data on other active paths if such paths are 624 available. Entering the PF state is done upon exceeding a 625 configured maximum number of retransmissions. Thus, for all paths 626 where this mechanism is used, there are two configurable error 627 thresholds: one to decide that a path is in PF state, and one to 628 decide that the transport address is unreachable. 630 Set / Get Authentication Parameters: This allows an endpoint to add/ 631 remove key material to/from an association. In addition, the 632 chunk types being authenticated can be queried [RFC4895]. 634 Add / Reset Streams, Reset Association: This allows an endpoint to 635 add streams to an existing association or or to reset them 636 individually. Additionally, the association can be reset 637 [RFC6525]. 639 Status: The 'Status' primitive returns a data block with information 640 about a specified association, containing: association connection 641 state; destination transport address list; destination transport 642 address reachability states; current local and peer receiver 643 window sizes; current local congestion window sizes; number of 644 unacknowledged DATA chunks; number of DATA chunks pending receipt; 645 primary path; most recent SRTT on primary path; RTO on primary 646 path; SRTT and RTO on other destination addresses [RFC4960] and 647 MTU per path [RFC6458]. 649 Enable / Disable Interleaving: This allows to enable or disable the 650 negotiation of user message interleaving support for future 651 associations. For existing associations it is possible to query 652 whether user message interleaving support was negotiated or not on 653 a particular association [I-D.ietf-tsvwg-sctp-ndata]. 655 Set Stream Scheduler: This allows to select a stream scheduler per 656 association, with a choice of: First Come First Serve, Round 657 Robin, Round Robin per Packet, Priority Based, Fair Bandwidth, 658 Weighted Fair Queuing [I-D.ietf-tsvwg-sctp-ndata]. 660 Configure Stream Scheduler: This allows to change a parameter per 661 stream for the schedulers: a priority value for the Priority Based 662 scheduler and a weight for the Weighted Fair Queuing scheduler. 664 Enable / Disable NoDelay: This turns on/off any Nagle-like algorithm 665 for an association [RFC6458]. 667 Configure Send Buffer Size: This controls the amount of data SCTP 668 may have waiting in internal buffers to be sent or retransmitted 669 [RFC6458]. 671 Configure Receive Buffer Size: This sets the receive buffer size in 672 octets, thereby controlling the receiver window for an association 673 [RFC6458]. 675 Configure Message Fragmentation: If a user message causes an SCTP 676 packet to exceed the maximum fragmentation size (which can be 677 provided by the application, and is otherwise the PMTU size), then 678 the message will be fragmented by SCTP. Disabling message 679 fragmentation will produce an error instead of fragmenting the 680 message [RFC6458]. 682 Configure Path MTU Discovery: Path MTU Discovery can be enabled or 683 disabled per peer address of an association (section 8.1.12 of 684 [RFC6458]). When it is enabled, the current Path MTU value can be 685 obtained. When it is disabled, the Path MTU to be used can be 686 controlled by the application. 688 Configure Delayed SACK Timer: The time before sending a SACK can be 689 adjusted; delaying SACKs can be disabled; the number of packets 690 that must be received before a SACK is sent without waiting for 691 the delay timer to expire can be configured [RFC6458]. 693 Set Cookie Life Value: The Cookie life value can be adjusted 694 (section 8.1.2 of [RFC6458]). "Valid.Cookie.Life" is also one of 695 the parameters that is potentially adjustable with 696 'SetProtocolParameters' [RFC4960]. 698 Set Maximum Burst: The maximum burst of packets that can be emitted 699 by a particular association (default 4, and values above 4 are 700 optional to implement) can be adjusted (section 8.1.2 of 701 [RFC6458]). "Max.Burst" is also one of the parameters that is 702 potentially adjustable with 'SetProtocolParameters' [RFC4960]. 704 Configure RTO Calculation: The abstract API contains the following 705 adjustable parameters: RTO.Initial; RTO.Min; RTO.Max; RTO.Alpha; 706 RTO.Beta. Only the initial, minimum and maximum RTO are also 707 described as configurable in the SCTP sockets API extensions 708 [RFC6458]. 710 Set DSCP Value: The DSCP value can be set per peer address of an 711 association (section 8.1.12 of [RFC6458]). 713 Set IPv6 Flow Label: The flow label field can be set per peer 714 address of an association (section 8.1.12 of [RFC6458]). 716 Set Partial Delivery Point: This allows to specify the size of a 717 message where partial delivery will be invoked. Setting this to a 718 lower value will cause partial deliveries to happen more often 719 [RFC6458]. 721 Communication Up Notification: When a lost communication to an 722 endpoint is restored or when SCTP becomes ready to send or receive 723 user messages, this notification informs the application process 724 about the affected association, the type of event that has 725 occurred, the complete set of sockets of the peer, the maximum 726 number of allowed streams and the inbound stream count (the number 727 of streams the peer endpoint has requested). If interleaving is 728 supported by both endpoints, this information is also included in 729 this notification. 731 Restart Notification: When SCTP has detected that the peer has 732 restarted, this notification is passed to the upper layer 733 [RFC6458]. 735 Data Arrive Notification: When a message is ready to be retrieved 736 via the 'Receive' primitive, the application is informed by this 737 notification. 739 Send Failure Notification / Receive Unsent Message / Receive 740 Unacknowledged Message: When a message cannot be delivered via an 741 association, the sender can be informed about it and learn whether 742 the message has just not been acknowledged or (e.g. in case of 743 lifetime expiry) if it has not even been sent. This can also 744 inform the sender that a part of the message has been successfully 745 delivered. 747 Network Status Change Notification: This informs the application 748 about a socket becoming active/inactive [RFC4960] or "Potentially 749 Failed" [RFC7829]. 751 Communication Lost Notification: When SCTP loses communication to an 752 endpoint (e.g. via Heartbeats or excessive retransmission) or 753 detects an abort, this notification informs the application 754 process of the affected association and the type of event (failure 755 OR termination in response to a shutdown or abort request). 757 Shutdown Complete Notification: When SCTP completes the shutdown 758 procedures, this notification is passed to the upper layer, 759 informing it about the affected assocation. 761 Authentication Notification: When SCTP wants to notify the upper 762 layer regarding the key management related to authenticated chunks 763 [RFC4895], this notification is passed to the upper layer. 765 Adaptation Layer Indication Notification: When SCTP completes the 766 association setup and the peer provided an adaptation layer 767 indication, this is passed to the upper layer [RFC5061], 768 [RFC6458]. 770 Stream Reset Notification: When SCTP completes the procedure for 771 resetting streams [RFC6525], this notification is passed to the 772 upper layer, informing it about the result. 774 Assocation Reset Notification: When SCTP completes the association 775 reset procedure [RFC6525], this notification is passed to the 776 upper layer, informing it about the result. 778 Stream Change Notification: When SCTP completes the procedure used 779 to increase the number of streams [RFC6525], this notification is 780 passed to the upper layer, informing it about the result. 782 Sender Dry Notification: When SCTP has no more user data to send or 783 retransmit on a particular association, this notification is 784 passed to the upper layer [RFC6458]. 786 Partial Delivery Aborted Notification: When a receiver has begun to 787 receive parts of a user message but the delivery of this message 788 is then aborted, this notification is passed to the upper layer 789 (section 6.1.7 of [RFC6458]). 791 3.3.1. Excluded Primitives or Parameters 793 The 'Receive' primitive can return certain additional information, 794 but this is optional to implement and therefore not considered. With 795 a 'Communication Lost' notification, some more information may 796 optionally be passed to the application (e.g., identification to 797 retrieve unsent and unacknowledged data). SCTP "can invoke" a 798 'Communication Error' notification and "may send" a 'Restart' 799 notification, making these two notifications optional to implement. 800 The list provided under 'Status' includes "etc", indicating that more 801 information could be provided. The primitive 'Get SRTT Report' 802 returns information that is included in the information that 'Status' 803 provides and is therefore not discussed. The 'Destroy SCTP Instance' 804 API function was excluded: it erases the SCTP instance that was 805 created by 'Initialize', but is not a Primitive as defined in this 806 document because it does not relate to a transport feature. The 807 'Shutdown' event informs an application that the peer has sent a 808 SHUTDOWN, and hence no further data should be sent on this socket 809 (section 6.1 of [RFC6458]). However, if an application would try to 810 send data on the socket, it would get an error message anyway; thus, 811 this event is classified as "just affecting the application 812 programming style, not how the underlying protocol operates" and not 813 included here. 815 3.4. Primitives Provided by UDP and UDP-Lite 817 The set of pass 1 primitives for UDP and UDP-Lite is documented in 818 [FJ16]. 820 3.5. The service of LEDBAT 822 The service of the Low Extra Delay Background Transport (LEDBAT) 823 congestion control mechanism is described as follows: "LEDBAT is 824 designed for use by background bulk-transfer applications to be no 825 more aggressive than standard TCP congestion control (as specified in 826 RFC 5681) and to yield in the presence of competing flows, thus 827 limiting interference with the network performance of competing 828 flows" [RFC6817]. 830 LEDBAT does not have any primitives, as LEDBAT is not a transport 831 protocol. According to its specification [RFC6817], "LEDBAT can be 832 used as part of a transport protocol or as part of an application, as 833 long as the data transmission mechanisms are capable of carrying 834 timestamps and acknowledging data frequently. LEDBAT can be used 835 with TCP, Stream Control Transmission Protocol (SCTP), and Datagram 836 Congestion Control Protocol (DCCP), with appropriate extensions where 837 necessary; and it can be used with proprietary application protocols, 838 such as those built on top of UDP for peer-to- peer (P2P) 839 applications." At the time of writing, the appropriate extensions 840 for TCP, SCTP or DCCP do not exist. 842 A numer of configurable parameters exist in the LEDBAT specification: 843 TARGET, which is the queuing delay target at which LEDBAT tries to 844 operate, must be set to 100ms or less. 'allowed_increase' (should be 845 1, must be greater than 0) limits the speed at which LEDBAT increases 846 its rate. 'gain', which MUST be set to 1 or less to avoid a faster 847 ramp-up than TCP Reno, determines how quickly the sender responds to 848 changes in queueing delay. Implementations may divide 'gain' into 849 two parameters, one for increase and a possibly larger one for 850 decrease. We call these parameters 'Gain_Inc' and 'Gain_Dec' here. 851 'Base_History' is the size of the list of measured base delays, and 852 SHOULD be 10. This list can be filtered using a 'Filter' function 853 which is not prescribed [RFC6817], yielding a list of size 854 'Current_Filter'. The initial and minimum congestion windows, 855 'Init_CWND' and 'Min_CWND', should both be 2. 857 Regarding which of these parameters should be under control of an 858 application, the possible range goes from exposing nothing on the one 859 hand, to considering everything that is not prescribed with a MUST in 860 the specification as a parameter on the other hand. Function 861 implementations are not provided as a parameter to any of the 862 transport protocols discussed here, and hence we do not regard the 863 'Filter' function as a parameter. However, to avoid unnecessarily 864 limiting future implementations, we consider all other parameters 865 above as tunable parameters that should be exposed. 867 4. Pass 2 869 This pass categorizes the primitives from pass 1 based on whether 870 they relate to a connection or to data transmission. Primitives are 871 presented following the nomenclature 872 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 873 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 874 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 875 considered. The DATA category does not have any SUBCATEGORY. The 876 PROTOCOL name "UDP(-Lite)" is used when primitives are equivalent for 877 UDP and UDP-Lite; the PROTOCOL name "TCP" refers to both TCP and 878 MPTCP. We present "connection" as a general protocol-independent 879 concept and use it to refer to, e.g., TCP connections (identifiable 880 by a unique pair of IP addresses and TCP port numbers), SCTP 881 associations (identifiable by multiple IP address and port number 882 pairs), as well UDP and UDP-Lite connections (identifiable by a 883 unique socket pair). 885 Some minor details are omitted for the sake of generalization -- 886 e.g., SCTP's 'Close' [RFC4960] returns success or failure, and lets 887 the application control whether further receive or send operations or 888 both are disabled [RFC6458]. This is not described in the same way 889 for TCP [RFC0793], but these details play no significant role for the 890 primitives provided by either TCP or SCTP (for the sake of being 891 generic, it could be assumed that both receive and send operations 892 are disabled in both cases). 894 The TCP 'Send' and 'Receive' primitives include usage of an 'urgent' 895 parameter. This parameter controls a mechanism that is required to 896 implement the "synch signal" used by telnet [RFC0854], but SHOULD NOT 897 be used by new applications [RFC6093]. Because pass 2 is meant as a 898 basis for the creation of future systems, the "urgent" mechanism is 899 excluded. This also concerns the notification 'Urgent Pointer 900 Advance' in the 'Error_Report' (section 4.2.4.1 of [RFC1122]). 902 Since LEDBAT is a congestion control mechanism and not a protocol, it 903 is not currently defined when to enable / disable or configure the 904 mechanism. For instance, it could be a one-time choice upon 905 connection establishment or when listening for incoming connections, 906 in which case it should be categorized under CONNECTION.ESTABLISHMENT 907 or CONNECTION.AVAILABILITY, respectively. To avoid unnecessarily 908 limiting future implementations, it was decided to place it under 909 CONNECTION.MAINTENANCE, with all parameters that are described in the 910 specification [RFC6817] made configurable. 912 4.1. CONNECTION Related Primitives 914 ESTABLISHMENT: 915 Active creation of a connection from one transport endpoint to one or 916 more transport endpoints. 917 Interfaces to UDP and UDP-Lite allow both connection-oriented and 918 connection-less usage of the API [RFC8085]. 920 o CONNECT.TCP: 921 Pass 1 primitive / event: 'Open' (active) or 'Open' (passive) with 922 socket, followed by 'Send' 923 Parameters: 1 local IP address (optional); 1 destination transport 924 address (for active open; else the socket and the local IP address 925 of the succeeding incoming connection request will be maintained); 926 timeout (optional); options (optional); MKT configuration 927 (optional); user message (optional) 928 Comments: If the local IP address is not provided, a default 929 choice will automatically be made. The timeout can also be a 930 retransmission count. The options are IP options to be used on 931 all segments of the connection. At least the Source Route option 932 is mandatory for TCP to provide. 'MKT configuration' refers to 933 the ability to configure Master Key Tuples (MKTs) for 934 authentication. The user message may be transmitted to the peer 935 application immediately upon reception of the TCP SYN packet. To 936 benefit from the lower latency this provides as part of the 937 experimental TFO mechanism, its length must be at most the TCP's 938 maximum segment size (minus TCP options used in the SYN). The 939 message may also be delivered more than once to the application on 940 the remote host. 942 o CONNECT.SCTP: 943 Pass 1 primitive / event: 'Initialize', followed by 'Enable / 944 Disable Interleaving' (optional), followed by 'Associate' 945 Parameters: list of local SCTP port number / IP address pairs 946 ('Initialize'); one or several sockets (identifying the peer); 947 outbound stream count; maximum allowed inbound stream count; 948 adaptation layer indication (optional); chunk types required to be 949 authenticated (optional); request interleaving on/off; maximum 950 number of INIT attemps (optional); maximum init. RTO for INIT 951 (optional); user message (optional); remote UDP port number 952 (optional) 953 Returns: socket list or failure 954 Comments: 'Initialize' needs to be called only once per list of 955 local SCTP port number / IP address pairs. One socket will 956 automatically be chosen; it can later be changed in MAINTENANCE. 957 The user message may be transmitted to the peer application 958 immediately upon reception of the packet containing the COOKIE- 959 ECHO chunk. To benefit from the lower latency this provides, its 960 length must be limited such that it fits into the packet 961 containing the COOKIE-ECHO chunk. If a remote UDP port number is 962 provided, SCTP packets will be encapsulated in UDP. 964 o CONNECT.MPTCP: 965 This is similar to CONNECT.TCP except for one additional boolean 966 parameter that allows to enable or disable MPTCP for a particular 967 connection or socket (default: enabled). 969 o CONNECT.UDP(-Lite): 970 Pass 1 primitive / event: 'Connect' followed by 'Send'. 971 Parameters: 1 local IP address (default (ANY), or specified); 1 972 destination transport address; 1 local port (default (OS chooses), 973 or specified); 1 destination port (default (OS chooses), or 974 specified). 975 Comments: Associates a transport address creating a UDP(-Lite) 976 socket connection. This can be called again with a new transport 977 address to create a new connection. The CONNECT function allows 978 an application to receive errors from messages sent to a transport 979 address. 981 AVAILABILITY: 982 Preparing to receive incoming connection requests. 984 o LISTEN.TCP: 985 Pass 1 primitive / event: 'Open' (passive) 986 Parameters: 1 local IP address (optional); 1 socket (optional); 987 timeout (optional); buffer to receive a user message (optional); 988 MKT configuration (optional) 989 Comments: if the socket and/or local IP address is provided, this 990 waits for incoming connections from only and/or to only the 991 provided address. Else this waits for incoming connections 992 without this / these constraint(s). ESTABLISHMENT can later be 993 performed with 'Send'. If a buffer is provided to receive a user 994 message, a user message can be received from a TFO-enabled sender 995 before TCP's connection handshake is completed. This message may 996 arrive multiple times. 'MKT configuration' refers to the ability 997 to configure Master Key Tuples (MKTs) for authentication. 999 o LISTEN.SCTP: 1000 Pass 1 primitive / event: 'Initialize', followed by 'Communication 1001 Up' or 'Restart' notification and possibly 'Adaptation Layer' 1002 notification 1003 Parameters: list of local SCTP port number / IP address pairs 1004 (initialize) 1005 Returns: socket list; outbound stream count; inbound stream count; 1006 adaptation layer indication; chunks required to be authenticated; 1007 interleaving supported on both sides yes/no 1008 Comments: 'Initialize' needs to be called only once per list of 1009 local SCTP port number / IP address pairs. 'Communication Up' can 1010 also follow a 'Communication Lost' notification, indicating that 1011 the lost communication is restored. If the peer has provided an 1012 adaptation layer indication, an 'Adaptation Layer' notification is 1013 issued. 1015 o LISTEN.MPTCP: 1016 This is similar to LISTEN.TCP except for one additional boolean 1017 parameter that allows to enable or disable MPTCP for a particular 1018 connection or socket (default: enabled). 1020 o LISTEN.UDP(-Lite): 1021 Pass 1 primitive / event: 'Receive'. 1022 Parameters: 1 local IP address (default (ANY), or specified); 1 1023 destination transport address; local port (default (OS chooses), 1024 or specified); destination port (default (OS chooses), or 1025 specified). 1026 Comments: The 'Receive' function registers the application to 1027 listen for incoming UDP(-Lite) datagrams at an endpoint. 1029 MAINTENANCE: 1030 Adjustments made to an open connection, or notifications about it. 1031 These are out-of-band messages to the protocol that can be issued at 1032 any time, at least after a connection has been established and before 1033 it has been terminated (with one exception: CHANGE_TIMEOUT.TCP can 1034 only be issued for an open connection when DATA.SEND.TCP is called). 1035 In some cases, these primitives can also be immediately issued during 1036 ESTABLISHMENT or AVAILABILITY, without waiting for the connection to 1037 be opened (e.g. CHANGE_TIMEOUT.TCP can be done using TCP's 'Open' 1038 primitive). For UDP and UDP-Lite, these functions may establish a 1039 setting per connection, but may also be changed per datagram message. 1041 o CHANGE_TIMEOUT.TCP: 1042 Pass 1 primitive / event: 'Open' or 'Send' combined with 1043 unspecified control of per-connection state variables 1044 Parameters: timeout value (optional); adv_uto (optional); boolean 1045 uto_enabled (optional, default false); boolean changeable 1046 (optional, default true) 1047 Comments: when sending data, an application can adjust the 1048 connection's timeout value (time after which the connection will 1049 be aborted if data could not be delivered). If 'uto_enabled' is 1050 true, the 'timeout value' (or, if provided, the value 'adv_uto') 1051 will be advertised for the TCP on the other side of the connection 1052 to adapt its own user timeout accordingly. 'uto_enabled' controls 1053 whether the UTO option is enabled for a connection. This applies 1054 to both sending and receiving. 'changeable' controls whether the 1055 user timeout may be changed based on a UTO option received from 1056 the other end of the connection; it becomes false when 'timeout 1057 value' is used. 1059 o CHANGE_TIMEOUT.SCTP: 1060 Pass 1 primitive / event: 'Change HeartBeat' combined with 1061 'Configure Max. Retransmissions of an Association' 1062 Parameters: 'Change Heartbeat': heartbeat frequency; 'Configure 1063 Max. Retransmissions of an Association': association.max.retrans 1064 Comments: 'Change Heartbeat' can enable / disable heartbeats in 1065 SCTP as well as change their frequency. The parameter 1066 'association.max.retrans' defines after how many unsuccessful 1067 transmissions of any packets (including heartbeats) the 1068 association will be terminated; thus these two primitives / 1069 parameters together can yield a similar behavior for SCTP 1070 associations as CHANGE_TIMEOUT.TCP does for TCP connections. 1072 o DISABLE_NAGLE.TCP: 1073 Pass 1 primitive / event: not specified 1074 Parameters: one boolean value 1075 Comments: the Nagle algorithm delays data transmission to increase 1076 the chance to send a full-sized segment. An application must be 1077 able to disable this algorithm for a connection. 1079 o DISABLE_NAGLE.SCTP: 1080 Pass 1 primitive / event: 'Enable / Disable NoDelay' 1081 Parameters: one boolean value 1082 Comments: Nagle-like algorithms delay data transmission to 1083 increase the chance to send a full-sized packet. 1085 o REQUEST_HEARTBEAT.SCTP: 1086 Pass 1 primitive / event: 'Request HeartBeat' 1087 Parameters: socket 1088 Returns: success or failure 1089 Comments: requests an immediate heartbeat on a path, returning 1090 success or failure. 1092 o ADD_PATH.MPTCP: 1093 Pass 1 primitive / event: not specified 1094 Parameters: local IP address and optionally the local port number 1095 Comments: the application specifies the local IP address and port 1096 number that must be used for a new subflow. 1098 o ADD_PATH.SCTP: 1099 Pass 1 primitive / event: 'Change Local Address / Set Peer 1100 Primary' 1101 Parameters: local IP address 1103 o REM_PATH.MPTCP: 1104 Pass 1 primitive / event: not specified 1105 Parameters: local IP address; local port number; remote IP 1106 address; remote port number 1107 Comments: the application removes the subflow specified by the IP/ 1108 port-pair. The MPTCP implementation must trigger a removal of the 1109 subflow that belongs to this IP/port-pair. 1111 o REM_PATH.SCTP: 1112 Pass 1 primitive / event: 'Change Local Address / Set Peer 1113 Primary' 1114 Parameters: local IP address 1116 o SET_PRIMARY.SCTP: 1117 Pass 1 primitive / event: 'Set Primary' 1118 Parameters: socket 1119 Returns: result of attempting this operation 1120 Comments: update the current primary address to be used, based on 1121 the set of available sockets of the association. 1123 o SET_PEER_PRIMARY.SCTP: 1124 Pass 1 primitive / event: 'Change Local Address / Set Peer 1125 Primary' 1126 Parameters: local IP address 1127 Comments: this is only advisory for the peer. 1129 o CONFIG_SWITCHOVER.SCTP: 1130 Pass 1 primitive / event: 'Configure Path Switchover' 1131 Parameters: primary max retrans (no. of retransmissions after 1132 which a path is considered inactive); PF max retrans (no. of 1133 retransmissions after which a path is considered to be 1134 "Potentially Failed", and others will be preferably used) 1135 (optional) 1137 o STATUS.SCTP: 1138 Pass 1 primitive / event: 'Status', 'Enable / Disable 1139 Interleaving' and 'Network Status Change' notification. 1140 Returns: data block with information about a specified 1141 association, containing: association connection state; destination 1142 transport address list; destination transport address reachability 1143 states; current local and peer receiver window sizes; current 1144 local congestion window sizes; number of unacknowledged DATA 1145 chunks; number of DATA chunks pending receipt; primary path; most 1146 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1147 other destination addresses; MTU per path; interleaving supported 1148 yes/no. 1149 Comments: The 'Network Status Change' notification informs the 1150 application about a socket becoming active/inactive; this only 1151 affects the programming style, as the same information is also 1152 available via 'Status'. 1154 o STATUS.MPTCP: 1155 Pass 1 primitive / event: not specified 1156 Returns: list of pairs of tuples of IP address and TCP port number 1157 of each subflow. The first of the pair is the local IP and port 1158 number, while the second is the remote IP and port number. 1160 o SET_DSCP.TCP: 1161 Pass 1 primitive / event: not specified 1162 Parameters: DSCP value 1163 Comments: this allows an application to change the DSCP value for 1164 outgoing segments. 1166 o SET_DSCP.SCTP: 1167 Pass 1 primitive / event: 'Set DSCP value' 1168 Parameters: DSCP value 1169 Comments: this allows an application to change the DSCP value for 1170 outgoing packets on a path. 1172 o SET_DSCP.UDP(-Lite): 1173 Pass 1 primitive / event: 'Set_DSCP' 1174 Parameter: DSCP value 1175 Comments: This allows an application to change the DSCP value for 1176 outgoing UDP(-Lite) datagrams. [RFC7657] and [RFC8085] provide 1177 current guidance on using this value with UDP. 1179 o ERROR.TCP: 1180 Pass 1 primitive / event: 'Error_Report' 1181 Returns: reason (encoding not specified); subreason (encoding not 1182 specified) 1183 Comments: soft errors that can be ignored without harm by many 1184 applications; an application should be able to disable these 1185 notifications. The reported conditions include at least: ICMP 1186 error message arrived; Excessive Retransmissions. 1188 o ERROR.UDP(-Lite): 1189 Pass 1 primitive / event: 'Error_Report' 1190 Returns: Error report 1191 Comments: This returns soft errors that may be ignored without 1192 harm by many applications; An application must connect to be able 1193 receive these notifications. 1195 o SET_AUTH.TCP: 1196 Pass 1 primitive / event: not specified 1197 Parameters: current_key; rnext_key 1198 Comments: current_key and rnext_key are the preferred outgoing MKT 1199 and the preferred incoming MKT, respectively, for a segment that 1200 is sent on the connection. 1202 o SET_AUTH.SCTP: 1203 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1204 Parameters: key_id; key; hmac_id 1206 o GET_AUTH.TCP: 1207 Pass 1 primitive / event: not specified 1208 Parameters: current_key; rnext_key 1209 Comments: current_key and rnext_key are the preferred outgoing MKT 1210 and the preferred incoming MKT, respectively, that were carried on 1211 a recently received segment. 1213 o GET_AUTH.SCTP: 1214 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1215 Parameters: key_id; chunk_list 1217 o RESET_STREAM.SCTP: 1218 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1219 Parameters: sid; direction 1221 o RESET_STREAM-EVENT.SCTP: 1222 Pass 1 primitive / event: 'Stream Reset' notification 1223 Parameters: information about the result of RESET_STREAM.SCTP. 1224 Comments: This is issued when the procedure for resetting streams 1225 has completed. 1227 o RESET_ASSOC.SCTP: 1228 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1229 Parameters: information related to the extension, defined in 1230 [RFC3260]. 1232 o RESET_ASSOC-EVENT.SCTP: 1233 Pass 1 primitive / event: 'Association Reset' notification 1234 Parameters: information about the result of RESET_ASSOC.SCTP. 1235 Comments: this is issued when the procedure for resetting an 1236 association has completed. 1238 o ADD_STREAM.SCTP: 1239 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1240 Parameters: number if outgoing and incoming streams to be added 1242 o ADD_STREAM-EVENT.SCTP: 1243 Pass 1 primitive / event: 'Stream Change' notification 1244 Parameters: information about the result of ADD_STREAM.SCTP. 1245 Comments: this is issued when the procedure for adding a stream 1246 has completed. 1248 o SET_STREAM_SCHEDULER.SCTP: 1249 Pass 1 primitive / event: 'Set Stream Scheduler' 1250 Parameters: scheduler identifier 1251 Comments: choice of First Come First Serve, Round Robin, Round 1252 Robin per Packet, Priority Based, Fair Bandwidth, Weighted Fair 1253 Queuing. 1255 o CONFIGURE_STREAM_SCHEDULER.SCTP: 1256 Pass 1 primitive / event: 'Configure Stream Scheduler' 1257 Parameters: priority 1258 Comments: the priority value only applies when Priority Based or 1259 Weighted Fair Queuing scheduling is chosen with 1260 SET_STREAM_SCHEDULER.SCTP. The meaning of the parameter differs 1261 between these two schedulers but in both cases it realizes some 1262 form of prioritization regarding how bandwidth is divided among 1263 streams. 1265 o SET_FLOWLABEL.SCTP: 1266 Pass 1 primitive / event: 'Set IPv6 Flow Label' 1267 Parameters: flow label 1268 Comments: this allows an application to change the IPv6 header's 1269 flow label field for outgoing packets on a path. 1271 o AUTHENTICATION_NOTIFICATION-EVENT.SCTP: 1272 Pass 1 primitive / event: 'Authentication' notification 1273 Returns: information regarding key management. 1275 o CONFIG_SEND_BUFFER.SCTP: 1276 Pass 1 primitive / event: 'Configure Send Buffer Size' 1277 Parameters: size value in octets 1279 o CONFIG_RECEIVE_BUFFER.SCTP: 1280 Pass 1 primitive / event: 'Configure Receive Buffer Size' 1281 Parameters: size value in octets 1282 Comments: this controls the receiver window. 1284 o CONFIG_FRAGMENTATION.SCTP: 1285 Pass 1 primitive / event: 'Configure Message Fragmentation' 1286 Parameters: one boolean value (enable/disable); maximum 1287 fragmentation size (optional; default: PMTU) 1288 Comments: if fragmentation is enabled, messages exceeding the 1289 maximum fragmentation size will be fragmented. If fragmentation 1290 is disabled, trying to send a message that exceeds the maximum 1291 fragmentation size will produce an error. 1293 o CONFIG_PMTUD.SCTP: 1294 Pass 1 primitive / event: 'Configure Path MTU Discovery' 1295 Parameters: one boolean value (PMTUD on/off); PMTU value 1296 (optional) 1297 Returns: PMTU value 1298 Comments: this returns a meaningful PMTU value when PMTUD is 1299 enabled (the boolean is true), and the PMTU value can be set if 1300 PMTUD is disabled (the boolean is false) 1302 o CONFIG_DELAYED_SACK.SCTP: 1303 Pass 1 primitive / event: 'Configure Delayed SACK Timer' 1304 Parameters: one boolean value (delayed SACK on/off); timer value 1305 (optional); number of packets to wait for (default 2) 1306 Comments: if delayed SACK is enabled, SCTP will send a SACK upon 1307 either receiving the provided number of packets or when the timer 1308 expires, whatever occurs first. 1310 o CONFIG_RTO.SCTP: 1311 Pass 1 primitive / event: 'Configure RTO Calculation' 1312 Parameters: init (optional); min (optional); max (optional) 1313 Comments: this adjusts the initial, minimum and maximum RTO 1314 values. 1316 o SET_COOKIE_LIFE.SCTP: 1317 Pass 1 primitive / event: 'Set Cookie Life Value' 1318 Parameters: cookie life value 1320 o SET_MAX_BURST.SCTP: 1321 Pass 1 primitive / event: 'Set Maximum Burst' 1322 Parameters: max burst value 1323 Comments: not all implementations allow values above the default 1324 of 4. 1326 o SET_PARTIAL_DELIVERY_POINT.SCTP: 1327 Pass 1 primitive / event: 'Set Partial Delivery Point' 1328 Parameters: partial delivery point (integer) 1329 Comments: this parameter must be smaller or equal to the socket 1330 receive buffer size. 1332 o SET_CHECKSUM_ENABLED.UDP: 1333 Pass 1 primitive / event: 'Checksum_Enabled'. 1334 Parameters: 0 when zero checksum is used at sender, 1 for checksum 1335 at sender (default) 1337 o SET_CHECKSUM_REQUIRED.UDP: 1338 Pass 1 primitive / event: 'Require_Checksum'. 1339 Parameter: 0 to allow zero checksum, 1 when a non-zero checksum is 1340 required (default) at receiver 1342 o SET_CHECKSUM_COVERAGE.UDP-Lite: 1343 Pass 1 primitive / event: 'Set_Checksum_Coverage' 1344 Parameters: coverage length at sender (default maximum coverage) 1346 o SET_MIN_CHECKSUM_COVERAGE.UDP-Lite: 1347 Pass 1 primitive / event: 'Set_Min_Coverage'. 1348 Parameter: coverage length at receiver (default minimum coverage) 1350 o SET_DF.UDP(-Lite): 1351 Pass 1 primitive event: 'Set_DF'. 1352 Parameter: 0 when DF is not set (default) in the IPv4 header, 1 1353 when DF is set 1355 o GET_MMS_S.UDP(-Lite): 1356 Pass 1 primitive event: 'Get_MM_S'. 1357 Comments: this retrieves the maximum transport-message size that 1358 may be sent using a non-fragmented IP packet from the configured 1359 interface. 1361 o GET_MMS_R.UDP(-Lite): 1362 Pass 1 primitive event: 'Get_MMS_R'. 1363 Comments: this retrieves the maximum transport-message size that 1364 may be received from the configured interface. 1366 o SET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1367 Pass 1 primitive / event: 'Set_TTL' and 'Set_IPV6_Unicast_Hops' 1368 Parameters: IPv4 TTL value or IPv6 Hop Count value 1369 Comments: this allows an application to change the IPv4 TTL of 1370 IPv6 Hop count value for outgoing UDP(-Lite) datagrams. 1372 o GET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1373 Pass 1 primitive / event: 'Get_TTL' and 'Get_IPV6_Unicast_Hops' 1374 Returns: IPv4 TTL value or IPv6 Hop Count value 1375 Comments: this allows an application to read the the IPv4 TTL of 1376 IPv6 Hop count value from a received UDP(-Lite) datagram. 1378 o SET_ECN.UDP(-Lite): 1379 Pass 1 primitive / event: 'Set_ECN' 1380 Parameters: ECN value 1381 Comments: this allows a UDP(-Lite) application to set the ECN 1382 codepoint field for outgoing UDP(-Lite) datagrams. Defaults to 1383 sending '00'. 1385 o GET_ECN.UDP(-Lite): 1386 Pass 1 primitive / event: 'Get_ECN' 1387 Parameters: ECN value 1388 Comments: this allows a UDP(-Lite) application to read the ECN 1389 codepoint field from a received UDP(-Lite) datagram. 1391 o SET_IP_OPTIONS.UDP(-Lite): 1392 Pass 1 primitive / event: 'Set_IP_Options' 1393 Parameters: options 1394 Comments: this allows a UDP(-Lite) application to set IP Options 1395 for outgoing UDP(-Lite) datagrams. These options can at least be 1396 the Source Route, Record Route, and Time Stamp option. 1398 o GET_IP_OPTIONS.UDP(-Lite): 1399 Pass 1 primitive / event: 'Get_IP_Options' 1400 Returns: options 1401 Comments: this allows a UDP(-Lite) application to receive any IP 1402 options that are contained in a received UDP(-Lite) datagram. 1404 o CONFIGURE.LEDBAT: 1405 Pass 1 primitive / event: N/A 1406 Parameters: enable (boolean); target; allowed_increase; gain_inc; 1407 gain_dec; base_history; current_filter; init_cwnd; min_cwnd 1408 Comments: 'enable' is a newly invented parameter that enables or 1409 disables the whole LEDBAT service. 1411 TERMINATION: 1412 Gracefully or forcefully closing a connection, or being informed 1413 about this event happening. 1415 o CLOSE.TCP: 1416 Pass 1 primitive / event: 'Close' 1417 Comments: this terminates the sending side of a connection after 1418 reliably delivering all remaining data. 1420 o CLOSE.SCTP: 1421 Pass 1 primitive / event: 'Shutdown' 1422 Comments: this terminates a connection after reliably delivering 1423 all remaining data. 1425 o ABORT.TCP: 1426 Pass 1 primitive / event: 'Abort' 1427 Comments: this terminates a connection without delivering 1428 remaining data and sends an error message to the other side. 1430 o ABORT.SCTP: 1431 Pass 1 primitive / event: 'Abort' 1432 Parameters: abort reason to be given to the peer (optional) 1433 Comments: this terminates a connection without delivering 1434 remaining data and sends an error message to the other side. 1436 o ABORT.UDP(-Lite): 1437 Pass 1 primitive event: 'Close' 1438 Comments: this terminates a connection without delivering 1439 remaining data. No further UDP(-Lite) datagrams are sent/received 1440 for this transport service instance. 1442 o TIMEOUT.TCP: 1443 Pass 1 primitive / event: 'User Timeout' event 1444 Comments: the application is informed that the connection is 1445 aborted. This event is executed on expiration of the timeout set 1446 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 1447 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 1449 o TIMEOUT.SCTP: 1450 Pass 1 primitive / event: 'Communication Lost' event 1451 Comments: the application is informed that the connection is 1452 aborted. this event is executed on expiration of the timeout that 1453 should be enabled by default (see the beginning of section 8.3 in 1454 [RFC4960]) and was possibly adjusted in 1455 CONNECTION.MAINTENANCE.CHANGE_TIMEOOUT.SCTP. 1457 o ABORT-EVENT.TCP: 1458 Pass 1 primitive / event: not specified. 1460 o ABORT-EVENT.SCTP: 1461 Pass 1 primitive / event: 'Communication Lost' event 1462 Returns: abort reason from the peer (if available) 1463 Comments: the application is informed that the other side has 1464 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 1466 o CLOSE-EVENT.TCP: 1467 Pass 1 primitive / event: not specified. 1469 o CLOSE-EVENT.SCTP: 1470 Pass 1 primitive / event: 'Shutdown Complete' event 1471 Comments: the application is informed that 1472 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 1474 4.2. DATA Transfer Related Primitives 1476 All primitives in this section refer to an existing connection, i.e. 1477 a connection that was either established or made available for 1478 receiving data (although this is optional for the primitives of UDP(- 1479 Lite)). In addition to the listed parameters, all sending primitives 1480 contain a reference to a data block and all receiving primitives 1481 contain a reference to available buffer space for the data. Note 1482 that CONNECT.TCP and LISTEN.TCP in the ESTABLISHMENT and AVAILABILITY 1483 category also allow to transfer data (an optional user message) 1484 before the connection is fully established. 1486 o SEND.TCP: 1487 Pass 1 primitive / event: 'Send' 1488 Parameters: timeout (optional); current_key (optional); rnext_key 1489 (optional) 1490 Comments: this gives TCP a data block for reliable transmission to 1491 the TCP on the other side of the connection. The timeout can be 1492 configured with this call (see also 1493 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 'current_key' and 1494 'rnext_key' are authentication parameters that can be configured 1495 with this call (see also CONNECTION.MAINTENANCE.SET_AUTH.TCP). 1497 o SEND.SCTP: 1498 Pass 1 primitive / event: 'Send' 1499 Parameters: stream number; context (optional); socket (optional); 1500 unordered flag (optional); no-bundle flag (optional); payload 1501 protocol-id (optional); pr-policy (optional) pr-value (optional); 1502 sack-immediately flag (optional); key-id (optional) 1503 Comments: this gives SCTP a data block for transmission to the 1504 SCTP on the other side of the connection (SCTP association). The 1505 'stream number' denotes the stream to be used. The 'context' 1506 number can later be used to refer to the correct message when an 1507 error is reported. The 'socket' can be used to state which path 1508 should be preferred, if there are multiple paths available (see 1509 also CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can 1510 be delivered out-of-order if the 'unordered flag' is set. The 1511 'no-bundle flag' can be set to indicate a preference to avoid 1512 bundling. The 'payload protocol-id' is a number that will, if 1513 provided, be handed over to the receiving application. Using pr- 1514 policy and pr-value the level of reliability can be controlled. 1515 The 'sack-immediately' flag can be used to indicate that the peer 1516 should not delay the sending of a SACK corresponding to the 1517 provided user message. If specified, the provided key-id is used 1518 for authenticating the user message. 1520 o SEND.UDP(-Lite): 1521 Pass 1 primitive / event: 'Send' 1522 Parameters: IP Address and Port Number of the destination endpoint 1523 (optional if connected) 1524 Comments: this provides a message for unreliable transmission 1525 using UDP(-Lite) to the specified transport address. IP address 1526 and Port may be omitted for connected UDP(-Lite) sockets. All 1527 CONNECTION.MAINTENANCE.SET_*.UDP(-Lite) primitives apply per 1528 message sent. 1530 o RECEIVE.TCP: 1531 Pass 1 primitive / event: 'Receive'. 1532 Parameters: current_key (optional); rnext_key (optional) 1533 Comments: 'current_key' and 'rnext_key' are authentication 1534 parameters that can be read with this call (see also 1535 CONNECTION.MAINTENANCE.GET_AUTH.TCP). 1537 o RECEIVE.SCTP: 1538 Pass 1 primitive / event: 'Data Arrive' notification, followed by 1539 'Receive' 1540 Parameters: stream number (optional) 1541 Returns: stream sequence number (optional); partial flag 1542 (optional) 1543 Comments: if the 'stream number' is provided, the call to receive 1544 only receives data on one particular stream. If a partial message 1545 arrives, this is indicated by the 'partial flag', and then the 1546 'stream sequence number' must be provided such that an application 1547 can restore the correct order of data blocks that comprise an 1548 entire message. Additionally, a delivery number lets the 1549 application detect reordering. 1551 o RECEIVE.UDP(-Lite): 1552 Pass 1 primitive / event: 'Receive', 1553 Parameters: buffer for received datagram 1554 Comments: all CONNECTION.MAINTENANCE.GET_*.UDP(-Lite) primitives 1555 apply per message received. 1557 o SENDFAILURE-EVENT.SCTP: 1558 Pass 1 primitive / event: 'Send Failure' notification, optionally 1559 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 1560 Message' 1561 Returns: cause code; context; unsent or unacknowledged message 1562 (optional) 1563 Comments: 'cause code' indicates the reason of the failure, and 1564 'context' is the context number if such a number has been provided 1565 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 1566 'Receive Unacknowledged Message', respectively. These primitives 1567 can be used to retrieve the unsent or unacknowledged message (or 1568 part of the message, in case a part was delivered) if desired. 1570 o SEND_FAILURE.UDP(-Lite): 1571 Pass 1 primitive / event: 'Send' 1572 Comments: this may be used to probe for the effective PMTU when 1573 using in combination with the 'MAINTENANCE.SET_DF' primitive. 1575 o SENDER_DRY-EVENT.SCTP: 1576 Pass 1 primitive / event: 'Sender Dry' notification 1577 Comments: this informs the application that the stack has no more 1578 user data to send. 1580 o PARTIAL_DELIVERY_ABORTED-EVENT.SCTP: 1581 Pass 1 primitive / event: 'Partial Delivery Aborted' notification 1582 Comments: this informs the receiver of a partial message that the 1583 further delivery of the message has been aborted. 1585 5. Pass 3 1587 This section presents the superset of all transport features in all 1588 protocols that were discussed in the preceding sections, based on the 1589 list of primitives in pass 2 but also on text in pass 1 to include 1590 transport features that can be configured in one protocol and are 1591 static properties in another (congestion control, for example). 1592 Again, some minor details are omitted for the sake of generalization 1593 -- e.g., TCP may provide various different IP options, but only 1594 source route is mandatory to implement, and this detail is not 1595 visible in the Pass 3 transport feature "Specify IP Options". As 1596 before, "UDP(-Lite)" represents both UDP and UDP-Lite, and TCP refers 1597 to both TCP and MPTCP. 1599 5.1. CONNECTION Related Transport Features 1601 ESTABLISHMENT: 1602 Active creation of a connection from one transport endpoint to one or 1603 more transport endpoints. 1605 o Connect 1606 Protocols: TCP, SCTP, UDP(-Lite) 1608 o Specify which IP Options must always be used 1609 Protocols: TCP, UDP(-Lite) 1611 o Request multiple streams 1612 Protocols: SCTP 1614 o Limit the number of inbound streams 1615 Protocols: SCTP 1617 o Specify number of attempts and/or timeout for the first 1618 establishment message 1619 Protocols: TCP, SCTP 1621 o Obtain multiple sockets 1622 Protocols: SCTP 1624 o Disable MPTCP 1625 Protocols: MPTCP 1627 o Configure authentication 1628 Protocols: TCP, SCTP 1629 Comments: with TCP, this allows to configure Master Key Tuples 1630 (MKTs). In SCTP, this allows to specify which chunk types must 1631 always be authenticated. DATA, ACK etc. are different 'chunks' in 1632 SCTP; one or more chunks may be included in a single packet. 1634 o Indicate an Adaptation Layer (via an adaptation code point) 1635 Protocols: SCTP 1637 o Request to negotiate interleaving of user messages 1638 Protocols: SCTP 1640 o Hand over a message to transfer (possibly multiple times) before 1641 connection establishment 1642 Protocols: TCP 1644 o Hand over a message to transfer during connection establishment 1645 Protocols: SCTP 1647 o Enable UDP encapsulation with a specified remote UDP port number 1648 Protocols: SCTP 1650 AVAILABILITY: 1651 Preparing to receive incoming connection requests. 1653 o Listen, 1 specified local interface 1654 Protocols: TCP, SCTP, UDP(-Lite) 1656 o Listen, N specified local interfaces 1657 Protocols: SCTP 1659 o Listen, all local interfaces 1660 Protocols: TCP, SCTP, UDP(-Lite) 1662 o Obtain requested number of streams 1663 Protocols: SCTP 1665 o Limit the number of inbound streams 1666 Protocols: SCTP 1668 o Specify which IP Options must always be used 1669 Protocols: TCP, UDP(-Lite) 1671 o Disable MPTCP 1672 Protocols: MPTCP 1674 o Configure authentication 1675 Protocols: TCP, SCTP 1676 Comments: with TCP, this allows to configure Master Key Tuples 1677 (MKTs). In SCTP, this allows to specify which chunk types must 1678 always be authenticated. DATA, ACK etc. are different 'chunks' in 1679 SCTP; one or more chunks may be included in a single packet. 1681 o Indicate an Adaptation Layer (via an adaptation code point) 1682 Protocols: SCTP 1684 MAINTENANCE: 1685 Adjustments made to an open connection, or notifications about it. 1687 o Change timeout for aborting connection (using retransmit limit or 1688 time value) 1689 Protocols: TCP, SCTP 1691 o Suggest timeout to the peer 1692 Protocols: TCP 1694 o Disable Nagle algorithm 1695 Protocols: TCP, SCTP 1697 o Request an immediate heartbeat, returning success/failure 1698 Protocols: SCTP 1700 o Notification of Excessive Retransmissions (early warning below 1701 abortion threshold) 1702 Protocols: TCP 1704 o Add path 1705 Protocols: MPTCP, SCTP 1706 MPTCP Parameters: source-IP; source-Port; destination-IP; 1707 destination-Port 1708 SCTP Parameters: local IP address 1710 o Remove path 1711 Protocols: MPTCP, SCTP 1712 MPTCP Parameters: source-IP; source-Port; destination-IP; 1713 destination-Port 1714 SCTP Parameters: local IP address 1716 o Set primary path 1717 Protocols: SCTP 1719 o Suggest primary path to the peer 1720 Protocols: SCTP 1722 o Configure Path Switchover 1723 Protocols: SCTP 1725 o Obtain status (query or notification) 1726 Protocols: SCTP, MPTCP 1727 SCTP parameters: association connection state; destination 1728 transport address list; destination transport address reachability 1729 states; current local and peer receiver window sizes; current 1730 local congestion window sizes; number of unacknowledged DATA 1731 chunks; number of DATA chunks pending receipt; primary path; most 1732 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1733 other destination addresses; MTU per path; interleaving supported 1734 yes/no 1735 MPTCP parameters: subflow-list (identified by source-IP; source- 1736 Port; destination-IP; destination-Port) 1738 o Specify DSCP field 1739 Protocols: TCP, SCTP, UDP(-Lite) 1741 o Notification of ICMP error message arrival 1742 Protocols: TCP, UDP(-Lite) 1744 o Change authentication parameters 1745 Protocols: TCP, SCTP 1747 o Obtain authentication information 1748 Protocols: TCP, SCTP 1750 o Reset Stream 1751 Protocols: SCTP 1753 o Notification of Stream Reset 1754 Protocols: STCP 1756 o Reset Association 1757 Protocols: SCTP 1759 o Notification of Association Reset 1760 Protocols: STCP 1762 o Add Streams 1763 Protocols: SCTP 1765 o Notification of Added Stream 1766 Protocols: STCP 1768 o Choose a scheduler to operate between streams of an association 1769 Protocols: SCTP 1771 o Configure priority or weight for a scheduler 1772 Protocols: SCTP 1774 o Specify IPv6 flow label field 1775 Protocols: SCTP 1777 o Configure send buffer size 1778 Protocols: SCTP 1780 o Configure receive buffer (and rwnd) size 1781 Protocols: SCTP 1783 o Configure message fragmentation 1784 Protocols: SCTP 1786 o Configure PMTUD 1787 Protocols: SCTP 1789 o Configure delayed SACK timer 1790 Protocols: SCTP 1792 o Set Cookie life value 1793 Protocols: SCTP 1795 o Set maximum burst 1796 Protocols: SCTP 1798 o Configure size where messages are broken up for partial delivery 1799 Protocols: SCTP 1801 o Disable checksum when sending 1802 Protocols: UDP 1804 o Disable checksum requirement when receiving 1805 Protocols: UDP 1807 o Specify checksum coverage used by the sender 1808 Protocols: UDP-Lite 1810 o Specify minimum checksum coverage required by receiver 1811 Protocols: UDP-Lite 1813 o Specify DF field 1814 Protocols: UDP(-Lite) 1816 o Get max. transport-message size that may be sent using a non- 1817 fragmented IP packet from the configured interface 1818 Protocols: UDP(-Lite) 1820 o Get max. transport-message size that may be received from the 1821 configured interface 1822 Protocols: UDP(-Lite) 1824 o Specify TTL/Hop count field 1825 Protocols: UDP(-Lite) 1827 o Obtain TTL/Hop count field 1828 Protocols: UDP(-Lite) 1830 o Specify ECN field 1831 Protocols: UDP(-Lite) 1833 o Obtain ECN field 1834 Protocols: UDP(-Lite) 1836 o Specify IP Options 1837 Protocols: UDP(-Lite) 1839 o Obtain IP Options 1840 Protocols: UDP(-Lite) 1842 o Enable and configure "Low Extra Delay Background Transfer" 1843 Protocols: A protocol implementing the LEDBAT congestion control 1844 mechanism 1846 TERMINATION: 1847 Gracefully or forcefully closing a connection, or being informed 1848 about this event happening. 1850 o Close after reliably delivering all remaining data, causing an 1851 event informing the application on the other side 1852 Protocols: TCP, SCTP 1853 Comments: a TCP endpoint locally only closes the connection for 1854 sending; it may still receive data afterwards. 1856 o Abort without delivering remaining data, causing an event 1857 informing the application on the other side 1858 Protocols: TCP, SCTP 1859 Comments: in SCTP a reason can optionally be given by the 1860 application on the aborting side, which can then be received by 1861 the application on the other side. 1863 o Abort without delivering remaining data, not causing an event 1864 informing the application on the other side 1865 Protocols: UDP(-Lite) 1867 o Timeout event when data could not be delivered for too long 1868 Protocols: TCP, SCTP 1869 Comments: the timeout is configured with CONNECTION.MAINTENANCE 1870 "Change timeout for aborting connection (using retransmit limit or 1871 time value)". 1873 5.2. DATA Transfer Related Transport Features 1875 All transport features in this section refer to an existing 1876 connection, i.e. a connection that was either established or made 1877 available for receiving data. Note that TCP allows to transfer data 1878 (a single optional user message, possibly arriving multiple times) 1879 before the connection is fully established. Reliable data transfer 1880 entails delay -- e.g. for the sender to wait until it can transmit 1881 data, or due to retransmission in case of packet loss. 1883 5.2.1. Sending Data 1885 All transport features in this section are provided by DATA.SEND from 1886 pass 2. DATA.SEND is given a data block from the application, which 1887 we here call a "message" if the beginning and end of the data block 1888 can be identified at the receiver, and "data" otherwise. 1890 o Reliably transfer data, with congestion control 1891 Protocols: TCP 1893 o Reliably transfer a message, with congestion control 1894 Protocols: SCTP 1896 o Unreliably transfer a message, with congestion control 1897 Protocols: SCTP 1899 o Unreliably transfer a message, without congestion control 1900 Protocols: UDP(-Lite) 1902 o Configurable Message Reliability 1903 Protocols: SCTP 1905 o Choice of stream 1906 Protocols: SCTP 1908 o Choice of path (destination address) 1909 Protocols: SCTP 1911 o Choice between unordered (potentially faster) or ordered delivery 1912 of messages 1913 Protocols: SCTP 1915 o Request not to bundle messages 1916 Protocols: SCTP 1918 o Specifying a "payload protocol-id" (handed over as such by the 1919 receiver) 1920 Protocols: SCTP 1922 o Specifying a key id to be used to authenticate a message 1923 Protocols: SCTP 1925 o Request not to delay the acknowledgement (SACK) of a message 1926 Protocols: SCTP 1928 5.2.2. Receiving Data 1930 All transport features in this section are provided by DATA.RECEIVE 1931 from pass 2. DATA.RECEIVE fills a buffer provided by the 1932 application, with what we here call a "message" if the beginning and 1933 end of the data block can be identified at the receiver, and "data" 1934 otherwise. 1936 o Receive data (with no message delineation) 1937 Protocols: TCP 1939 o Receive a message 1940 Protocols: SCTP, UDP(-Lite) 1942 o Choice of stream to receive from 1943 Protocols: SCTP 1945 o Information about partial message arrival 1946 Protocols: SCTP 1947 Comments: in SCTP, partial messages are combined with a stream 1948 sequence number so that the application can restore the correct 1949 order of data blocks an entire message consists of. 1951 o Obtain a message delivery number 1952 Protocols: SCTP 1953 Comments: this number can let applications detect and, if desired, 1954 correct reordering. 1956 5.2.3. Errors 1958 This section describes sending failures that are associated with a 1959 specific call to DATA.SEND from pass 2. 1961 o Notification of an unsent (part of a) message 1962 Protocols: SCTP, UDP(-Lite) 1964 o Notification of an unacknowledged (part of a) message 1965 Protocols: SCTP 1967 o Notification that the stack has no more user data to send 1968 Protocols: SCTP 1970 o Notification to a receiver that a partial message delivery has 1971 been aborted 1972 Protocols: SCTP 1974 6. Acknowledgements 1976 The authors would like to thank (in alphabetical order) Bob Briscoe, 1977 Aaron Falk, David Hayes, Karen Nielsen, Tommy Pauly, Joe Touch and 1978 Brian Trammell for providing valuable feedback on this document. We 1979 especially thank Christoph Paasch for providing input related to 1980 Multipath TCP, and Gorry Fairhurst and Tom Jones for providing input 1981 related to UDP(-Lite). This work has received funding from the 1982 European Union's Horizon 2020 research and innovation programme under 1983 grant agreement No. 644334 (NEAT). The views expressed are solely 1984 those of the author(s). 1986 7. IANA Considerations 1988 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 1990 This memo includes no request to IANA. 1992 8. Security Considerations 1994 Authentication, confidentiality protection, and integrity protection 1995 are identified as transport features [RFC8095]. As currently 1996 deployed in the Internet, these transport features are generally 1997 provided by a protocol or layer on top of the transport protocol; no 1998 current full-featured standards-track transport protocol provides 1999 these transport features on its own. Therefore, these transport 2000 features are not considered in this document, with the exception of 2001 native authentication capabilities of TCP and SCTP for which the 2002 security considerations in [RFC5925] and [RFC4895] apply. 2004 Security considerations for the use of UDP and UDP-Lite are provided 2005 in the referenced RFCs. Security guidance for application usage is 2006 provided in the UDP-Guidelines [RFC8085]. 2008 9. References 2010 9.1. Normative References 2012 [FJ16] Fairhurst, G. and T. Jones, "Features of the User Datagram 2013 Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport 2014 Protocols", draft-ietf-taps-transports-usage-udp-04 (work 2015 in progress), July 2017. 2017 [I-D.ietf-tsvwg-sctp-ndata] 2018 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2019 "Stream Schedulers and User Message Interleaving for the 2020 Stream Control Transmission Protocol", 2021 draft-ietf-tsvwg-sctp-ndata-08 (work in progress), 2022 October 2016. 2024 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2025 RFC 793, DOI 10.17487/RFC0793, September 1981, 2026 . 2028 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2029 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 2030 RFC1122, October 1989, 2031 . 2033 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 2034 Conrad, "Stream Control Transmission Protocol (SCTP) 2035 Partial Reliability Extension", RFC 3758, DOI 10.17487/ 2036 RFC3758, May 2004, 2037 . 2039 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 2040 "Authenticated Chunks for the Stream Control Transmission 2041 Protocol (SCTP)", RFC 4895, DOI 10.17487/RFC4895, 2042 August 2007, . 2044 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2045 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2046 . 2048 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 2049 Kozuka, "Stream Control Transmission Protocol (SCTP) 2050 Dynamic Address Reconfiguration", RFC 5061, DOI 10.17487/ 2051 RFC5061, September 2007, 2052 . 2054 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 2055 RFC 5482, DOI 10.17487/RFC5482, March 2009, 2056 . 2058 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2059 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2060 June 2010, . 2062 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 2063 Iyengar, "Architectural Guidelines for Multipath TCP 2064 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 2065 . 2067 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 2068 Yasevich, "Sockets API Extensions for the Stream Control 2069 Transmission Protocol (SCTP)", RFC 6458, DOI 10.17487/ 2070 RFC6458, December 2011, 2071 . 2073 [RFC6525] Stewart, R., Tuexen, M., and P. Lei, "Stream Control 2074 Transmission Protocol (SCTP) Stream Reconfiguration", 2075 RFC 6525, DOI 10.17487/RFC6525, February 2012, 2076 . 2078 [RFC6817] Shalunov, S., Hazel, G., Iyengar, J., and M. Kuehlewind, 2079 "Low Extra Delay Background Transport (LEDBAT)", RFC 6817, 2080 DOI 10.17487/RFC6817, December 2012, 2081 . 2083 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 2084 "TCP Extensions for Multipath Operation with Multiple 2085 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 2086 . 2088 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 2089 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 2090 March 2013, . 2092 [RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream 2093 Control Transmission Protocol (SCTP) Packets for End-Host 2094 to End-Host Communication", RFC 6951, DOI 10.17487/ 2095 RFC6951, May 2013, 2096 . 2098 [RFC7053] Tuexen, M., Ruengeler, I., and R. Stewart, "SACK- 2099 IMMEDIATELY Extension for the Stream Control Transmission 2100 Protocol", RFC 7053, DOI 10.17487/RFC7053, November 2013, 2101 . 2103 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2104 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2105 . 2107 [RFC7496] Tuexen, M., Seggelmann, R., Stewart, R., and S. Loreto, 2108 "Additional Policies for the Partially Reliable Stream 2109 Control Transmission Protocol Extension", RFC 7496, 2110 DOI 10.17487/RFC7496, April 2015, 2111 . 2113 [RFC7829] Nishida, Y., Natarajan, P., Caro, A., Amer, P., and K. 2114 Nielsen, "SCTP-PF: A Quick Failover Algorithm for the 2115 Stream Control Transmission Protocol", RFC 7829, 2116 DOI 10.17487/RFC7829, April 2016, 2117 . 2119 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2120 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2121 March 2017, . 2123 9.2. Informative References 2125 [I-D.draft-gjessing-taps-minset] 2126 Gjessing, S. and M. Welzl, "A Minimal Set of Transport 2127 Services for TAPS Systems", draft-gjessing-taps-minset-05 2128 (work in progress), June 2017. 2130 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 2131 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, 2132 May 1983, . 2134 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2135 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2136 RFC2119, March 1997, 2137 . 2139 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2140 "Definition of the Differentiated Services Field (DS 2141 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2142 DOI 10.17487/RFC2474, December 1998, 2143 . 2145 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., 2146 and W. Weiss, "An Architecture for Differentiated 2147 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 2148 . 2150 [RFC3260] Grossman, D., "New Terminology and Clarifications for 2151 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 2152 . 2154 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 2155 DOI 10.17487/RFC5461, February 2009, 2156 . 2158 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 2159 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 2160 January 2011, . 2162 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 2163 Zimmermann, "A Roadmap for Transmission Control Protocol 2164 (TCP) Specification Documents", RFC 7414, DOI 10.17487/ 2165 RFC7414, February 2015, 2166 . 2168 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2169 (Diffserv) and Real-Time Communication", RFC 7657, 2170 DOI 10.17487/RFC7657, November 2015, 2171 . 2173 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2174 Ed., "Services Provided by IETF Transport Protocols and 2175 Congestion Control Mechanisms", RFC 8095, DOI 10.17487/ 2176 RFC8095, March 2017, 2177 . 2179 Appendix A. Overview of RFCs used as input for pass 1 2181 TCP: [RFC0793], [RFC1122], [RFC5482], [RFC5925], [RFC7413] 2182 MPTCP: [RFC6182], [RFC6824], [RFC6897] 2183 SCTP: RFCs without a socket API specification: [RFC3758], [RFC4895], 2184 [RFC4960], [RFC5061]. 2185 RFCs that include a socket API specification: [RFC6458], 2186 [RFC6525], [RFC6951], [RFC7053], [RFC7496] [RFC7829]. 2187 UDP(-Lite): See [FJ16] 2188 LEDBAT: [RFC6817]. 2190 Appendix B. How this document was developed 2192 This section gives an overview of the method that was used to develop 2193 this document. It was given to contributors for guidance, and it can 2194 be helpful for future updates or extensions. 2196 This document is only concerned with transport features that are 2197 explicitly exposed to applications via primitives. It also strictly 2198 follows RFC text: if a transport feature is truly relevant for an 2199 application, the RFCs should say so, and they should describe how to 2200 use and configure it. Thus, the approach followed for developing 2201 this document was to identify the right RFCs, then analyze and 2202 process their text. 2204 Primitives that MAY be implemented by a transport protocol were 2205 excluded. To be included, the minimum requirement level for a 2206 primitive to be implemented by a protocol was SHOULD. Where 2207 [RFC2119]-style requirements levels are not used, primitives were 2208 excluded when they are described in conjunction with statements like, 2209 e.g.: "some implementations also provide" or "an implementation may 2210 also". Excluded primitives or parameters were briefly described in a 2211 dedicated subsection. 2213 Pass 1: This began by identifying text that talks about primitives. 2214 An API specification, abstract or not, obviously describes primitives 2215 -- but we are not *only* interested in API specifications. The text 2216 describing the 'send' primitive in the API specified in [RFC0793], 2217 for instance, does not say that data transfer is reliable. TCP's 2218 reliability is clear, however, from this text in Section 1 of 2219 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 2220 use as a highly reliable host-to-host protocol between hosts in 2221 packet-switched computer communication networks, and in 2222 interconnected systems of such networks." 2224 Some text for pass 1 subsections was developed copy+pasting all the 2225 relevant text parts from the relevant RFCs, then adjusting 2226 terminology to match the terminology in Section 1 and adjusting 2227 (shortening!) phrasing to match the general style of the document. 2228 An effort was made to formulate everything as a primitive description 2229 such that the primitive descriptions became as complete as possible 2230 (e.g., the "SEND.TCP" primitive in pass 2 is explicitly described as 2231 reliably transferring data); text that is relevant for the primitives 2232 presented in this pass but still does not fit directly under any 2233 primitive was used in a subsection's introduction. 2235 Pass 2: The main goal of this pass is unification of primitives. As 2236 input, only text from pass 1 was used (no exterior sources). The 2237 list in pass 2 is not arranged by protocol ("first protocol X, here 2238 are all the primitives; then protocol Y, here are all the primitives, 2239 ..") but by primitive ("primitive A, implemented this way in protocol 2240 X, this way in protocol Y, ..."). It was a goal to obtain as many 2241 similar pass 2 primitives as possible. For instance, this was 2242 sometimes achieved by not always maintaining a 1:1 mapping between 2243 pass 1 and pass 2 primitives, renaming primitives etc. For every new 2244 primitive, the already existing primitives were considered to try to 2245 make them as coherent as possible. 2247 For each primitive, the following style was used: 2249 o PRIMITIVENAME.PROTOCOL: 2250 Pass 1 primitive / event: 2251 Parameters: 2252 Returns: 2253 Comments: 2255 The entries "Parameters", "Returns" and "Comments" were skipped when 2256 a primitive had no parameters, no described return value or no 2257 comments seemed necessary, respectively. Optional parameters are 2258 followed by "(optional)". When a default value is known, this was 2259 also provided. 2261 Pass 3: the main point of this pass is to identify transport features 2262 that are the result of static properties of protocols, for which all 2263 protocols have to be listed together; this is then the final list of 2264 all available transport features. This list was primarily based on 2265 text from pass 2, with additional input from pass 1 (but no external 2266 sources). 2268 Appendix C. Revision information 2270 XXX RFC-Ed please remove this section prior to publication. 2272 -00 (from draft-welzl-taps-transports): this now covers TCP based on 2273 all TCP RFCs (this means: if you know of something in any TCP RFC 2274 that you think should be addressed, please speak up!) as well as 2275 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 2276 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 2277 in line with [RFC8095]. Addressed comments by Karen Nielsen and 2278 Gorry Fairhurst; various other fixes. Appendices (TCP overview and 2279 how-to-contribute) added. 2281 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 2282 [RFC6897]. 2284 -02: included UDP, UDP-Lite, and all extensions of SCTPs. This 2285 includes fixing the [RFC6458] omission from -00. 2287 -03: wrote security considerations. The "how to contribute" section 2288 was updated to reflect how the document WAS created, not how it 2289 SHOULD BE created; it also no longer wrongly says that Experimental 2290 RFCs are excluded. Included LEDBAT. Changed abstract and intro to 2291 reflect which protocols/mechanisms are covered (TCP, MPTCP, SCTP, 2292 UDP, UDP-Lite, LEDBAT) instead of talking about "transport 2293 protocols". Interleaving and stream scheduling added 2294 (draft-ietf-tsvwg-sctp-ndata). TFO added. "Set protocol parameters" 2295 in SCTP replaced with per-parameter (or parameter group) primitives. 2296 More primitives added, mostly previously overlooked ones from 2297 [RFC6458]. Updated terminology (s/transport service feature/ 2298 transport feature) in line with an update of [RFC8095]. Made 2299 sequence of transport features / primitives more logical. Combined 2300 MPTCP's add/rem subflow with SCTP's add/remove local address. 2302 -04: changed UDP's close into an ABORT (to better fit with the 2303 primitives of TCP and SCTP), and incorporated the corresponding 2304 transport feature in step 3 (this addresses a comment from Gorry 2305 Fairhurst). Added TCP Authentication (RFC 5925, section 7.1). 2306 Changed TFO from looking like a primitive in pass 1 to be a part of 2307 'open'. Changed description of SCTP authentication in pass 3 to 2308 encompass both TCP and SCTP. Added citations of [RFC8095] and minset 2309 [I-D.draft-gjessing-taps-minset] to the intro, to give the context of 2310 this document. 2312 -05: minor fix to TCP authentication (comment from Joe Touch), 2313 several fixes from Gorry Fairhurst and Tom Jones. Language fixes; 2314 updated to align with latest taps-transport-usage-udp ID. 2316 -06: addressed WGLC comments from Aaron Falk and Tommy Pauly. 2318 Authors' Addresses 2320 Michael Welzl 2321 University of Oslo 2322 PO Box 1080 Blindern 2323 Oslo, N-0316 2324 Norway 2326 Email: michawe@ifi.uio.no 2328 Michael Tuexen 2329 Muenster University of Applied Sciences 2330 Stegerwaldstrasse 39 2331 Steinfurt 48565 2332 Germany 2334 Email: tuexen@fh-muenster.de 2336 Naeem Khademi 2337 University of Oslo 2338 PO Box 1080 Blindern 2339 Oslo, N-0316 2340 Norway 2342 Email: naeemk@ifi.uio.no