idnits 2.17.1 draft-ietf-taps-transports-usage-09.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 : ---------------------------------------------------------------------------- == 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 (October 26, 2017) is 2373 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 871, but not defined == Unused Reference: 'RFC2119' is defined on line 2349, 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: 4 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: April 29, 2018 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 October 26, 2017 10 On the Usage of Transport Features Provided by IETF Transport Protocols 11 draft-ietf-taps-transports-usage-09 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. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on April 29, 2018. 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . . 5 63 3.1.1. Excluded Primitives or Parameters . . . . . . . . . . 9 64 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . . 10 65 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 11 66 3.3.1. Excluded Primitives or Parameters . . . . . . . . . . 18 67 3.4. Primitives Provided by UDP and UDP-Lite . . . . . . . . . 18 68 3.5. The service of LEDBAT . . . . . . . . . . . . . . . . . . 18 69 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 70 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 20 71 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . . 38 72 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 73 5.1. CONNECTION Related Transport Features . . . . . . . . . . 41 74 5.2. DATA Transfer Related Transport Features . . . . . . . . . 47 75 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . . 47 76 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . . 48 77 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . 49 78 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 49 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 50 81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50 82 9.1. Normative References . . . . . . . . . . . . . . . . . . . 50 83 9.2. Informative References . . . . . . . . . . . . . . . . . . 52 84 Appendix A. Overview of RFCs used as input for pass 1 . . . . . . 53 85 Appendix B. How this document was developed . . . . . . . . . . . 54 86 Appendix C. Revision information . . . . . . . . . . . . . . . . 55 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 57 89 1. Terminology 91 Transport Feature: a specific end-to-end feature that the transport 92 layer provides to an application. Examples include 93 confidentiality, reliable delivery, ordered delivery, message- 94 versus-stream orientation, etc. 95 Transport Service: a set of Transport Features, without an 96 association to any given framing protocol, which provides a 97 complete service to an application. 98 Transport Protocol: an implementation that provides one or more 99 transport services using a specific framing and header format on 100 the wire. 101 Transport Protocol Component: an implementation of a Transport 102 Feature within a protocol. 103 Transport Service Instance: an arrangement of transport protocols 104 with a selected set of features and configuration parameters that 105 implements a single transport service, e.g., a protocol stack (RTP 106 over UDP). 107 Application: an entity that uses the transport layer for end-to-end 108 delivery of data across the network (this may also be an upper 109 layer protocol or tunnel encapsulation). 110 Endpoint: an entity that communicates with one or more other 111 endpoints using a transport protocol. 112 Connection: shared state of two or more endpoints that persists 113 across messages that are transmitted between these endpoints. 114 Primitive: a function call that is used to locally communicate 115 between an application and a transport endpoint. A primitive is 116 related to one or more Transport Features. 117 Event: a primitive that is invoked by a transport endpoint. 118 Parameter: a value passed between an application and a transport 119 protocol by a primitive. 120 Socket: the combination of a destination IP address and a 121 destination port number. 122 Transport Address: the combination of an IP address, transport 123 protocol and the port number used by the transport protocol. 125 2. Introduction 127 This specification describes an abstract interface for applications 128 to make use of Transport Services, such that applications are no 129 longer directly tied to a specific protocol. Breaking this strict 130 connection can reduce the effort for an application programmer, yet 131 attain greater transport flexibility by pushing complexity into an 132 underlying Transport Services (TAPS) system. 134 This design process has started with a survey of the services 135 provided by IETF transport protocols and congestion control 136 mechanisms [RFC8095]. The present document and [FJ16] complement 137 this survey with an in-depth look at the defined interactions between 138 applications and the following unicast transport protocols: 139 Transmission Control Protocol (TCP), MultiPath TCP (MPTCP), Stream 140 Control Transmission Protocol (SCTP), User Datagram Protocol (UDP), 141 Lightweight User Datagram Protocol (UDP-Lite). We also define a 142 primitive to enable/disable and configure the Low Extra Delay 143 Background Transport (LEDBAT) unicast congestion control mechanism. 144 For UDP and UDP-Lite, the first step of the protocol analysis -- a 145 discussion of relevant RFC text -- is documented in [FJ16]. 147 This snapshot in time analysis of the IETF transport protocols is 148 published as an RFC to document the authors' and working group's 149 analysis, generating a set of transport abstractions that can be 150 exported in a TAPS API. It provides the basis for the minimal set of 151 transport services that end systems supporting TAPS should implement 152 [I-D.draft-gjessing-taps-minset]. 154 The list of primitives, events and transport features in this 155 document is strictly based on the parts of protocol specifications 156 that describe what the protocol provides to an application using it 157 and how the application interacts with it. Transport protocols 158 provide communication between processes that operate on network 159 endpoints, which means that they allow for multiplexing of 160 communication between the same IP addresses, and this multiplexing is 161 achieved using port numbers. Port multiplexing is therefore assumed 162 to be always provided and not discussed in this document. 164 Parts of a protocol that are explicitly stated as optional to 165 implement are not covered. Interactions between the application and 166 a transport protocol that are not directly related to the operation 167 of the protocol are also not covered. For example, there are various 168 ways for an application to use socket options to indicate its 169 interest in receiving certain notifications [RFC6458]. However, for 170 the purpose of identifying primitives, events and transport features, 171 the ability to enable or disable the reception of notifications is 172 irrelevant. Similarly, "one-to-many style sockets" [RFC6458] just 173 affect the application programming style, not how the underlying 174 protocol operates, and they are therefore not discussed here. The 175 same is true for the ability to obtain the unchanged value of a 176 parameter that an application has previously set (e.g.,via "get" in 177 get/set operations [RFC6458]). 179 The document presents a three-pass process to arrive at a list of 180 transport features. In the first pass, the relevant RFC text is 181 discussed per protocol. In the second pass, this discussion is used 182 to derive a list of primitives and events that are uniformly 183 categorized across protocols. Here, an attempt is made to present or 184 -- where text describing primitives or events does not yet exist -- 185 construct primitives or events in a slightly generalized form to 186 highlight similarities. This is, for example, achieved by renaming 187 primitives or events of protocols or by avoiding a strict 1:1-mapping 188 between the primitives or events in the protocol specification and 189 primitives or events in the list. Finally, the third pass presents 190 transport features based on pass 2, identifying which protocols 191 implement them. 193 In the list resulting from the second pass, some transport features 194 are missing because they are implicit in some protocols, and they 195 only become explicit when we consider the superset of all transport 196 features offered by all protocols. For example, TCP always carries 197 out congestion control; we have to consider it together with a 198 protocol like UDP (which does not have congestion control) before we 199 can consider congestion control as a transport feature. The complete 200 list of transport features across all protocols is therefore only 201 available after pass 3. 203 Some protocols are connection-oriented. Connection-oriented 204 protocols often use an initial call to a specific primitive to open a 205 connection before communication can progress, and require 206 communication to be explicitly terminated by issuing another call to 207 a primitive (usually called "close"). A "connection" is the common 208 state that some transport primitives refer to, e.g., to adjust 209 general configuration settings. Connection establishment, 210 maintenance and termination are therefore used to categorize 211 transport primitives of connection-oriented transport protocols in 212 pass 2 and pass 3. For this purpose, UDP is assumed to be used with 213 "connected" sockets, i.e. sockets that are bound to a specific pair 214 of addresses and ports [FJ16]. 216 3. Pass 1 218 This first iteration summarizes the relevant text parts of the RFCs 219 describing the protocols, focusing on what each transport protocol 220 provides to the application and how it is used (abstract API 221 descriptions, where they are available). When presenting primitives, 222 events and parameters, the use of lower- and upper-case characters is 223 made uniform for the sake of readability. 225 3.1. Primitives Provided by TCP 227 The initial TCP specification [RFC0793] states: "The Transmission 228 Control Protocol (TCP) is intended for use as a highly reliable host- 229 to-host protocol between hosts in packet-switched computer 230 communication networks, and in interconnected systems of such 231 networks". Section 3.8 in this specification [RFC0793] further 232 specifies the interaction with the application by listing several 233 transport primitives. It is also assumed that an Operating System 234 provides a means for TCP to asynchronously signal the application; 235 the primitives representing such signals are called 'events' in this 236 section. This section describes the relevant primitives. 238 Open: this is either active or passive, to initiate a connection or 239 listen for incoming connections. All other primitives are 240 associated with a specific connection, which is assumed to first 241 have been opened. An active open call contains a socket. A 242 passive open call with a socket waits for a particular connection; 243 alternatively, a passive open call can leave the socket 244 unspecified to accept any incoming connection. A fully specified 245 passive call can later be made active by calling 'Send'. 246 Optionally, a timeout can be specified, after which TCP will abort 247 the connection if data has not been successfully delivered to the 248 destination (else a default timeout value is used). A procedure 249 for aborting the connection is used to avoid excessive 250 retransmissions, and an application is able to control the 251 threshold used to determine the condition for aborting; this 252 threshold may be measured in time units or as a count of 253 retransmission [RFC1122]. This indicates that the timeout could 254 also be specified as a count of retransmission. 256 Also optional, for multihomed hosts, the local IP address can be 257 provided [RFC1122]. If it is not provided, a default choice will 258 be made in case of active open calls. A passive open call will 259 await incoming connection requests to all local addresses and then 260 maintain usage of the local IP address where the incoming 261 connection request has arrived. Finally, the 'options' parameter 262 allows the application to specify IP options such as source route, 263 record route, or timestamp [RFC1122]. It is not stated on which 264 segments of a connection these options should be applied, but 265 probably all segments, as this is also stated in a specification 266 given for the usage of source route (section 4.2.3.8 of 267 [RFC1122]). Source route is the only non-optional IP option in 268 this parameter, allowing an application to specify a source route 269 when it actively opens a TCP connection. 271 Master Key Tuples (MKTs) for authentication can optionally be 272 configured when calling open (section 7.1 of [RFC5925]). When 273 authentication is in use, complete TCP segments are authenticated, 274 including the TCP IPv4 pseudoheader, TCP header, and TCP data. 276 TCP Fast Open (TFO) [RFC7413] allows applications to immediately 277 hand over a message from the active open to the passive open side 278 of a TCP connection together with the first message establishment 279 packet (the SYN). This can be useful for applications that are 280 sensitive to TCP's connection setup delay. [RFC7413] states that 281 "TCP implementations MUST NOT use TFO by default, but only use TFO 282 if requested explicitly by the application on a per-service-port 283 basis". The size of the message sent with TFO cannot be more than 284 TCP's maximum segment size (minus options used in the SYN). For 285 the active open side, it is recommended to change or replace the 286 connect() call in order to support a user data buffer argument 287 [RFC7413]. For the passive open side, the application needs to 288 enable the reception of Fast Open requests, e.g. via a new 289 TCP_FASTOPEN setsockopt() socket option before listen(). The 290 receiving application must be prepared to accept duplicates of the 291 TFO message, as the first data written to a socket can be 292 delivered more than once to the application on the remote host. 294 Send: this is the primitive that an application uses to give the 295 local TCP transport endpoint a number of bytes that TCP should 296 reliably send to the other side of the connection. The 'urgent' 297 flag, if set, states that the data handed over by this send call 298 is urgent and this urgency should be indicated to the receiving 299 process in case the receiving application has not yet consumed all 300 non-urgent data preceding it. An optional timeout parameter can 301 be provided that updates the connection's timeout (see 'open'). 302 Additionally, optional parameters allow to indicate the preferred 303 outgoing MKT (current_key) and/or the preferred incoming MKT 304 (rnext_key) of a connection (section 7.1 of [RFC5925]). 306 Receive: This primitive allocates a receiving buffer for a provided 307 number of bytes. It returns the number of received bytes provided 308 in the buffer when these bytes have been received and written into 309 the buffer by TCP. The application is informed of urgent data via 310 an 'urgent' flag: if it is on, there is urgent data. If it is 311 off, there is no urgent data or this call to 'receive' has 312 returned all the urgent data. The application is also informed 313 about the current_key and rnext_key information carried in a 314 recently received segment via an optional parameter (section 7.1 315 of [RFC5925]). 317 Close: This primitive closes one side of a connection. It is 318 semantically equivalent to "I have no more data to send" but does 319 not mean "I will not receive any more", as the other side may 320 still have data to send. This call reliably delivers any data 321 that has already been given to TCP (and if that fails, 'close' 322 becomes 'abort'). 324 Abort: This primitive causes all pending 'send' and 'receive' calls 325 to be aborted. A TCP "RESET" message is sent to the TCP endpoint 326 on the other side of the connection [RFC0793]. 328 Close Event: TCP uses this primitive to inform an application that 329 the application on the other side has called the 'close' 330 primitive, so the local application can also issue a 'close' and 331 terminate the connection gracefully. See [RFC0793], Section 3.5. 333 Abort Event: When TCP aborts a connection upon receiving a "RESET" 334 from the peer, it "advises the user and goes to the CLOSED state." 335 See [RFC0793], Section 3.4. 337 User Timeout Event: This event is executed when the user timeout 338 expires (see 'open') (section 3.9 of [RFC0793]). All queues are 339 flushed and the application is informed that the connection had to 340 be aborted due to user timeout. 342 Error_Report event: This event informs the application of "soft 343 errors" that can be safely ignored [RFC5461], including the 344 arrival of an ICMP error message or excessive retransmissions 345 (reaching a threshold below the threshold where the connection is 346 aborted). See section 4.2.4.1 of [RFC1122]. 348 Type-of-Service: Section 4.2.4.2 of the requirements for Internet 349 hosts [RFC1122] states that "the application layer MUST be able to 350 specify the Type-of-Service (TOS) for segments that are sent on a 351 connection". The application should be able to change the TOS 352 during the connection lifetime, and the TOS value should be passed 353 to the IP layer unchanged. Since then the TOS field has been 354 redefined. The Differentiated Services (DiffServ) model [RFC2475] 355 [RFC3260] replaces this field in the IP Header, assigning the six 356 most significant bits to carry the Differentiated Services Code 357 Point (DSCP) field [RFC2474]. 359 Nagle: The Nagle algorithm delays sending data for some time to 360 increase the likelihood of sending a full-sized segment (section 361 4.2.3.4 of [RFC1122]). An application can disable the Nagle 362 algorithm for an individual connection. 364 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 365 one end of a TCP connection to advertise its current user timeout 366 value so that the other end of the TCP connection can adapt its 367 own user timeout accordingly. In addition to the configurable 368 value of the User Timeout (see 'send'), there are three per- 369 connection state variables that an application can adjust to 370 control the operation of the User Timeout Option (UTO): 'adv_uto' 371 is the value of the UTO advertised to the remote TCP peer 372 (default: system-wide default user timeout); 'enabled' (default 373 false) is a boolean-type flag that controls whether the UTO option 374 is enabled for a connection. This applies to both sending and 375 receiving. 'changeable' is a boolean-type flag (default true) that 376 controls whether the user timeout may be changed based on a UTO 377 option received from the other end of the connection. 'changeable' 378 becomes false when an application explicitly sets the user timeout 379 (see 'send'). 381 Set / Get Authentication Parameters: The preferred outgoing MKT 382 (current_key) and/or the preferred incoming MKT (rnext_key) of a 383 connection can be configured. Information about current_key and 384 rnext_key carried in a recently received segment can be retrieved 385 (section 7.1 of [RFC5925]). 387 3.1.1. Excluded Primitives or Parameters 389 The 'open' primitive can be handed optional Precedence or security/ 390 compartment information [RFC0793], but this was not included here 391 because it is mostly irrelevant today [RFC7414]. 393 The 'Status' primitive was not included because the initial TCP 394 specification describes this primitive as "implementation dependent" 395 and states that it "could be excluded without adverse effect" 396 [RFC0793]. Moreover, while a data block containing specific 397 information is described, it is also stated that not all of this 398 information may always be available. While [RFC5925] states that 399 'Status' "SHOULD be augmented to allow the MKTs of a current or 400 pending connection to be read (for confirmation)", the same 401 information is also available via 'Receive', which, following 402 [RFC5925], "MUST be augmented" with that functionality. The 'Send' 403 primitive includes an optional 'push' flag which, if set, requires 404 data to be promptly transmitted to the receiver without delay 405 [RFC0793]; the 'Receive' primitive described in can (under some 406 conditions) yield the status of the 'push' flag. Because "push" 407 functionality is optional to implement for both the 'send' and 408 'receive' primitives [RFC1122], this functionality is not included 409 here. The requirements for Internet hosts [RFC1122] also introduce 410 keep-alives to TCP, but these are optional to implement and hence not 411 considered here. The same document also describes that "some TCP 412 implementations have included a FLUSH call", indicating that this 413 call is also optional to implement. It is therefore not considered 414 here. 416 3.2. Primitives Provided by MPTCP 418 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 419 multiple paths for a single data-stream. It achieves this by 420 creating different so-called TCP subflows for each of the interfaces 421 and scheduling the traffic across these TCP subflows. The service 422 provided by MPTCP is described as follows in [RFC6182]: "Multipath 423 TCP MUST follow the same service model as TCP [RFC0793]: in- order, 424 reliable, and byte-oriented delivery. Furthermore, a Multipath TCP 425 connection SHOULD provide the application with no worse throughput or 426 resilience than it would expect from running a single TCP connection 427 over any one of its available paths." 429 Further, there are some constraints on the API exposed by MPTCP, 430 stated in [RFC6182]: "A multipath-capable equivalent of TCP MUST 431 retain some level of backward compatibility with existing TCP APIs, 432 so that existing applications can use the newer merely by upgrading 433 the operating systems of the end hosts." As such, the primitives 434 provided by MPTCP are equivalent to the ones provided by TCP. 435 Nevertheless, the MPTCP RFCs [RFC6824] and [RFC6897] clarify some 436 parts of TCP's primitives with respect to MPTCP and add some 437 extensions for better control on MPTCP's subflows. Hereafter is a 438 list of the clarifications and extensions the above cited RFCs 439 provide to TCP's primitives. 441 Open: "An application should be able to request to turn on or turn 442 off the usage of MPTCP" [RFC6897]. This functionality can be 443 provided through a socket-option called 'tcp_multipath_enable'. 444 Further, MPTCP must be disabled in case the application is binding 445 to a specific address [RFC6897]. 447 Send/Receive: The sending and receiving of data does not require any 448 changes to the application when MPTCP is being used [RFC6824]. 449 The MPTCP-layer will "take one input data stream from an 450 application, and split it into one or more subflows, with 451 sufficient control information to allow it to be reassembled and 452 delivered reliably and in order to the recipient application." 453 The use of the Urgent Pointer is special in MPTCP [RFC6824], which 454 states: "a TCP subflow MUST NOT use the Urgent Pointer to 455 interrupt an existing mapping." 457 Address and Subflow Management: MPTCP uses different addresses and 458 allows a host to announce these addresses as part of the protocol. 459 The MPTCP API Considerations RFC [RFC6897] says "An application 460 should be able to restrict MPTCP to binding to a given set of 461 addresses" and thus allows applications to limit the set of 462 addresses that are being used by MPTCP. Further, "An application 463 should be able to obtain information on the pairs of addresses 464 used by the MPTCP subflows". 466 3.3. Primitives Provided by SCTP 468 TCP has a number of limitations that SCTP removes (section 1.1 of 469 [RFC4960]). The following three removed limitations directly 470 translate into transport features that are visible to an application 471 using SCTP: 1) it allows for preservation of message delimiters; 2) 472 it does not provide in-order or reliable delivery unless the 473 application wants that; 3) multi-homing is supported. In SCTP, 474 connections are called "associations" and they can be between not 475 only two (as in TCP) but multiple addresses at each endpoint. 477 Section 10 of the SCTP base protocol specification [RFC4960] 478 specifies the interaction with the application (which SCTP calls the 479 "Upper Layer Protocol" (ULP)). It is assumed that the Operating 480 System provides a means for SCTP to asynchronously signal the 481 application; the primitives representing such signals are called 482 'events' in this section. Here, we describe the relevant primitives. 483 In addition to the abstract API described in the section 10 of the 484 SCTP base protocol specification [RFC4960], an extension to the 485 socket API is described in [RFC6458]. This covers the functionality 486 of the base protocol [RFC4960] and some of its extensions [RFC3758], 487 [RFC4895], [RFC5061]. For other protocol extensions [RFC6525], 488 [RFC6951], [RFC7053], [RFC7496], [RFC7829], 489 [I-D.ietf-tsvwg-sctp-ndata], the corresponding extensions of the 490 socket API are specified in these protocol specifications. The 491 functionality exposed to the ULP through all these APIs is considered 492 here. 494 The abstract API contains a 'SetProtocolParameters' primitive that 495 allows to adjust elements of a parameter list [RFC4960]; it is stated 496 that SCTP implementations "may allow ULP to customize some of these 497 protocol parameters", indicating that none of the elements of this 498 parameter list are mandatory to make ULP-configurable. Thus, we only 499 consider the parameters in the abstract API that are also covered in 500 one of the other RFCs listed above, which leads us to exclude the 501 parameters RTO.Alpha, RTO.Beta and HB.Max.Burst. For clarity, we 502 also replace 'SetProtocolParameters' itself with primitives that 503 adjust parameters or groups of parameters that fit together. 505 Initialize: Initialize creates a local SCTP instance that it binds 506 to a set of local addresses (and, if provided, a local port 507 number) [RFC4960]. Initialize needs to be called only once per 508 set of local addresses. A number of per-association 509 initialization parameters can be used when an association is 510 created, but before it is connected (via the primitive 'Associate' 511 below): the maximum number of inbound streams the application is 512 prepared to support, the maximum number of attempts to be made 513 when sending the INIT (the first message of association 514 establishment), and the maximum retransmission timeout (RTO) value 515 to use when attempting an INIT [RFC6458]. At this point, before 516 connecting, an application can also enable UDP encapsulation by 517 configuring the remote UDP encapsulation port number [RFC6951]. 519 Associate: This creates an association (the SCTP equivalent of a 520 connection) that connects the local SCTP instance and a remote 521 SCTP instance. To identify the remote endpoint, it can be given 522 one or multiple (using "connectx") sockets (section 9.9 of 523 [RFC6458]). Most primitives are associated with a specific 524 association, which is assumed to first have been created. 525 Associate can return a list of destination transport addresses so 526 that multiple paths can later be used. One of the returned 527 sockets will be selected by the local endpoint as default primary 528 path for sending SCTP packets to this peer, but this choice can be 529 changed by the application using the list of destination 530 addresses. Associate is also given the number of outgoing streams 531 to request and optionally returns the number of negotiated 532 outgoing streams. An optional parameter of 32 bits, the 533 adaptation layer indication, can be provided [RFC5061]. If 534 authenticated chunks are used, the chunk types required to be sent 535 authenticated by the peer can be provided [RFC4895]. A 536 'SCTP_Cant_Str_Assoc' notification is used to inform the 537 application of a failure to create an association [RFC6458]. An 538 application could use sendto() or sendmsg() to implicitly setup an 539 association, thereby handing over a message that SCTP might send 540 during the association setup phase [RFC6458]. Note that this 541 mechanism is different from TCP's TFO mechanism: the message would 542 arrive only once, after at least one RTT, as it is sent together 543 with the third message exchanged during association setup, the 544 COOKIE-ECHO chunk). 546 Send: This sends a message of a certain length in bytes over an 547 association. A number can be provided to later refer to the 548 correct message when reporting an error, and a stream id is 549 provided to specify the stream to be used inside an association 550 (we consider this as a mandatory parameter here for simplicity: if 551 not provided, the stream id defaults to 0). A condition to 552 abandon the message can be specified (for example limiting the 553 number of retransmissions or the lifetime of the user message). 554 This allows to control the partial reliability extension 555 [RFC3758], [RFC7496]. An optional maximum life time can specify 556 the time after which the message should be discarded rather than 557 sent. A choice (advisory, i.e. not guaranteed) of the preferred 558 path can be made by providing a socket, and the message can be 559 delivered out-of-order if the unordered flag is set. An advisory 560 flag indicates that the peer should not delay the acknowledgement 561 of the user message provided [RFC7053]. Another advisory flag 562 indicates whether the application prefers to avoid bundling user 563 data with other outbound DATA chunks (i.e., in the same packet). 564 A payload protocol-id can be provided to pass a value that 565 indicates the type of payload protocol data to the peer. If 566 authenticated chunks are used, the key identifier for 567 authenticating DATA chunks can be provided [RFC4895]. 569 Receive: Messages are received from an association, and optionally a 570 stream within the association, with their size returned. The 571 application is notified of the availability of data via a 'Data 572 Arrive' notification. If the sender has included a payload 573 protocol-id, this value is also returned. If the received message 574 is only a partial delivery of a whole message, a partial flag will 575 indicate so, in which case the stream id and a stream sequence 576 number are provided to the application. 578 Shutdown: This primitive gracefully closes an association, reliably 579 delivering any data that has already been handed over to SCTP. A 580 parameter lets the application control whether further receive or 581 send operations or both are disabled when the call is issued. A 582 return code informs about success or failure of this procedure. 584 Abort: This ungracefully closes an association, by discarding any 585 locally queued data and informing the peer that the association 586 was aborted. Optionally, an abort reason to be passed to the peer 587 may be provided by the application. A return code informs about 588 success or failure of this procedure. 590 Change Heartbeat / Request Heartbeat: This allows the application to 591 enable/disable heartbeats and optionally specify a heartbeat 592 frequency as well as requesting a single heartbeat to be carried 593 out upon a function call, with a notification about success or 594 failure of transmitting the HEARTBEAT chunk to the destination. 596 Configure Max. Retransmissions of an Association: The parameter 597 Association.Max.Retrans [RFC4960] (called "sasoc_maxrxt" in the 598 SCTP socket API extensions [RFC6458]), allows to configure the 599 number of unsuccessful retransmissions after which an entire 600 association is considered as failed; this should invoke a 601 'Communication Lost' notification. 603 Set Primary: This allows to set a new primary default path for an 604 association by providing a socket. Optionally, a default source 605 address to be used in IP datagrams can be provided. 607 Change Local Address / Set Peer Primary: This allows an endpoint to 608 add/remove local addresses to/from an association. In addition, 609 the peer can be given a hint which address to use as the primary 610 address [RFC5061]. 612 Configure Path Switchover: The abstract API contains a primitive 613 called 'Set Failure Threshold' [RFC4960]. This configures the 614 parameter "Path.Max.Retrans", which determines after how many 615 retransmissions a particular transport address is considered as 616 unreachable. If there are more transport addresses available in 617 an association, reaching this limit will invoke a path switchover. 618 An extension called "SCTP-PF" adds a concept of "Potentially 619 Failed" (PF) paths to this method [RFC7829]. When a path is in PF 620 state, SCTP will not entirely give up sending on that path, but it 621 will preferably send data on other active paths if such paths are 622 available. Entering the PF state is done upon exceeding a 623 configured maximum number of retransmissions. Thus, for all paths 624 where this mechanism is used, there are two configurable error 625 thresholds: one to decide that a path is in PF state, and one to 626 decide that the transport address is unreachable. 628 Set / Get Authentication Parameters: This allows an endpoint to add/ 629 remove key material to/from an association. In addition, the 630 chunk types being authenticated can be queried [RFC4895]. 632 Add / Reset Streams, Reset Association: This allows an endpoint to 633 add streams to an existing association or or to reset them 634 individually. Additionally, the association can be reset 635 [RFC6525]. 637 Status: The 'Status' primitive returns a data block with information 638 about a specified association, containing: association connection 639 state; destination transport address list; destination transport 640 address reachability states; current local and peer receiver 641 window sizes; current local congestion window sizes; number of 642 unacknowledged DATA chunks; number of DATA chunks pending receipt; 643 primary path; most recent SRTT on primary path; RTO on primary 644 path; SRTT and RTO on other destination addresses [RFC4960] and 645 MTU per path [RFC6458]. 647 Enable / Disable Interleaving: This allows to enable or disable the 648 negotiation of user message interleaving support for future 649 associations. For existing associations it is possible to query 650 whether user message interleaving support was negotiated or not on 651 a particular association [I-D.ietf-tsvwg-sctp-ndata]. 653 Set Stream Scheduler: This allows to select a stream scheduler per 654 association, with a choice of: First Come First Serve, Round 655 Robin, Round Robin per Packet, Priority Based, Fair Bandwidth, 656 Weighted Fair Queuing [I-D.ietf-tsvwg-sctp-ndata]. 658 Configure Stream Scheduler: This allows to change a parameter per 659 stream for the schedulers: a priority value for the Priority Based 660 scheduler and a weight for the Weighted Fair Queuing scheduler. 662 Enable / Disable NoDelay: This turns on/off any Nagle-like algorithm 663 for an association [RFC6458]. 665 Configure Send Buffer Size: This controls the amount of data SCTP 666 may have waiting in internal buffers to be sent or retransmitted 667 [RFC6458]. 669 Configure Receive Buffer Size: This sets the receive buffer size in 670 octets, thereby controlling the receiver window for an association 671 [RFC6458]. 673 Configure Message Fragmentation: If a user message causes an SCTP 674 packet to exceed the maximum fragmentation size (which can be 675 provided by the application, and is otherwise the PMTU size), then 676 the message will be fragmented by SCTP. Disabling message 677 fragmentation will produce an error instead of fragmenting the 678 message [RFC6458]. 680 Configure Path MTU Discovery: Path MTU Discovery can be enabled or 681 disabled per peer address of an association (section 8.1.12 of 682 [RFC6458]). When it is enabled, the current Path MTU value can be 683 obtained. When it is disabled, the Path MTU to be used can be 684 controlled by the application. 686 Configure Delayed SACK Timer: The time before sending a SACK can be 687 adjusted; delaying SACKs can be disabled; the number of packets 688 that must be received before a SACK is sent without waiting for 689 the delay timer to expire can be configured [RFC6458]. 691 Set Cookie Life Value: The Cookie life value can be adjusted 692 (section 8.1.2 of [RFC6458]). "Valid.Cookie.Life" is also one of 693 the parameters that is potentially adjustable with 694 'SetProtocolParameters' [RFC4960]. 696 Set Maximum Burst: The maximum burst of packets that can be emitted 697 by a particular association (default 4, and values above 4 are 698 optional to implement) can be adjusted (section 8.1.2 of 699 [RFC6458]). "Max.Burst" is also one of the parameters that is 700 potentially adjustable with 'SetProtocolParameters' [RFC4960]. 702 Configure RTO Calculation: The abstract API contains the following 703 adjustable parameters: RTO.Initial; RTO.Min; RTO.Max; RTO.Alpha; 704 RTO.Beta. Only the initial, minimum and maximum RTO are also 705 described as configurable in the SCTP sockets API extensions 706 [RFC6458]. 708 Set DSCP Value: The DSCP value can be set per peer address of an 709 association (section 8.1.12 of [RFC6458]). 711 Set IPv6 Flow Label: The flow label field can be set per peer 712 address of an association (section 8.1.12 of [RFC6458]). 714 Set Partial Delivery Point: This allows to specify the size of a 715 message where partial delivery will be invoked. Setting this to a 716 lower value will cause partial deliveries to happen more often 717 [RFC6458]. 719 Communication Up Notification: When a lost communication to an 720 endpoint is restored or when SCTP becomes ready to send or receive 721 user messages, this notification informs the application process 722 about the affected association, the type of event that has 723 occurred, the complete set of sockets of the peer, the maximum 724 number of allowed streams and the inbound stream count (the number 725 of streams the peer endpoint has requested). If interleaving is 726 supported by both endpoints, this information is also included in 727 this notification. 729 Restart Notification: When SCTP has detected that the peer has 730 restarted, this notification is passed to the upper layer 731 [RFC6458]. 733 Data Arrive Notification: When a message is ready to be retrieved 734 via the 'Receive' primitive, the application is informed by this 735 notification. 737 Send Failure Notification / Receive Unsent Message / Receive 738 Unacknowledged Message: When a message cannot be delivered via an 739 association, the sender can be informed about it and learn whether 740 the message has just not been acknowledged or (e.g. in case of 741 lifetime expiry) if it has not even been sent. This can also 742 inform the sender that a part of the message has been successfully 743 delivered. 745 Network Status Change Notification: This informs the application 746 about a socket becoming active/inactive [RFC4960] or "Potentially 747 Failed" [RFC7829]. 749 Communication Lost Notification: When SCTP loses communication to an 750 endpoint (e.g. via Heartbeats or excessive retransmission) or 751 detects an abort, this notification informs the application 752 process of the affected association and the type of event (failure 753 OR termination in response to a shutdown or abort request). 755 Shutdown Complete Notification: When SCTP completes the shutdown 756 procedures, this notification is passed to the upper layer, 757 informing it about the affected assocation. 759 Authentication Notification: When SCTP wants to notify the upper 760 layer regarding the key management related to authenticated chunks 761 [RFC4895], this notification is passed to the upper layer. 763 Adaptation Layer Indication Notification: When SCTP completes the 764 association setup and the peer provided an adaptation layer 765 indication, this is passed to the upper layer [RFC5061], 766 [RFC6458]. 768 Stream Reset Notification: When SCTP completes the procedure for 769 resetting streams [RFC6525], this notification is passed to the 770 upper layer, informing it about the result. 772 Assocation Reset Notification: When SCTP completes the association 773 reset procedure [RFC6525], this notification is passed to the 774 upper layer, informing it about the result. 776 Stream Change Notification: When SCTP completes the procedure used 777 to increase the number of streams [RFC6525], this notification is 778 passed to the upper layer, informing it about the result. 780 Sender Dry Notification: When SCTP has no more user data to send or 781 retransmit on a particular association, this notification is 782 passed to the upper layer [RFC6458]. 784 Partial Delivery Aborted Notification: When a receiver has begun to 785 receive parts of a user message but the delivery of this message 786 is then aborted, this notification is passed to the upper layer 787 (section 6.1.7 of [RFC6458]). 789 3.3.1. Excluded Primitives or Parameters 791 The 'Receive' primitive can return certain additional information, 792 but this is optional to implement and therefore not considered. With 793 a 'Communication Lost' notification, some more information may 794 optionally be passed to the application (e.g., identification to 795 retrieve unsent and unacknowledged data). SCTP "can invoke" a 796 'Communication Error' notification and "may send" a 'Restart' 797 notification, making these two notifications optional to implement. 798 The list provided under 'Status' includes "etc", indicating that more 799 information could be provided. The primitive 'Get SRTT Report' 800 returns information that is included in the information that 'Status' 801 provides and is therefore not discussed. The 'Destroy SCTP Instance' 802 API function was excluded: it erases the SCTP instance that was 803 created by 'Initialize', but is not a Primitive as defined in this 804 document because it does not relate to a transport feature. The 805 'Shutdown' event informs an application that the peer has sent a 806 SHUTDOWN, and hence no further data should be sent on this socket 807 (section 6.1 of [RFC6458]). However, if an application would try to 808 send data on the socket, it would get an error message anyway; thus, 809 this event is classified as "just affecting the application 810 programming style, not how the underlying protocol operates" and not 811 included here. 813 3.4. Primitives Provided by UDP and UDP-Lite 815 The set of pass 1 primitives for UDP and UDP-Lite is documented in 816 [FJ16]. 818 3.5. The service of LEDBAT 820 The service of the Low Extra Delay Background Transport (LEDBAT) 821 congestion control mechanism is described as follows: "LEDBAT is 822 designed for use by background bulk-transfer applications to be no 823 more aggressive than standard TCP congestion control (as specified in 824 RFC 5681) and to yield in the presence of competing flows, thus 825 limiting interference with the network performance of competing 826 flows" [RFC6817]. 828 LEDBAT does not have any primitives, as LEDBAT is not a transport 829 protocol. According to its specification [RFC6817], "LEDBAT can be 830 used as part of a transport protocol or as part of an application, as 831 long as the data transmission mechanisms are capable of carrying 832 timestamps and acknowledging data frequently. LEDBAT can be used 833 with TCP, Stream Control Transmission Protocol (SCTP), and Datagram 834 Congestion Control Protocol (DCCP), with appropriate extensions where 835 necessary; and it can be used with proprietary application protocols, 836 such as those built on top of UDP for peer-to- peer (P2P) 837 applications." At the time of writing, the appropriate extensions 838 for TCP, SCTP or DCCP do not exist. 840 A numer of configurable parameters exist in the LEDBAT specification: 841 TARGET, which is the queuing delay target at which LEDBAT tries to 842 operate, must be set to 100ms or less. 'allowed_increase' (should be 843 1, must be greater than 0) limits the speed at which LEDBAT increases 844 its rate. 'gain', which, according to [RFC6817], "MUST be set to 1 or 845 less" to avoid a faster ramp-up than TCP Reno, determines how quickly 846 the sender responds to changes in queueing delay. Implementations 847 may divide 'gain' into two parameters, one for increase and a 848 possibly larger one for decrease. We call these parameters 849 'Gain_Inc' and 'Gain_Dec' here. 'Base_History' is the size of the 850 list of measured base delays, and, according to [RFC6817], "SHOULD be 851 10". This list can be filtered using a 'Filter' function which is 852 not prescribed [RFC6817], yielding a list of size 'Current_Filter'. 853 The initial and minimum congestion windows, 'Init_CWND' and 854 'Min_CWND', should both be 2. 856 Regarding which of these parameters should be under control of an 857 application, the possible range goes from exposing nothing on the one 858 hand, to considering everything that is not prescribed with a "MUST" 859 in the specification as a parameter on the other hand. Function 860 implementations are not provided as a parameter to any of the 861 transport protocols discussed here, and hence we do not regard the 862 'Filter' function as a parameter. However, to avoid unnecessarily 863 limiting future implementations, we consider all other parameters 864 above as tunable parameters that should be exposed. 866 4. Pass 2 868 This pass categorizes the primitives from pass 1 based on whether 869 they relate to a connection or to data transmission. Primitives are 870 presented following the nomenclature 871 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 872 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 873 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 874 considered. The DATA category does not have any SUBCATEGORY. The 875 PROTOCOL name "UDP(-Lite)" is used when primitives are equivalent for 876 UDP and UDP-Lite; the PROTOCOL name "TCP" refers to both TCP and 877 MPTCP. We present "connection" as a general protocol-independent 878 concept and use it to refer to, e.g., TCP connections (identifiable 879 by a unique pair of IP addresses and TCP port numbers), SCTP 880 associations (identifiable by multiple IP address and port number 881 pairs), as well UDP and UDP-Lite connections (identifiable by a 882 unique socket pair). 884 Some minor details are omitted for the sake of generalization -- 885 e.g., SCTP's 'Close' [RFC4960] returns success or failure, and lets 886 the application control whether further receive or send operations or 887 both are disabled [RFC6458]. This is not described in the same way 888 for TCP [RFC0793], but these details play no significant role for the 889 primitives provided by either TCP or SCTP (for the sake of being 890 generic, it could be assumed that both receive and send operations 891 are disabled in both cases). 893 The TCP 'Send' and 'Receive' primitives include usage of an 'urgent' 894 parameter. This parameter controls a mechanism that is required to 895 implement the "synch signal" used by telnet [RFC0854], but [RFC6093] 896 states that "new applications SHOULD NOT employ the TCP urgent 897 mechanism". Because pass 2 is meant as a basis for the creation of 898 future systems, the "urgent" mechanism is excluded. This also 899 concerns the notification 'Urgent Pointer Advance' in the 900 '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: 916 Active creation of a connection from one transport endpoint to one or 917 more transport endpoints. 918 Interfaces to UDP and UDP-Lite allow both connection-oriented and 919 connection-less usage of the API [RFC8085]. 921 o CONNECT.TCP: 923 Pass 1 primitive / event: 'Open' (active) or 'Open' (passive) with 924 socket, followed by 'Send' 925 Parameters: 1 local IP address (optional); 1 destination transport 926 address (for active open; else the socket and the local IP address 927 of the succeeding incoming connection request will be maintained); 928 timeout (optional); options (optional); MKT configuration 929 (optional); user message (optional) 931 Comments: If the local IP address is not provided, a default 932 choice will automatically be made. The timeout can also be a 933 retransmission count. The options are IP options to be used on 934 all segments of the connection. At least the Source Route option 935 is mandatory for TCP to provide. 'MKT configuration' refers to 936 the ability to configure Master Key Tuples (MKTs) for 937 authentication. The user message may be transmitted to the peer 938 application immediately upon reception of the TCP SYN packet. To 939 benefit from the lower latency this provides as part of the 940 experimental TFO mechanism, its length must be at most the TCP's 941 maximum segment size (minus TCP options used in the SYN). The 942 message may also be delivered more than once to the application on 943 the remote host. 945 o CONNECT.SCTP: 947 Pass 1 primitive / event: 'Initialize', followed by 'Enable / 948 Disable Interleaving' (optional), followed by 'Associate' 950 Parameters: list of local SCTP port number / IP address pairs 951 ('Initialize'); one or several sockets (identifying the peer); 952 outbound stream count; maximum allowed inbound stream count; 953 adaptation layer indication (optional); chunk types required to be 954 authenticated (optional); request interleaving on/off; maximum 955 number of INIT attemps (optional); maximum init. RTO for INIT 956 (optional); user message (optional); remote UDP port number 957 (optional) 959 Returns: socket list or failure 961 Comments: 'Initialize' needs to be called only once per list of 962 local SCTP port number / IP address pairs. One socket will 963 automatically be chosen; it can later be changed in MAINTENANCE. 964 The user message may be transmitted to the peer application 965 immediately upon reception of the packet containing the COOKIE- 966 ECHO chunk. To benefit from the lower latency this provides, its 967 length must be limited such that it fits into the packet 968 containing the COOKIE-ECHO chunk. If a remote UDP port number is 969 provided, SCTP packets will be encapsulated in UDP. 971 o CONNECT.MPTCP: 973 This is similar to CONNECT.TCP except for one additional boolean 974 parameter that allows to enable or disable MPTCP for a particular 975 connection or socket (default: enabled). 977 o CONNECT.UDP(-Lite): 979 Pass 1 primitive / event: 'Connect' followed by 'Send'. 981 Parameters: 1 local IP address (default (ANY), or specified); 1 982 destination transport address; 1 local port (default (OS chooses), 983 or specified); 1 destination port (default (OS chooses), or 984 specified). 986 Comments: Associates a transport address creating a UDP(-Lite) 987 socket connection. This can be called again with a new transport 988 address to create a new connection. The CONNECT function allows 989 an application to receive errors from messages sent to a transport 990 address. 992 AVAILABILITY: 994 Preparing to receive incoming connection requests. 996 o LISTEN.TCP: 998 Pass 1 primitive / event: 'Open' (passive) 1000 Parameters: 1 local IP address (optional); 1 socket (optional); 1001 timeout (optional); buffer to receive a user message (optional); 1002 MKT configuration (optional) 1004 Comments: if the socket and/or local IP address is provided, this 1005 waits for incoming connections from only and/or to only the 1006 provided address. Else this waits for incoming connections 1007 without this / these constraint(s). ESTABLISHMENT can later be 1008 performed with 'Send'. If a buffer is provided to receive a user 1009 message, a user message can be received from a TFO-enabled sender 1010 before TCP's connection handshake is completed. This message may 1011 arrive multiple times. 'MKT configuration' refers to the ability 1012 to configure Master Key Tuples (MKTs) for authentication. 1014 o LISTEN.SCTP: 1016 Pass 1 primitive / event: 'Initialize', followed by 'Communication 1017 Up' or 'Restart' notification and possibly 'Adaptation Layer' 1018 notification 1020 Parameters: list of local SCTP port number / IP address pairs 1021 (initialize) 1023 Returns: socket list; outbound stream count; inbound stream count; 1024 adaptation layer indication; chunks required to be authenticated; 1025 interleaving supported on both sides yes/no 1027 Comments: 'Initialize' needs to be called only once per list of 1028 local SCTP port number / IP address pairs. 'Communication Up' can 1029 also follow a 'Communication Lost' notification, indicating that 1030 the lost communication is restored. If the peer has provided an 1031 adaptation layer indication, an 'Adaptation Layer' notification is 1032 issued. 1034 o LISTEN.MPTCP: 1036 This is similar to LISTEN.TCP except for one additional boolean 1037 parameter that allows to enable or disable MPTCP for a particular 1038 connection or socket (default: enabled). 1040 o LISTEN.UDP(-Lite): 1042 Pass 1 primitive / event: 'Receive'. 1044 Parameters: 1 local IP address (default (ANY), or specified); 1 1045 destination transport address; local port (default (OS chooses), 1046 or specified); destination port (default (OS chooses), or 1047 specified). 1049 Comments: The 'Receive' function registers the application to 1050 listen for incoming UDP(-Lite) datagrams at an endpoint. 1052 MAINTENANCE: 1054 Adjustments made to an open connection, or notifications about it. 1055 These are out-of-band messages to the protocol that can be issued at 1056 any time, at least after a connection has been established and before 1057 it has been terminated (with one exception: CHANGE_TIMEOUT.TCP can 1058 only be issued for an open connection when DATA.SEND.TCP is called). 1059 In some cases, these primitives can also be immediately issued during 1060 ESTABLISHMENT or AVAILABILITY, without waiting for the connection to 1061 be opened (e.g. CHANGE_TIMEOUT.TCP can be done using TCP's 'Open' 1062 primitive). For UDP and UDP-Lite, these functions may establish a 1063 setting per connection, but may also be changed per datagram message. 1065 o CHANGE_TIMEOUT.TCP: 1067 Pass 1 primitive / event: 'Open' or 'Send' combined with 1068 unspecified control of per-connection state variables 1070 Parameters: timeout value (optional); adv_uto (optional); boolean 1071 uto_enabled (optional, default false); boolean changeable 1072 (optional, default true) 1074 Comments: when sending data, an application can adjust the 1075 connection's timeout value (time after which the connection will 1076 be aborted if data could not be delivered). If 'uto_enabled' is 1077 true, the 'timeout value' (or, if provided, the value 'adv_uto') 1078 will be advertised for the TCP on the other side of the connection 1079 to adapt its own user timeout accordingly. 'uto_enabled' controls 1080 whether the UTO option is enabled for a connection. This applies 1081 to both sending and receiving. 'changeable' controls whether the 1082 user timeout may be changed based on a UTO option received from 1083 the other end of the connection; it becomes false when 'timeout 1084 value' is used. 1086 o CHANGE_TIMEOUT.SCTP: 1088 Pass 1 primitive / event: 'Change HeartBeat' combined with 1089 'Configure Max. Retransmissions of an Association' 1091 Parameters: 'Change Heartbeat': heartbeat frequency; 'Configure 1092 Max. Retransmissions of an Association': association.max.retrans 1094 Comments: 'Change Heartbeat' can enable / disable heartbeats in 1095 SCTP as well as change their frequency. The parameter 1096 'association.max.retrans' defines after how many unsuccessful 1097 transmissions of any packets (including heartbeats) the 1098 association will be terminated; thus these two primitives / 1099 parameters together can yield a similar behavior for SCTP 1100 associations as CHANGE_TIMEOUT.TCP does for TCP connections. 1102 o DISABLE_NAGLE.TCP: 1104 Pass 1 primitive / event: not specified 1106 Parameters: one boolean value 1108 Comments: the Nagle algorithm delays data transmission to increase 1109 the chance to send a full-sized segment. An application must be 1110 able to disable this algorithm for a connection. 1112 o DISABLE_NAGLE.SCTP: 1114 Pass 1 primitive / event: 'Enable / Disable NoDelay' 1116 Parameters: one boolean value 1118 Comments: Nagle-like algorithms delay data transmission to 1119 increase the chance to send a full-sized packet. 1121 o REQUEST_HEARTBEAT.SCTP: 1123 Pass 1 primitive / event: 'Request HeartBeat' 1125 Parameters: socket 1127 Returns: success or failure 1129 Comments: requests an immediate heartbeat on a path, returning 1130 success or failure. 1132 o ADD_PATH.MPTCP: 1134 Pass 1 primitive / event: not specified 1136 Parameters: local IP address and optionally the local port number 1138 Comments: the application specifies the local IP address and port 1139 number that must be used for a new subflow. 1141 o ADD_PATH.SCTP: 1143 Pass 1 primitive / event: 'Change Local Address / Set Peer 1144 Primary' 1145 Parameters: local IP address 1147 o REM_PATH.MPTCP: 1149 Pass 1 primitive / event: not specified 1151 Parameters: local IP address; local port number; remote IP 1152 address; remote port number 1154 Comments: the application removes the subflow specified by the IP/ 1155 port-pair. The MPTCP implementation must trigger a removal of the 1156 subflow that belongs to this IP/port-pair. 1158 o REM_PATH.SCTP: 1160 Pass 1 primitive / event: 'Change Local Address / Set Peer 1161 Primary' 1163 Parameters: local IP address 1165 o SET_PRIMARY.SCTP: 1167 Pass 1 primitive / event: 'Set Primary' 1169 Parameters: socket 1171 Returns: result of attempting this operation 1173 Comments: update the current primary address to be used, based on 1174 the set of available sockets of the association. 1176 o SET_PEER_PRIMARY.SCTP: 1178 Pass 1 primitive / event: 'Change Local Address / Set Peer 1179 Primary' 1181 Parameters: local IP address 1183 Comments: this is only advisory for the peer. 1185 o CONFIG_SWITCHOVER.SCTP: 1187 Pass 1 primitive / event: 'Configure Path Switchover' 1188 Parameters: primary max retrans (no. of retransmissions after 1189 which a path is considered inactive); PF max retrans (no. of 1190 retransmissions after which a path is considered to be 1191 "Potentially Failed", and others will be preferably used) 1192 (optional) 1194 o STATUS.SCTP: 1196 Pass 1 primitive / event: 'Status', 'Enable / Disable 1197 Interleaving' and 'Network Status Change' notification. 1199 Returns: data block with information about a specified 1200 association, containing: association connection state; destination 1201 transport address list; destination transport address reachability 1202 states; current local and peer receiver window sizes; current 1203 local congestion window sizes; number of unacknowledged DATA 1204 chunks; number of DATA chunks pending receipt; primary path; most 1205 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1206 other destination addresses; MTU per path; interleaving supported 1207 yes/no. 1209 Comments: The 'Network Status Change' notification informs the 1210 application about a socket becoming active/inactive; this only 1211 affects the programming style, as the same information is also 1212 available via 'Status'. 1214 o STATUS.MPTCP: 1216 Pass 1 primitive / event: not specified 1218 Returns: list of pairs of tuples of IP address and TCP port number 1219 of each subflow. The first of the pair is the local IP and port 1220 number, while the second is the remote IP and port number. 1222 o SET_DSCP.TCP: 1224 Pass 1 primitive / event: not specified 1226 Parameters: DSCP value 1228 Comments: this allows an application to change the DSCP value for 1229 outgoing segments. 1231 o SET_DSCP.SCTP: 1233 Pass 1 primitive / event: 'Set DSCP value' 1235 Parameters: DSCP value 1237 Comments: this allows an application to change the DSCP value for 1238 outgoing packets on a path. 1240 o SET_DSCP.UDP(-Lite): 1242 Pass 1 primitive / event: 'Set_DSCP' 1244 Parameter: DSCP value 1246 Comments: This allows an application to change the DSCP value for 1247 outgoing UDP(-Lite) datagrams. [RFC7657] and [RFC8085] provide 1248 current guidance on using this value with UDP. 1250 o ERROR.TCP: 1252 Pass 1 primitive / event: 'Error_Report' 1254 Returns: reason (encoding not specified); subreason (encoding not 1255 specified) 1257 Comments: soft errors that can be ignored without harm by many 1258 applications; an application should be able to disable these 1259 notifications. The reported conditions include at least: ICMP 1260 error message arrived; Excessive Retransmissions. 1262 o ERROR.UDP(-Lite): 1264 Pass 1 primitive / event: 'Error_Report' 1266 Returns: Error report 1268 Comments: This returns soft errors that may be ignored without 1269 harm by many applications; An application must connect to be able 1270 receive these notifications. 1272 o SET_AUTH.TCP: 1274 Pass 1 primitive / event: not specified 1275 Parameters: current_key; rnext_key 1277 Comments: current_key and rnext_key are the preferred outgoing MKT 1278 and the preferred incoming MKT, respectively, for a segment that 1279 is sent on the connection. 1281 o SET_AUTH.SCTP: 1283 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1285 Parameters: key_id; key; hmac_id 1287 o GET_AUTH.TCP: 1289 Pass 1 primitive / event: not specified 1291 Parameters: current_key; rnext_key 1293 Comments: current_key and rnext_key are the preferred outgoing MKT 1294 and the preferred incoming MKT, respectively, that were carried on 1295 a recently received segment. 1297 o GET_AUTH.SCTP: 1299 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1301 Parameters: key_id; chunk_list 1303 o RESET_STREAM.SCTP: 1305 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1307 Parameters: sid; direction 1309 o RESET_STREAM-EVENT.SCTP: 1311 Pass 1 primitive / event: 'Stream Reset' notification 1313 Parameters: information about the result of RESET_STREAM.SCTP. 1315 Comments: This is issued when the procedure for resetting streams 1316 has completed. 1318 o RESET_ASSOC.SCTP: 1320 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1322 Parameters: information related to the extension, defined in 1323 [RFC3260]. 1325 o RESET_ASSOC-EVENT.SCTP: 1327 Pass 1 primitive / event: 'Association Reset' notification 1329 Parameters: information about the result of RESET_ASSOC.SCTP. 1331 Comments: this is issued when the procedure for resetting an 1332 association has completed. 1334 o ADD_STREAM.SCTP: 1336 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1338 Parameters: number if outgoing and incoming streams to be added 1340 o ADD_STREAM-EVENT.SCTP: 1342 Pass 1 primitive / event: 'Stream Change' notification 1344 Parameters: information about the result of ADD_STREAM.SCTP. 1346 Comments: this is issued when the procedure for adding a stream 1347 has completed. 1349 o SET_STREAM_SCHEDULER.SCTP: 1351 Pass 1 primitive / event: 'Set Stream Scheduler' 1353 Parameters: scheduler identifier 1355 Comments: choice of First Come First Serve, Round Robin, Round 1356 Robin per Packet, Priority Based, Fair Bandwidth, Weighted Fair 1357 Queuing. 1359 o CONFIGURE_STREAM_SCHEDULER.SCTP: 1361 Pass 1 primitive / event: 'Configure Stream Scheduler' 1363 Parameters: priority 1365 Comments: the priority value only applies when Priority Based or 1366 Weighted Fair Queuing scheduling is chosen with 1367 SET_STREAM_SCHEDULER.SCTP. The meaning of the parameter differs 1368 between these two schedulers but in both cases it realizes some 1369 form of prioritization regarding how bandwidth is divided among 1370 streams. 1372 o SET_FLOWLABEL.SCTP: 1374 Pass 1 primitive / event: 'Set IPv6 Flow Label' 1376 Parameters: flow label 1378 Comments: this allows an application to change the IPv6 header's 1379 flow label field for outgoing packets on a path. 1381 o AUTHENTICATION_NOTIFICATION-EVENT.SCTP: 1383 Pass 1 primitive / event: 'Authentication' notification 1385 Returns: information regarding key management. 1387 o CONFIG_SEND_BUFFER.SCTP: 1389 Pass 1 primitive / event: 'Configure Send Buffer Size' 1391 Parameters: size value in octets 1393 o CONFIG_RECEIVE_BUFFER.SCTP: 1395 Pass 1 primitive / event: 'Configure Receive Buffer Size' 1397 Parameters: size value in octets 1399 Comments: this controls the receiver window. 1401 o CONFIG_FRAGMENTATION.SCTP: 1403 Pass 1 primitive / event: 'Configure Message Fragmentation' 1405 Parameters: one boolean value (enable/disable); maximum 1406 fragmentation size (optional; default: PMTU) 1408 Comments: if fragmentation is enabled, messages exceeding the 1409 maximum fragmentation size will be fragmented. If fragmentation 1410 is disabled, trying to send a message that exceeds the maximum 1411 fragmentation size will produce an error. 1413 o CONFIG_PMTUD.SCTP: 1415 Pass 1 primitive / event: 'Configure Path MTU Discovery' 1417 Parameters: one boolean value (PMTUD on/off); PMTU value 1418 (optional) 1420 Returns: PMTU value 1422 Comments: this returns a meaningful PMTU value when PMTUD is 1423 enabled (the boolean is true), and the PMTU value can be set if 1424 PMTUD is disabled (the boolean is false) 1426 o CONFIG_DELAYED_SACK.SCTP: 1428 Pass 1 primitive / event: 'Configure Delayed SACK Timer' 1430 Parameters: one boolean value (delayed SACK on/off); timer value 1431 (optional); number of packets to wait for (default 2) 1433 Comments: if delayed SACK is enabled, SCTP will send a SACK upon 1434 either receiving the provided number of packets or when the timer 1435 expires, whatever occurs first. 1437 o CONFIG_RTO.SCTP: 1439 Pass 1 primitive / event: 'Configure RTO Calculation' 1441 Parameters: init (optional); min (optional); max (optional) 1443 Comments: this adjusts the initial, minimum and maximum RTO 1444 values. 1446 o SET_COOKIE_LIFE.SCTP: 1448 Pass 1 primitive / event: 'Set Cookie Life Value' 1450 Parameters: cookie life value 1452 o SET_MAX_BURST.SCTP: 1454 Pass 1 primitive / event: 'Set Maximum Burst' 1456 Parameters: max burst value 1458 Comments: not all implementations allow values above the default 1459 of 4. 1461 o SET_PARTIAL_DELIVERY_POINT.SCTP: 1463 Pass 1 primitive / event: 'Set Partial Delivery Point' 1465 Parameters: partial delivery point (integer) 1467 Comments: this parameter must be smaller or equal to the socket 1468 receive buffer size. 1470 o SET_CHECKSUM_ENABLED.UDP: 1472 Pass 1 primitive / event: 'Checksum_Enabled'. 1474 Parameters: 0 when zero checksum is used at sender, 1 for checksum 1475 at sender (default) 1477 o SET_CHECKSUM_REQUIRED.UDP: 1479 Pass 1 primitive / event: 'Require_Checksum'. 1481 Parameter: 0 to allow zero checksum, 1 when a non-zero checksum is 1482 required (default) at receiver 1484 o SET_CHECKSUM_COVERAGE.UDP-Lite: 1486 Pass 1 primitive / event: 'Set_Checksum_Coverage' 1488 Parameters: coverage length at sender (default maximum coverage) 1490 o SET_MIN_CHECKSUM_COVERAGE.UDP-Lite: 1492 Pass 1 primitive / event: 'Set_Min_Coverage'. 1494 Parameter: coverage length at receiver (default minimum coverage) 1496 o SET_DF.UDP(-Lite): 1498 Pass 1 primitive event: 'Set_DF'. 1500 Parameter: 0 when DF is not set (default) in the IPv4 header, 1 1501 when DF is set 1503 o GET_MMS_S.UDP(-Lite): 1505 Pass 1 primitive event: 'Get_MM_S'. 1507 Comments: this retrieves the maximum transport-message size that 1508 may be sent using a non-fragmented IP packet from the configured 1509 interface. 1511 o GET_MMS_R.UDP(-Lite): 1513 Pass 1 primitive event: 'Get_MMS_R'. 1515 Comments: this retrieves the maximum transport-message size that 1516 may be received from the configured interface. 1518 o SET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1520 Pass 1 primitive / event: 'Set_TTL' and 'Set_IPV6_Unicast_Hops' 1522 Parameters: IPv4 TTL value or IPv6 Hop Count value 1524 Comments: this allows an application to change the IPv4 TTL of 1525 IPv6 Hop count value for outgoing UDP(-Lite) datagrams. 1527 o GET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1529 Pass 1 primitive / event: 'Get_TTL' and 'Get_IPV6_Unicast_Hops' 1531 Returns: IPv4 TTL value or IPv6 Hop Count value 1532 Comments: this allows an application to read the the IPv4 TTL of 1533 IPv6 Hop count value from a received UDP(-Lite) datagram. 1535 o SET_ECN.UDP(-Lite): 1537 Pass 1 primitive / event: 'Set_ECN' 1539 Parameters: ECN value 1541 Comments: this allows a UDP(-Lite) application to set the ECN 1542 codepoint field for outgoing UDP(-Lite) datagrams. Defaults to 1543 sending '00'. 1545 o GET_ECN.UDP(-Lite): 1547 Pass 1 primitive / event: 'Get_ECN' 1549 Parameters: ECN value 1551 Comments: this allows a UDP(-Lite) application to read the ECN 1552 codepoint field from a received UDP(-Lite) datagram. 1554 o SET_IP_OPTIONS.UDP(-Lite): 1556 Pass 1 primitive / event: 'Set_IP_Options' 1558 Parameters: options 1560 Comments: this allows a UDP(-Lite) application to set IP Options 1561 for outgoing UDP(-Lite) datagrams. These options can at least be 1562 the Source Route, Record Route, and Time Stamp option. 1564 o GET_IP_OPTIONS.UDP(-Lite): 1566 Pass 1 primitive / event: 'Get_IP_Options' 1568 Returns: options 1570 Comments: this allows a UDP(-Lite) application to receive any IP 1571 options that are contained in a received UDP(-Lite) datagram. 1573 o CONFIGURE.LEDBAT: 1575 Pass 1 primitive / event: N/A 1577 Parameters: enable (boolean); target; allowed_increase; gain_inc; 1578 gain_dec; base_history; current_filter; init_cwnd; min_cwnd 1579 Comments: 'enable' is a newly invented parameter that enables or 1580 disables the whole LEDBAT service. 1582 TERMINATION: 1584 Gracefully or forcefully closing a connection, or being informed 1585 about this event happening. 1587 o CLOSE.TCP: 1589 Pass 1 primitive / event: 'Close' 1591 Comments: this terminates the sending side of a connection after 1592 reliably delivering all remaining data. 1594 o CLOSE.SCTP: 1596 Pass 1 primitive / event: 'Shutdown' 1598 Comments: this terminates a connection after reliably delivering 1599 all remaining data. 1601 o ABORT.TCP: 1603 Pass 1 primitive / event: 'Abort' 1605 Comments: this terminates a connection without delivering 1606 remaining data and sends an error message to the other side. 1608 o ABORT.SCTP: 1610 Pass 1 primitive / event: 'Abort' 1612 Parameters: abort reason to be given to the peer (optional) 1614 Comments: this terminates a connection without delivering 1615 remaining data and sends an error message to the other side. 1617 o ABORT.UDP(-Lite): 1619 Pass 1 primitive event: 'Close' 1621 Comments: this terminates a connection without delivering 1622 remaining data. No further UDP(-Lite) datagrams are sent/received 1623 for this transport service instance. 1625 o TIMEOUT.TCP: 1627 Pass 1 primitive / event: 'User Timeout' event 1629 Comments: the application is informed that the connection is 1630 aborted. This event is executed on expiration of the timeout set 1631 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 1632 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 1634 o TIMEOUT.SCTP: 1636 Pass 1 primitive / event: 'Communication Lost' event 1638 Comments: the application is informed that the connection is 1639 aborted. this event is executed on expiration of the timeout that 1640 should be enabled by default (see the beginning of section 8.3 in 1641 [RFC4960]) and was possibly adjusted in 1642 CONNECTION.MAINTENANCE.CHANGE_TIMEOOUT.SCTP. 1644 o ABORT-EVENT.TCP: 1646 Pass 1 primitive / event: not specified. 1648 o ABORT-EVENT.SCTP: 1650 Pass 1 primitive / event: 'Communication Lost' event 1652 Returns: abort reason from the peer (if available) 1654 Comments: the application is informed that the other side has 1655 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 1657 o CLOSE-EVENT.TCP: 1659 Pass 1 primitive / event: not specified. 1661 o CLOSE-EVENT.SCTP: 1663 Pass 1 primitive / event: 'Shutdown Complete' event 1665 Comments: the application is informed that 1666 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 1668 4.2. DATA Transfer Related Primitives 1670 All primitives in this section refer to an existing connection, i.e. 1671 a connection that was either established or made available for 1672 receiving data (although this is optional for the primitives of UDP(- 1673 Lite)). In addition to the listed parameters, all sending primitives 1674 contain a reference to a data block and all receiving primitives 1675 contain a reference to available buffer space for the data. Note 1676 that CONNECT.TCP and LISTEN.TCP in the ESTABLISHMENT and AVAILABILITY 1677 category also allow to transfer data (an optional user message) 1678 before the connection is fully established. 1680 o SEND.TCP: 1682 Pass 1 primitive / event: 'Send' 1684 Parameters: timeout (optional); current_key (optional); rnext_key 1685 (optional) 1687 Comments: this gives TCP a data block for reliable transmission to 1688 the TCP on the other side of the connection. The timeout can be 1689 configured with this call (see also 1690 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 'current_key' and 1691 'rnext_key' are authentication parameters that can be configured 1692 with this call (see also CONNECTION.MAINTENANCE.SET_AUTH.TCP). 1694 o SEND.SCTP: 1696 Pass 1 primitive / event: 'Send' 1698 Parameters: stream number; context (optional); socket (optional); 1699 unordered flag (optional); no-bundle flag (optional); payload 1700 protocol-id (optional); pr-policy (optional) pr-value (optional); 1701 sack-immediately flag (optional); key-id (optional) 1703 Comments: this gives SCTP a data block for transmission to the 1704 SCTP on the other side of the connection (SCTP association). The 1705 'stream number' denotes the stream to be used. The 'context' 1706 number can later be used to refer to the correct message when an 1707 error is reported. The 'socket' can be used to state which path 1708 should be preferred, if there are multiple paths available (see 1709 also CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can 1710 be delivered out-of-order if the 'unordered flag' is set. The 1711 'no-bundle flag' can be set to indicate a preference to avoid 1712 bundling. The 'payload protocol-id' is a number that will, if 1713 provided, be handed over to the receiving application. Using pr- 1714 policy and pr-value the level of reliability can be controlled. 1715 The 'sack-immediately' flag can be used to indicate that the peer 1716 should not delay the sending of a SACK corresponding to the 1717 provided user message. If specified, the provided key-id is used 1718 for authenticating the user message. 1720 o SEND.UDP(-Lite): 1722 Pass 1 primitive / event: 'Send' 1724 Parameters: IP Address and Port Number of the destination endpoint 1725 (optional if connected) 1727 Comments: this provides a message for unreliable transmission 1728 using UDP(-Lite) to the specified transport address. IP address 1729 and Port may be omitted for connected UDP(-Lite) sockets. All 1730 CONNECTION.MAINTENANCE.SET_*.UDP(-Lite) primitives apply per 1731 message sent. 1733 o RECEIVE.TCP: 1735 Pass 1 primitive / event: 'Receive'. 1737 Parameters: current_key (optional); rnext_key (optional) 1739 Comments: 'current_key' and 'rnext_key' are authentication 1740 parameters that can be read with this call (see also 1741 CONNECTION.MAINTENANCE.GET_AUTH.TCP). 1743 o RECEIVE.SCTP: 1745 Pass 1 primitive / event: 'Data Arrive' notification, followed by 1746 'Receive' 1748 Parameters: stream number (optional) 1750 Returns: stream sequence number (optional); partial flag 1751 (optional) 1753 Comments: if the 'stream number' is provided, the call to receive 1754 only receives data on one particular stream. If a partial message 1755 arrives, this is indicated by the 'partial flag', and then the 1756 'stream sequence number' must be provided such that an application 1757 can restore the correct order of data blocks that comprise an 1758 entire message. 1760 o RECEIVE.UDP(-Lite): 1762 Pass 1 primitive / event: 'Receive', 1764 Parameters: buffer for received datagram 1766 Comments: all CONNECTION.MAINTENANCE.GET_*.UDP(-Lite) primitives 1767 apply per message received. 1769 o SENDFAILURE-EVENT.SCTP: 1771 Pass 1 primitive / event: 'Send Failure' notification, optionally 1772 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 1773 Message' 1775 Returns: cause code; context; unsent or unacknowledged message 1776 (optional) 1778 Comments: 'cause code' indicates the reason of the failure, and 1779 'context' is the context number if such a number has been provided 1780 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 1781 'Receive Unacknowledged Message', respectively. These primitives 1782 can be used to retrieve the unsent or unacknowledged message (or 1783 part of the message, in case a part was delivered) if desired. 1785 o SEND_FAILURE.UDP(-Lite): 1787 Pass 1 primitive / event: 'Send' 1789 Comments: this may be used to probe for the effective PMTU when 1790 using in combination with the 'MAINTENANCE.SET_DF' primitive. 1792 o SENDER_DRY-EVENT.SCTP: 1794 Pass 1 primitive / event: 'Sender Dry' notification 1795 Comments: this informs the application that the stack has no more 1796 user data to send. 1798 o PARTIAL_DELIVERY_ABORTED-EVENT.SCTP: 1800 Pass 1 primitive / event: 'Partial Delivery Aborted' notification 1802 Comments: this informs the receiver of a partial message that the 1803 further delivery of the message has been aborted. 1805 5. Pass 3 1807 This section presents the superset of all transport features in all 1808 protocols that were discussed in the preceding sections, based on the 1809 list of primitives in pass 2 but also on text in pass 1 to include 1810 transport features that can be configured in one protocol and are 1811 static properties in another (congestion control, for example). 1812 Again, some minor details are omitted for the sake of generalization 1813 -- e.g., TCP may provide various different IP options, but only 1814 source route is mandatory to implement, and this detail is not 1815 visible in the Pass 3 transport feature "Specify IP Options". As 1816 before, "UDP(-Lite)" represents both UDP and UDP-Lite, and TCP refers 1817 to both TCP and MPTCP. 1819 5.1. CONNECTION Related Transport Features 1821 ESTABLISHMENT: 1822 Active creation of a connection from one transport endpoint to one or 1823 more transport endpoints. 1825 o Connect 1826 Protocols: TCP, SCTP, UDP(-Lite) 1828 o Specify which IP Options must always be used 1829 Protocols: TCP, UDP(-Lite) 1831 o Request multiple streams 1832 Protocols: SCTP 1834 o Limit the number of inbound streams 1835 Protocols: SCTP 1837 o Specify number of attempts and/or timeout for the first 1838 establishment message 1839 Protocols: TCP, SCTP 1841 o Obtain multiple sockets 1842 Protocols: SCTP 1844 o Disable MPTCP 1845 Protocols: MPTCP 1847 o Configure authentication 1848 Protocols: TCP, SCTP 1849 Comments: with TCP, this allows to configure Master Key Tuples 1850 (MKTs). In SCTP, this allows to specify which chunk types must 1851 always be authenticated. DATA, ACK etc. are different 'chunks' in 1852 SCTP; one or more chunks may be included in a single packet. 1854 o Indicate an Adaptation Layer (via an adaptation code point) 1855 Protocols: SCTP 1857 o Request to negotiate interleaving of user messages 1858 Protocols: SCTP 1860 o Hand over a message to reliably transfer (possibly multiple times) 1861 before connection establishment 1862 Protocols: TCP 1864 o Hand over a message to reliably transfer during connection 1865 establishment 1866 Protocols: SCTP 1868 o Enable UDP encapsulation with a specified remote UDP port number 1869 Protocols: SCTP 1871 AVAILABILITY: 1872 Preparing to receive incoming connection requests. 1874 o Listen, 1 specified local interface 1875 Protocols: TCP, SCTP, UDP(-Lite) 1877 o Listen, N specified local interfaces 1878 Protocols: SCTP 1880 o Listen, all local interfaces 1881 Protocols: TCP, SCTP, UDP(-Lite) 1883 o Obtain requested number of streams 1884 Protocols: SCTP 1886 o Limit the number of inbound streams 1887 Protocols: SCTP 1889 o Specify which IP Options must always be used 1890 Protocols: TCP, UDP(-Lite) 1892 o Disable MPTCP 1893 Protocols: MPTCP 1895 o Configure authentication 1896 Protocols: TCP, SCTP 1897 Comments: with TCP, this allows to configure Master Key Tuples 1898 (MKTs). In SCTP, this allows to specify which chunk types must 1899 always be authenticated. DATA, ACK etc. are different 'chunks' in 1900 SCTP; one or more chunks may be included in a single packet. 1902 o Indicate an Adaptation Layer (via an adaptation code point) 1903 Protocols: SCTP 1905 MAINTENANCE: 1906 Adjustments made to an open connection, or notifications about it. 1908 o Change timeout for aborting connection (using retransmit limit or 1909 time value) 1910 Protocols: TCP, SCTP 1912 o Suggest timeout to the peer 1913 Protocols: TCP 1915 o Disable Nagle algorithm 1916 Protocols: TCP, SCTP 1918 o Request an immediate heartbeat, returning success/failure 1919 Protocols: SCTP 1921 o Notification of Excessive Retransmissions (early warning below 1922 abortion threshold) 1923 Protocols: TCP 1925 o Add path 1926 Protocols: MPTCP, SCTP 1927 MPTCP Parameters: source-IP; source-Port; destination-IP; 1928 destination-Port 1929 SCTP Parameters: local IP address 1931 o Remove path 1932 Protocols: MPTCP, SCTP 1933 MPTCP Parameters: source-IP; source-Port; destination-IP; 1934 destination-Port 1935 SCTP Parameters: local IP address 1937 o Set primary path 1938 Protocols: SCTP 1940 o Suggest primary path to the peer 1941 Protocols: SCTP 1943 o Configure Path Switchover 1944 Protocols: SCTP 1946 o Obtain status (query or notification) 1947 Protocols: SCTP, MPTCP 1948 SCTP parameters: association connection state; destination 1949 transport address list; destination transport address reachability 1950 states; current local and peer receiver window sizes; current 1951 local congestion window sizes; number of unacknowledged DATA 1952 chunks; number of DATA chunks pending receipt; primary path; most 1953 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1954 other destination addresses; MTU per path; interleaving supported 1955 yes/no 1956 MPTCP parameters: subflow-list (identified by source-IP; source- 1957 Port; destination-IP; destination-Port) 1959 o Specify DSCP field 1960 Protocols: TCP, SCTP, UDP(-Lite) 1962 o Notification of ICMP error message arrival 1963 Protocols: TCP, UDP(-Lite) 1965 o Change authentication parameters 1966 Protocols: TCP, SCTP 1968 o Obtain authentication information 1969 Protocols: TCP, SCTP 1971 o Reset Stream 1972 Protocols: SCTP 1974 o Notification of Stream Reset 1975 Protocols: STCP 1977 o Reset Association 1978 Protocols: SCTP 1980 o Notification of Association Reset 1981 Protocols: STCP 1983 o Add Streams 1984 Protocols: SCTP 1986 o Notification of Added Stream 1987 Protocols: STCP 1989 o Choose a scheduler to operate between streams of an association 1990 Protocols: SCTP 1992 o Configure priority or weight for a scheduler 1993 Protocols: SCTP 1995 o Specify IPv6 flow label field 1996 Protocols: SCTP 1998 o Configure send buffer size 1999 Protocols: SCTP 2001 o Configure receive buffer (and rwnd) size 2002 Protocols: SCTP 2004 o Configure message fragmentation 2005 Protocols: SCTP 2007 o Configure PMTUD 2008 Protocols: SCTP 2010 o Configure delayed SACK timer 2011 Protocols: SCTP 2013 o Set Cookie life value 2014 Protocols: SCTP 2016 o Set maximum burst 2017 Protocols: SCTP 2019 o Configure size where messages are broken up for partial delivery 2020 Protocols: SCTP 2022 o Disable checksum when sending 2023 Protocols: UDP 2025 o Disable checksum requirement when receiving 2026 Protocols: UDP 2028 o Specify checksum coverage used by the sender 2029 Protocols: UDP-Lite 2031 o Specify minimum checksum coverage required by receiver 2032 Protocols: UDP-Lite 2034 o Specify DF field 2035 Protocols: UDP(-Lite) 2037 o Get max. transport-message size that may be sent using a non- 2038 fragmented IP packet from the configured interface 2039 Protocols: UDP(-Lite) 2041 o Get max. transport-message size that may be received from the 2042 configured interface 2043 Protocols: UDP(-Lite) 2045 o Specify TTL/Hop count field 2046 Protocols: UDP(-Lite) 2048 o Obtain TTL/Hop count field 2049 Protocols: UDP(-Lite) 2051 o Specify ECN field 2052 Protocols: UDP(-Lite) 2054 o Obtain ECN field 2055 Protocols: UDP(-Lite) 2057 o Specify IP Options 2058 Protocols: UDP(-Lite) 2060 o Obtain IP Options 2061 Protocols: UDP(-Lite) 2063 o Enable and configure "Low Extra Delay Background Transfer" 2064 Protocols: A protocol implementing the LEDBAT congestion control 2065 mechanism 2067 TERMINATION: 2068 Gracefully or forcefully closing a connection, or being informed 2069 about this event happening. 2071 o Close after reliably delivering all remaining data, causing an 2072 event informing the application on the other side 2073 Protocols: TCP, SCTP 2074 Comments: a TCP endpoint locally only closes the connection for 2075 sending; it may still receive data afterwards. 2077 o Abort without delivering remaining data, causing an event 2078 informing the application on the other side 2079 Protocols: TCP, SCTP 2080 Comments: in SCTP a reason can optionally be given by the 2081 application on the aborting side, which can then be received by 2082 the application on the other side. 2084 o Abort without delivering remaining data, not causing an event 2085 informing the application on the other side 2086 Protocols: UDP(-Lite) 2088 o Timeout event when data could not be delivered for too long 2089 Protocols: TCP, SCTP 2090 Comments: the timeout is configured with CONNECTION.MAINTENANCE 2091 "Change timeout for aborting connection (using retransmit limit or 2092 time value)". 2094 5.2. DATA Transfer Related Transport Features 2096 All transport features in this section refer to an existing 2097 connection, i.e. a connection that was either established or made 2098 available for receiving data. Note that TCP allows to transfer data 2099 (a single optional user message, possibly arriving multiple times) 2100 before the connection is fully established. Reliable data transfer 2101 entails delay -- e.g. for the sender to wait until it can transmit 2102 data, or due to retransmission in case of packet loss. 2104 5.2.1. Sending Data 2106 All transport features in this section are provided by DATA.SEND from 2107 pass 2. DATA.SEND is given a data block from the application, which 2108 we here call a "message" if the beginning and end of the data block 2109 can be identified at the receiver, and "data" otherwise. 2111 o Reliably transfer data, with congestion control 2112 Protocols: TCP 2114 o Reliably transfer a message, with congestion control 2115 Protocols: SCTP 2117 o Unreliably transfer a message, with congestion control 2118 Protocols: SCTP 2120 o Unreliably transfer a message, without congestion control 2121 Protocols: UDP(-Lite) 2123 o Configurable Message Reliability 2124 Protocols: SCTP 2126 o Choice of stream 2127 Protocols: SCTP 2129 o Choice of path (destination address) 2130 Protocols: SCTP 2132 o Ordered message delivery (potentially slower than unordered) 2133 Protocols: SCTP 2135 o Unordered message delivery (potentially faster than ordered) 2136 Protocols: SCTP, UDP(-Lite) 2138 o Request not to bundle messages 2139 Protocols: SCTP 2141 o Specifying a "payload protocol-id" (handed over as such by the 2142 receiver) 2143 Protocols: SCTP 2145 o Specifying a key id to be used to authenticate a message 2146 Protocols: SCTP 2148 o Request not to delay the acknowledgement (SACK) of a message 2149 Protocols: SCTP 2151 5.2.2. Receiving Data 2153 All transport features in this section are provided by DATA.RECEIVE 2154 from pass 2. DATA.RECEIVE fills a buffer provided by the 2155 application, with what we here call a "message" if the beginning and 2156 end of the data block can be identified at the receiver, and "data" 2157 otherwise. 2159 o Receive data (with no message delimiting) 2160 Protocols: TCP 2162 o Receive a message 2163 Protocols: SCTP, UDP(-Lite) 2165 o Choice of stream to receive from 2166 Protocols: SCTP 2168 o Information about partial message arrival 2169 Protocols: SCTP 2170 Comments: in SCTP, partial messages are combined with a stream 2171 sequence number so that the application can restore the correct 2172 order of data blocks an entire message consists of. 2174 5.2.3. Errors 2176 This section describes sending failures that are associated with a 2177 specific call to DATA.SEND from pass 2. 2179 o Notification of an unsent (part of a) message 2180 Protocols: SCTP, UDP(-Lite) 2182 o Notification of an unacknowledged (part of a) message 2183 Protocols: SCTP 2185 o Notification that the stack has no more user data to send 2186 Protocols: SCTP 2188 o Notification to a receiver that a partial message delivery has 2189 been aborted 2190 Protocols: SCTP 2192 6. Acknowledgements 2194 The authors would like to thank (in alphabetical order) Bob Briscoe, 2195 Spencer Dawkins, Aaron Falk, David Hayes, Karen Nielsen, Tommy Pauly, 2196 Joe Touch and Brian Trammell for providing valuable feedback on this 2197 document. We especially thank Christoph Paasch for providing input 2198 related to Multipath TCP, and Gorry Fairhurst and Tom Jones for 2199 providing input related to UDP(-Lite). This work has received 2200 funding from the European Union's Horizon 2020 research and 2201 innovation programme under grant agreement No. 644334 (NEAT). 2203 7. IANA Considerations 2205 This memo includes no request to IANA. 2207 8. Security Considerations 2209 Authentication, confidentiality protection, and integrity protection 2210 are identified as transport features [RFC8095]. These transport 2211 features are generally provided by a protocol or layer on top of the 2212 transport protocol; none of the transport protocols considered in 2213 this document provides these transport features on its own. 2214 Therefore, these transport features are not considered in this 2215 document, with the exception of native authentication capabilities of 2216 TCP and SCTP for which the security considerations in [RFC5925] and 2217 [RFC4895] apply. 2219 Security considerations for the use of UDP and UDP-Lite are provided 2220 in the referenced RFCs. Security guidance for application usage is 2221 provided in the UDP-Guidelines [RFC8085]. 2223 9. References 2225 9.1. Normative References 2227 [FJ16] Fairhurst, G. and T. Jones, "Features of the User Datagram 2228 Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport 2229 Protocols", draft-ietf-taps-transports-usage-udp-04 (work 2230 in progress), July 2017. 2232 [I-D.ietf-tsvwg-sctp-ndata] 2233 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2234 "Stream Schedulers and User Message Interleaving for the 2235 Stream Control Transmission Protocol", 2236 draft-ietf-tsvwg-sctp-ndata-08 (work in progress), 2237 October 2016. 2239 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2240 RFC 793, DOI 10.17487/RFC0793, September 1981, 2241 . 2243 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2244 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 2245 RFC1122, October 1989, 2246 . 2248 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 2249 Conrad, "Stream Control Transmission Protocol (SCTP) 2250 Partial Reliability Extension", RFC 3758, DOI 10.17487/ 2251 RFC3758, May 2004, 2252 . 2254 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 2255 "Authenticated Chunks for the Stream Control Transmission 2256 Protocol (SCTP)", RFC 4895, DOI 10.17487/RFC4895, 2257 August 2007, . 2259 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2260 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2261 . 2263 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 2264 Kozuka, "Stream Control Transmission Protocol (SCTP) 2265 Dynamic Address Reconfiguration", RFC 5061, DOI 10.17487/ 2266 RFC5061, September 2007, 2267 . 2269 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 2270 RFC 5482, DOI 10.17487/RFC5482, March 2009, 2271 . 2273 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2274 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2275 June 2010, . 2277 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 2278 Iyengar, "Architectural Guidelines for Multipath TCP 2279 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 2280 . 2282 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 2283 Yasevich, "Sockets API Extensions for the Stream Control 2284 Transmission Protocol (SCTP)", RFC 6458, DOI 10.17487/ 2285 RFC6458, December 2011, 2286 . 2288 [RFC6525] Stewart, R., Tuexen, M., and P. Lei, "Stream Control 2289 Transmission Protocol (SCTP) Stream Reconfiguration", 2290 RFC 6525, DOI 10.17487/RFC6525, February 2012, 2291 . 2293 [RFC6817] Shalunov, S., Hazel, G., Iyengar, J., and M. Kuehlewind, 2294 "Low Extra Delay Background Transport (LEDBAT)", RFC 6817, 2295 DOI 10.17487/RFC6817, December 2012, 2296 . 2298 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 2299 "TCP Extensions for Multipath Operation with Multiple 2300 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 2301 . 2303 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 2304 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 2305 March 2013, . 2307 [RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream 2308 Control Transmission Protocol (SCTP) Packets for End-Host 2309 to End-Host Communication", RFC 6951, DOI 10.17487/ 2310 RFC6951, May 2013, 2311 . 2313 [RFC7053] Tuexen, M., Ruengeler, I., and R. Stewart, "SACK- 2314 IMMEDIATELY Extension for the Stream Control Transmission 2315 Protocol", RFC 7053, DOI 10.17487/RFC7053, November 2013, 2316 . 2318 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2319 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2320 . 2322 [RFC7496] Tuexen, M., Seggelmann, R., Stewart, R., and S. Loreto, 2323 "Additional Policies for the Partially Reliable Stream 2324 Control Transmission Protocol Extension", RFC 7496, 2325 DOI 10.17487/RFC7496, April 2015, 2326 . 2328 [RFC7829] Nishida, Y., Natarajan, P., Caro, A., Amer, P., and K. 2329 Nielsen, "SCTP-PF: A Quick Failover Algorithm for the 2330 Stream Control Transmission Protocol", RFC 7829, 2331 DOI 10.17487/RFC7829, April 2016, 2332 . 2334 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2335 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2336 March 2017, . 2338 9.2. Informative References 2340 [I-D.draft-gjessing-taps-minset] 2341 Gjessing, S. and M. Welzl, "A Minimal Set of Transport 2342 Services for TAPS Systems", draft-gjessing-taps-minset-05 2343 (work in progress), June 2017. 2345 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 2346 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, 2347 May 1983, . 2349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2350 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2351 RFC2119, March 1997, 2352 . 2354 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2355 "Definition of the Differentiated Services Field (DS 2356 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2357 DOI 10.17487/RFC2474, December 1998, 2358 . 2360 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., 2361 and W. Weiss, "An Architecture for Differentiated 2362 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 2363 . 2365 [RFC3260] Grossman, D., "New Terminology and Clarifications for 2366 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 2367 . 2369 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 2370 DOI 10.17487/RFC5461, February 2009, 2371 . 2373 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 2374 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 2375 January 2011, . 2377 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 2378 Zimmermann, "A Roadmap for Transmission Control Protocol 2379 (TCP) Specification Documents", RFC 7414, DOI 10.17487/ 2380 RFC7414, February 2015, 2381 . 2383 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2384 (Diffserv) and Real-Time Communication", RFC 7657, 2385 DOI 10.17487/RFC7657, November 2015, 2386 . 2388 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2389 Ed., "Services Provided by IETF Transport Protocols and 2390 Congestion Control Mechanisms", RFC 8095, DOI 10.17487/ 2391 RFC8095, March 2017, 2392 . 2394 Appendix A. Overview of RFCs used as input for pass 1 2395 TCP: [RFC0793], [RFC1122], [RFC5482], [RFC5925], [RFC7413] 2396 MPTCP: [RFC6182], [RFC6824], [RFC6897] 2397 SCTP: RFCs without a socket API specification: [RFC3758], [RFC4895], 2398 [RFC4960], [RFC5061]. 2399 RFCs that include a socket API specification: [RFC6458], 2400 [RFC6525], [RFC6951], [RFC7053], [RFC7496] [RFC7829]. 2401 UDP(-Lite): See [FJ16] 2402 LEDBAT: [RFC6817]. 2404 Appendix B. How this document was developed 2406 This section gives an overview of the method that was used to develop 2407 this document. It was given to contributors for guidance, and it can 2408 be helpful for future updates or extensions. 2410 This document is only concerned with transport features that are 2411 explicitly exposed to applications via primitives. It also strictly 2412 follows RFC text: if a transport feature is truly relevant for an 2413 application, the RFCs should say so, and they should describe how to 2414 use and configure it. Thus, the approach followed for developing 2415 this document was to identify the right RFCs, then analyze and 2416 process their text. 2418 Primitives that "MAY" be implemented by a transport protocol were 2419 excluded. To be included, the minimum requirement level for a 2420 primitive to be implemented by a protocol was "SHOULD". Where 2421 [RFC2119]-style requirements levels are not used, primitives were 2422 excluded when they are described in conjunction with statements like, 2423 e.g.: "some implementations also provide" or "an implementation may 2424 also". Excluded primitives or parameters were briefly described in a 2425 dedicated subsection. 2427 Pass 1: This began by identifying text that talks about primitives. 2428 An API specification, abstract or not, obviously describes primitives 2429 -- but we are not *only* interested in API specifications. The text 2430 describing the 'send' primitive in the API specified in [RFC0793], 2431 for instance, does not say that data transfer is reliable. TCP's 2432 reliability is clear, however, from this text in Section 1 of 2433 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 2434 use as a highly reliable host-to-host protocol between hosts in 2435 packet-switched computer communication networks, and in 2436 interconnected systems of such networks." 2438 Some text for pass 1 subsections was developed copy+pasting all the 2439 relevant text parts from the relevant RFCs, then adjusting 2440 terminology to match the terminology in Section 1 and adjusting 2441 (shortening!) phrasing to match the general style of the document. 2443 An effort was made to formulate everything as a primitive description 2444 such that the primitive descriptions became as complete as possible 2445 (e.g., the "SEND.TCP" primitive in pass 2 is explicitly described as 2446 reliably transferring data); text that is relevant for the primitives 2447 presented in this pass but still does not fit directly under any 2448 primitive was used in a subsection's introduction. 2450 Pass 2: The main goal of this pass is unification of primitives. As 2451 input, only text from pass 1 was used (no exterior sources). The 2452 list in pass 2 is not arranged by protocol ("first protocol X, here 2453 are all the primitives; then protocol Y, here are all the primitives, 2454 ..") but by primitive ("primitive A, implemented this way in protocol 2455 X, this way in protocol Y, ..."). It was a goal to obtain as many 2456 similar pass 2 primitives as possible. For instance, this was 2457 sometimes achieved by not always maintaining a 1:1 mapping between 2458 pass 1 and pass 2 primitives, renaming primitives etc. For every new 2459 primitive, the already existing primitives were considered to try to 2460 make them as coherent as possible. 2462 For each primitive, the following style was used: 2464 o PRIMITIVENAME.PROTOCOL: 2465 Pass 1 primitive / event: 2466 Parameters: 2467 Returns: 2468 Comments: 2470 The entries "Parameters", "Returns" and "Comments" were skipped when 2471 a primitive had no parameters, no described return value or no 2472 comments seemed necessary, respectively. Optional parameters are 2473 followed by "(optional)". When a default value is known, this was 2474 also provided. 2476 Pass 3: the main point of this pass is to identify transport features 2477 that are the result of static properties of protocols, for which all 2478 protocols have to be listed together; this is then the final list of 2479 all available transport features. This list was primarily based on 2480 text from pass 2, with additional input from pass 1 (but no external 2481 sources). 2483 Appendix C. Revision information 2485 XXX RFC-Ed please remove this section prior to publication. 2487 -00 (from draft-welzl-taps-transports): this now covers TCP based on 2488 all TCP RFCs (this means: if you know of something in any TCP RFC 2489 that you think should be addressed, please speak up!) as well as 2490 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 2491 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 2492 in line with [RFC8095]. Addressed comments by Karen Nielsen and 2493 Gorry Fairhurst; various other fixes. Appendices (TCP overview and 2494 how-to-contribute) added. 2496 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 2497 [RFC6897]. 2499 -02: included UDP, UDP-Lite, and all extensions of SCTPs. This 2500 includes fixing the [RFC6458] omission from -00. 2502 -03: wrote security considerations. The "how to contribute" section 2503 was updated to reflect how the document *was* created, not how it 2504 *should be* created; it also no longer wrongly says that Experimental 2505 RFCs are excluded. Included LEDBAT. Changed abstract and intro to 2506 reflect which protocols/mechanisms are covered (TCP, MPTCP, SCTP, 2507 UDP, UDP-Lite, LEDBAT) instead of talking about "transport 2508 protocols". Interleaving and stream scheduling added 2509 (draft-ietf-tsvwg-sctp-ndata). TFO added. "Set protocol parameters" 2510 in SCTP replaced with per-parameter (or parameter group) primitives. 2511 More primitives added, mostly previously overlooked ones from 2512 [RFC6458]. Updated terminology (s/transport service feature/ 2513 transport feature) in line with an update of [RFC8095]. Made 2514 sequence of transport features / primitives more logical. Combined 2515 MPTCP's add/rem subflow with SCTP's add/remove local address. 2517 -04: changed UDP's close into an ABORT (to better fit with the 2518 primitives of TCP and SCTP), and incorporated the corresponding 2519 transport feature in step 3 (this addresses a comment from Gorry 2520 Fairhurst). Added TCP Authentication (RFC 5925, section 7.1). 2521 Changed TFO from looking like a primitive in pass 1 to be a part of 2522 'open'. Changed description of SCTP authentication in pass 3 to 2523 encompass both TCP and SCTP. Added citations of [RFC8095] and minset 2524 [I-D.draft-gjessing-taps-minset] to the intro, to give the context of 2525 this document. 2527 -05: minor fix to TCP authentication (comment from Joe Touch), 2528 several fixes from Gorry Fairhurst and Tom Jones. Language fixes; 2529 updated to align with latest taps-transport-usage-udp ID. 2531 -06: addressed WGLC comments from Aaron Falk and Tommy Pauly. 2533 -07: addressed AD review comments from Spencer Dawkins. 2535 -08: removed "delivery number" which was based on an error in RFC 2536 4960: https://tools.ietf.org/html/ 2537 draft-ietf-tsvwg-rfc4960-errata-02#section-3.34. 2539 -09: for consistency with the draft-ietf-taps-minset-00, adjusted the 2540 following transport features in "pass 3": "Choice between unordered 2541 (potentially faster) or ordered delivery of messages" divided into 2542 two transport features (one for unordered, one for ordered); the word 2543 "reliably" was added to the transport features "Hand over a message 2544 to reliably transfer (possibly multiple times) before connection 2545 establishment" and "Hand over a message to reliably transfer during 2546 connection establishment". Fixed RFC2119-style language into 2547 explicit citations (comment by Eric Rescorla and others). Addressed 2548 editorial comments by Mirja Kuehlewind, Ben Campbell, Benoit Claise 2549 and the Gen-ART reviewer Roni Even, except for moving terminology 2550 section after the intro because the terminology is already used in 2551 the intro text. 2553 Authors' Addresses 2555 Michael Welzl 2556 University of Oslo 2557 PO Box 1080 Blindern 2558 Oslo, N-0316 2559 Norway 2561 Email: michawe@ifi.uio.no 2563 Michael Tuexen 2564 Muenster University of Applied Sciences 2565 Stegerwaldstrasse 39 2566 Steinfurt 48565 2567 Germany 2569 Email: tuexen@fh-muenster.de 2571 Naeem Khademi 2572 University of Oslo 2573 PO Box 1080 Blindern 2574 Oslo, N-0316 2575 Norway 2577 Email: naeemk@ifi.uio.no