idnits 2.17.1 draft-ietf-taps-transports-usage-05.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 13 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 (May 24, 2017) is 2529 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 880, but not defined == Unused Reference: 'RFC2119' is defined on line 2145, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-taps-transports-usage-udp-02 == 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) == Outdated reference: A later version (-05) exists of draft-gjessing-taps-minset-04 -- Obsolete informational reference (is this intentional?): RFC 6093 (Obsoleted by RFC 9293) Summary: 4 errors (**), 0 flaws (~~), 9 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: November 25, 2017 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 May 24, 2017 10 On the Usage of Transport Features Provided by IETF Transport Protocols 11 draft-ietf-taps-transports-usage-05 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. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on November 25, 2017. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . 5 62 3.1.1. Excluded Primitives or Parameters . . . . . . . . . . 9 63 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . 9 64 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 10 65 3.3.1. Excluded Primitives or Parameters . . . . . . . . . . 18 66 3.4. Primitives Provided by UDP and UDP-Lite . . . . . . . . . 18 67 3.5. The service of LEDBAT . . . . . . . . . . . . . . . . . . 19 68 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 69 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 21 70 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . 36 71 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 72 5.1. CONNECTION Related Transport Features . . . . . . . . . . 39 73 5.2. DATA Transfer Related Transport Features . . . . . . . . 47 74 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . 48 75 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . 49 76 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . 50 77 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 50 78 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 51 80 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 81 9.1. Normative References . . . . . . . . . . . . . . . . . . 51 82 9.2. Informative References . . . . . . . . . . . . . . . . . 54 83 Appendix A. Overview of RFCs used as input for pass 1 . . . . . 55 84 Appendix B. How this document was developed . . . . . . . . . . 55 85 Appendix C. Revision information . . . . . . . . . . . . . . . . 57 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 88 1. Terminology 90 Transport Feature: a specific end-to-end feature that the transport 91 layer provides to an application. Examples include 92 confidentiality, reliable delivery, ordered delivery, message- 93 versus-stream orientation, etc. 94 Transport Service: a set of Transport Features, without an 95 association to any given framing protocol, which provides a 96 complete service to an application. 98 Transport Protocol: an implementation that provides one or more 99 different transport services using a specific framing and header 100 format on 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 document presents, in the form of primitives, events and 128 transport features, defined interactions between applications and the 129 following unicast transport protocols: Transmission Control Protocol 130 (TCP), MultiPath TCP (MPTCP), Stream Control Transmission Protocol 131 (SCTP), User Datagram Protocol (UDP), Lightweight User Datagram 132 Protocol (UDP-Lite). It also defines a primitive to enable/disable 133 and configure the Low Extra Delay Background Transport (LEDBAT) 134 unicast congestion control mechanism. Transport protocols provide 135 communication between processes that operate on network endpoints, 136 which means that they allow for multiplexing of communication between 137 the same IP addresses, and normally this multiplexing is achieved 138 using port numbers. Port multiplexing is therefore assumed to be 139 always provided and not discussed in this document. 141 The list of primitives, events and transport features in this 142 document is strictly based on the parts of protocol specifications 143 that describe what the protocol provides to an application using it 144 and how the application interacts with it. Together with an overview 145 of the services provided by IETF transport protocols and congestion 146 control mechanisms [RFC8095] and an analysis of UDP and UDP-Lite 147 [FJ16], it provides the basis for the minimal set of transport 148 services that end systems should support 149 [I-D.draft-gjessing-taps-minset]. 151 Parts of a protocol that are explicitly stated as optional to 152 implement are not covered. Interactions between the application and 153 a transport protocol that are not directly related to the operation 154 of the protocol are also not covered. For example, there are various 155 ways for an application to use socket options to indicate its 156 interest in receiving certain notifications [RFC6458]. However, for 157 the purpose of identifying primitives, events and transport features, 158 the ability to enable or disable the reception of notifications is 159 irrelevant. Similarly, "one-to-many style sockets" [RFC6458] just 160 affect the application programming style, not how the underlying 161 protocol operates, and they are therefore not discussed here. The 162 same is true for the ability to obtain the unchanged value of a 163 parameter that an application has previously set (e.g.,via "get" in 164 get/set operations [RFC6458]). 166 The document presents a three-pass process to arrive at a list of 167 transport features. In the first pass, the relevant RFC text is 168 discussed per protocol. In the second pass, this discussion is used 169 to derive a list of primitives and events that are uniformly 170 categorized across protocols. Here, an attempt is made to present or 171 -- where text describing primitives or events does not yet exist -- 172 construct primitives or events in a slightly generalized form to 173 highlight similarities. This is, for example, achieved by renaming 174 primitives or events of protocols or by avoiding a strict 1:1-mapping 175 between the primitives or events in the protocol specification and 176 primitives or events in the list. Finally, the third pass presents 177 transport features based on pass 2, identifying which protocols 178 implement them. 180 In the list resulting from the second pass, some transport features 181 are missing because they are implicit in some protocols, and they 182 only become explicit when we consider the superset of all transport 183 features offered by all protocols. For example, TCP always carries 184 out congestion control; we have to consider it together with a 185 protocol like UDP (which does not have congestion control) before we 186 can consider congestion control as a transport feature. The complete 187 list of transport features across all protocols is therefore only 188 available after pass 3. 190 Some protocols are connection-oriented. Connection-oriented 191 protocols often use an initial call to a specific primitive to open a 192 connection before communication can progress, and require 193 communication to be explicitly terminated by issuing another call to 194 a primitive (usually called "close"). A "connection" is the common 195 state that some transport primitives refer to, e.g., to adjust 196 general configuration settings. Connection establishment, 197 maintenance and termination are therefore used to categorize 198 transport primitives of connection-oriented transport protocols in 199 pass 2 and pass 3. For this purpose, UDP is assumed to be used with 200 "connected" sockets, i.e. sockets that are bound to a specific pair 201 of addresses and ports [FJ16]. 203 3. Pass 1 205 This first iteration summarizes the relevant text parts of the RFCs 206 describing the protocols, focusing on what each transport protocol 207 provides to the application and how it is used (abstract API 208 descriptions, where they are available). 210 3.1. Primitives Provided by TCP 212 The initial TCP specification [RFC0793] states: "The Transmission 213 Control Protocol (TCP) is intended for use as a highly reliable host- 214 to-host protocol between hosts in packet-switched computer 215 communication networks, and in interconnected systems of such 216 networks". Section 3.8 in this specification [RFC0793] further 217 specifies the interaction with the application by listing several 218 transport primitives. It is also assumed that an Operating System 219 provides a means for TCP to asynchronously signal the application; 220 the primitives representing such signals are called 'events' in this 221 section. This section describes the relevant primitives. 223 open: this is either active or passive, to initiate a connection or 224 listen for incoming connections. All other primitives are 225 associated with a specific connection, which is assumed to first 226 have been opened. An active open call contains a socket. A 227 passive open call with a socket waits for a particular connection; 228 alternatively, a passive open call can leave the socket 229 unspecified to accept any incoming connection. A fully specified 230 passive call can later be made active by calling 'send'. 231 Optionally, a timeout can be specified, after which TCP will abort 232 the connection if data has not been successfully delivered to the 233 destination (else a default timeout value is used). A procedure 234 for aborting the connection is used to avoid excessive 235 retransmissions, and an application is able to control the 236 threshold used to determine the condition for aborting; this 237 threshold may be measured in time units or as a count of 238 retransmission [RFC1122]. This indicates that the timeout could 239 also be specified as a count of retransmission. 241 Also optional, for multihomed hosts, the local IP address can be 242 provided [RFC1122]. If it is not provided, a default choice will 243 be made in case of active open calls. A passive open call will 244 await incoming connection requests to all local addresses and then 245 maintain usage of the local IP address where the incoming 246 connection request has arrived. Finally, the 'options' parameter 247 allows the application to specify IP options such as source route, 248 record route, or timestamp [RFC1122]. It is not stated on which 249 segments of a connection these options should be applied, but 250 probably all segments, as this is also stated in a specification 251 given for the usage of source route (section 4.2.3.8 of 252 [RFC1122]). Source route is the only non-optional IP option in 253 this parameter, allowing an application to specify a source route 254 when it actively opens a TCP connection. 256 Master Key Tuples (MKTs) for authentication can optionally be 257 configured when calling open (section 7.1 of [RFC5925]). When 258 authentication is in use, complete TCP segments are authenticated, 259 including the TCP IPv4 pseudoheader, TCP header, and TCP data. 261 TCP Fast Open (TFO) [RFC7413] allows to immediately hand over a 262 message from the active open to the passive open side of a TCP 263 connection together with the first message establishment packet 264 (the SYN). This can be useful for applications that are sensitive 265 to TCP's connection setup delay. TCP implementations MUST NOT use 266 TFO by default, but only use TFO if requested explicitly by the 267 application on a per-service-port basis. more than TCP's maximum 268 segment size (minus options used in the SYN). For the active open 269 side, it is recommended to change or replace the connect() call in 270 order to support a user data buffer argument [RFC7413]. For the 271 passive open side, the application needs to enable the reception 272 of Fast Open requests, e.g. via a new TCP_FASTOPEN setsockopt() 273 socket option before listen(). The receiving application must be 274 prepared to accept duplicates of the TFO message, as the first 275 data written to a socket can be delivered more than once to the 276 application on the remote host. 278 send: this is the primitive that an application uses to give the 279 local TCP transport endpoint a number of bytes that TCP should 280 reliably send to the other side of the connection. The URGENT 281 flag, if set, states that the data handed over by this send call 282 is urgent and this urgency should be indicated to the receiving 283 process in case the receiving application has not yet consumed all 284 non-urgent data preceding it. An optional timeout parameter can 285 be provided that updates the connection's timeout (see 'open'). 286 Additionally, optional parameters allow to indicate the preferred 287 outgoing MKT (current_key) and/or the preferred incoming MKT 288 (rnext_key) of a connection (section 7.1 of [RFC5925]). 290 receive: This primitive allocates a receiving buffer for a provided 291 number of bytes. It returns the number of received bytes provided 292 in the buffer when these bytes have been received and written into 293 the buffer by TCP. The application is informed of urgent data via 294 an URGENT flag: if it is on, there is urgent data. If it is off, 295 there is no urgent data or this call to 'receive' has returned all 296 the urgent data. The application is also informed about the 297 current_key and rnext_key information carried in a recently 298 received segment via an optional parameter (section 7.1 of 299 [RFC5925]). 301 close: This primitive closes one side of a connection. It is 302 semantically equivalent to "I have no more data to send" but does 303 not mean "I will not receive any more", as the other side may 304 still have data to send. This call reliably delivers any data 305 that has already been given to TCP (and if that fails, 'close' 306 becomes 'abort'). 308 abort: This primitive causes all pending 'send' and 'receive' calls 309 to be aborted. A TCP RESET message is sent to the TCP endpoint on 310 the other side of the connection [RFC0793]. 312 close event: TCP uses this primitive to inform an application that 313 the application on the other side has called the 'close' 314 primitive, so the local application can also issue a 'close' and 315 terminate the connection gracefully. See [RFC0793], Section 3.5. 317 abort event: When TCP aborts a connection upon receiving a "Reset" 318 from the peer, it "advises the user and goes to the CLOSED state." 319 See [RFC0793], Section 3.4. 321 USER TIMEOUT event: This event is executed when the user timeout 322 expires (see 'open') (section 3.9 of [RFC0793]). All queues are 323 flushed and the application is informed that the connection had to 324 be aborted due to user timeout. 326 ERROR_REPORT event: This event informs the application of "soft 327 errors" that can be safely ignored [RFC5461], including the 328 arrival of an ICMP error message or excessive retransmissions 329 (reaching a threshold below the threshold where the connection is 330 aborted). See section 4.2.4.1 of [RFC1122]. 332 Type-of-Service: Section 4.2.4.2 of the requirements for Internet 333 hosts [RFC1122] states that the application layer MUST be able to 334 specify the Type-of-Service (TOS) for segments that are sent on a 335 connection. The application should be able to change the TOS 336 during the connection lifetime, and the TOS value should be passed 337 to the IP layer unchanged. Since then the TOS field has been 338 redefined. The Differentiated Services (diffuser) model [RFC2475] 339 [RFC3260] replaces this field in the IP Header, assigning the six 340 most significant bits to carry the Differentiated Services Code 341 Point (DSCP) field [RFC2474]. 343 Nagle: The Nagle algorithm delays sending data for some time to 344 increase the likelihood of sending a full-sized segment (section 345 4.2.3.4 of [RFC1122]). An application can disable the Nagle 346 algorithm for an individual connection. 348 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 349 one end of a TCP connection to advertise its current user timeout 350 value so that the other end of the TCP connection can adapt its 351 own user timeout accordingly. In addition to the configurable 352 value of the User Timeout (see 'send'), there are three per- 353 connection state variables that an application can adjust to 354 control the operation of the User Timeout Option (UTO): ADV_UTO is 355 the value of the UTO advertised to the remote TCP peer (default: 356 system-wide default user timeout); ENABLED (default false) is a 357 boolean-type flag that controls whether the UTO option is enabled 358 for a connection. This applies to both sending and receiving. 359 CHANGEABLE is a boolean-type flag (default true) that controls 360 whether the user timeout may be changed based on a UTO option 361 received from the other end of the connection. CHANGEABLE becomes 362 false when an application explicitly sets the user timeout (see 363 'send'). 365 Set / Get Authentication Parameters: The preferred outgoing MKT 366 (current_key) and/or the preferred incoming MKT (rnext_key) of a 367 connection can be configured. Information about current_key and 368 rnext_key carried in a recently received segment can be retrieved 369 (section 7.1 of [RFC5925]). 371 3.1.1. Excluded Primitives or Parameters 373 The 'open' primitive can be handed optional Precedence or security/ 374 compartment information [RFC0793], but this was not included here 375 because it is mostly irrelevant today [RFC7414]. 377 The 'status' primitive was not included because the initial TCP 378 specification describes this primitive as "implementation dependent" 379 and states that it "could be excluded without adverse effect" 380 [RFC0793]. Moreover, while a data block containing specific 381 information is described, it is also stated that not all of this 382 information may always be available. While 'status' SHOULD be 383 augmented to allow the MKTs of a current or pending connection to be 384 read (for confirmation), the same information is also available via 385 'receive', which MUST be augmented with that functionality [RFC5925]. 386 The 'send' primitive includes an optional PUSH flag which, if set, 387 requires data to be promptly transmitted to the receiver without 388 delay [RFC0793]; the 'receive' primitive described in can (under some 389 conditions) yield the status of the PUSH flag. Because PUSH 390 functionality is optional to implement for both the 'send' and 391 'receive' primitives [RFC1122], this functionality is not included 392 here. The requirements for Internet hosts [RFC1122] also introduce 393 keep-alives to TCP, but these are optional to implement and hence not 394 considered here. The same document also describes that "some TCP 395 implementations have included a FLUSH call", indicating that this 396 call is also optional to implement. It is therefore not considered 397 here. 399 3.2. Primitives Provided by MPTCP 401 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 402 multiple paths for a single data-stream. It achieves this by 403 creating different so-called TCP subflows for each of the interfaces 404 and scheduling the traffic across these TCP subflows. The service 405 provided by MPTCP is described as follows [RFC6182]: "Multipath TCP 406 MUST follow the same service model as TCP [RFC0793]: in- order, 407 reliable, and byte-oriented delivery. Furthermore, a Multipath TCP 408 connection SHOULD provide the application with no worse throughput or 409 resilience than it would expect from running a single TCP connection 410 over any one of its available paths." 412 Further, there are some constraints on the API exposed by MPTCP 413 [RFC6182]: "A multipath-capable equivalent of TCP MUST retain some 414 level of backward compatibility with existing TCP APIs, so that 415 existing applications can use the newer merely by upgrading the 416 operating systems of the end hosts." As such, the primitives 417 provided by MPTCP are equivalent to the ones provided by TCP. 418 Nevertheless, the MPTCP RFCs [RFC6824] and [RFC6897] clarify some 419 parts of TCP's primitives with respect to MPTCP and add some 420 extensions for better control on MPTCP's subflows. Hereafter is a 421 list of the clarifications and extensions the above cited RFCs 422 provide to TCP's primitives. 424 open: "An application should be able to request to turn on or turn 425 off the usage of MPTCP" [RFC6897]. This functionality can be 426 provided through a socket-option called TCP_MULTIPATH_ENABLE. 427 Further, MPTCP must be disabled in case the application is binding 428 to a specific address [RFC6897]. 430 send/receive: The sending and receiving of data does not require any 431 changes to the application when MPTCP is being used [RFC6824]. 432 The MPTCP-layer will "take one input data stream from an 433 application, and split it into one or more subflows, with 434 sufficient control information to allow it to be reassembled and 435 delivered reliably and in order to the recipient application." 436 The use of the Urgent-Pointer is special in MPTCP [RFC6824]: "a 437 TCP subflow MUST NOT use the Urgent Pointer to interrupt an 438 existing mapping." 440 address and subflow management: MPTCP uses different addresses and 441 allows a host to announce these addresses as part of the protocol. 442 The MPTCP API Considerations RFC [RFC6897] says "An application 443 should be able to restrict MPTCP to binding to a given set of 444 addresses" and thus allows applications to limit the set of 445 addresses that are being used by MPTCP. Further, "An application 446 should be able to obtain information on the pairs of addresses 447 used by the MPTCP subflows". 449 3.3. Primitives Provided by SCTP 451 TCP has a number of limitations that SCPT removes (section 1.1 of 452 [RFC4960]). The following three removed limitations directly 453 translate into transport features that are visible to an application 454 using SCTP: 1) it allows for preservation of message delineations; 2) 455 these messages, while reliably transferred, do not require to be in 456 order unless the application wants it; 3) multi-homing is supported. 457 In SCTP, connections are called "associations" and they can be 458 between not only two (as in TCP) but multiple addresses at each 459 endpoint. 461 Section 10 of the SCTP base protocol specification [RFC4960] 462 specifies the interaction with the application (which this RFC calls 463 the "Upper Layer Protocol" (ULP)). It is assumed that the Operating 464 System provides a means for SCTP to asynchronously signal the 465 application; the primitives representing such signals are called 466 'events' in this section. Here, we describe the relevant primitives. 467 In addition to the abstract API described in the section 10 of the 468 SCTP base protocol specification [RFC4960], an extension to the 469 socket API is described in [RFC6458]. This covers the functionality 470 of the base protocol [RFC4960] and some of its extensions [RFC3758], 471 [RFC4895], [RFC5061]. For other protocol extensions [RFC6525], 472 [RFC6951], [RFC7053], [RFC7496], [RFC7829], 473 [I-D.ietf-tsvwg-sctp-ndata], the corresponding extensions of the 474 socket API are specified in these protocol specifications. The 475 functionality exposed to the ULP through the all these APIs is 476 considered here. 478 The abstract API contains a "SETPROTOCOLPARAMETERS" primitive that 479 allows to adjust elements of a parameter list [RFC4960]; it is stated 480 that SCTP implementations "may allow ULP to customize some of these 481 protocol parameters", indicating that none of the elements of this 482 parameter list are mandatory to make ULP-configurable. Thus, we only 483 consider the parameters in the abstract API that are also covered in 484 one of the other RFCs listed above, which leads us to exclude the 485 parameters RTO.Alpha, RTO.Beta and HB.Max.Burst. For clarity, we 486 also replace "SETPROTOCOLPARAMETERS" itself with primitives that 487 adjust parameters or groups of parameters which fit together. 489 Initialize: Initialize creates a local SCTP instance that it binds 490 to a set of local addresses (and, if provided, a local port 491 number) [RFC4960]. Initialize needs to be called only once per 492 set of local addresses. A number of per-association 493 initialization parameters can be used when an association is 494 created, but before it is connected (via the primitive 'Associate' 495 below): the maximum number of inbound streams the application is 496 prepared to support, the maximum number of attempts to be made 497 when sending the INIT (the first message of association 498 establishment), and the maximum retransmission timeout (RTO) value 499 to use when attempting an INIT [RFC6458]. At this point, before 500 connecting, an application can also enable UDP encapsulation by 501 configuring the remote UDP encapsulation port number [RFC6951]. 503 Associate: This creates an association (the SCTP equivalent of a 504 connection) that connects the local SCTP instance and a remote 505 SCTP instance. To identify the remote endpoint, it can be given 506 one or multiple (using "connectx") sockets (section 9.9 of 507 [RFC6458]). Most primitives are associated with a specific 508 association, which is assumed to first have been created. 509 Associate can return a list of destination transport addresses so 510 that multiple paths can later be used. One of the returned 511 sockets will be selected by the local endpoint as default primary 512 path for sending SCTP packets to this peer, but this choice can be 513 changed by the application using the list of destination 514 addresses. Associate is also given the number of outgoing streams 515 to request and optionally returns the number of negotiated 516 outgoing streams. An optional parameter of 32 bits, the 517 adaptation layer indication, can be provided [RFC5061]. If 518 authenticated chunks are used, the chunk types required to be sent 519 authenticated by the peer can be provided [RFC4895]. A 520 'SCTP_CANT_STR_ASSOC' notification is used to inform the 521 application of a failure to create an association [RFC6458]. An 522 application could use sendto() or sendmsg() to implicitly setup an 523 association, thereby handing over a message that SCTP might send 524 during the association setup phase [RFC6458]. Note that this 525 mechanism is different from TCP's TFO mechanism: the message would 526 arrive only once, after at least one RTT, as it is sent together 527 with the third message exchanged during association setup, the 528 COOKIE-ECHO chunk). 530 Send: This sends a message of a certain length in bytes over an 531 association. A number can be provided to later refer to the 532 correct message when reporting an error, and a stream id is 533 provided to specify the stream to be used inside an association 534 (we consider this as a mandatory parameter here for simplicity: if 535 not provided, the stream id defaults to 0). A condition to 536 abandon the message can be specified (for example limiting the 537 number of retransmissions or the lifetime of the user message). 538 This allows to control the partial reliability extension 539 [RFC3758], [RFC7496]. An optional maximum life time can specify 540 the time after which the message should be discarded rather than 541 sent. A choice (advisory, i.e. not guaranteed) of the preferred 542 path can be made by providing a socket, and the message can be 543 delivered out-of-order if the unordered flag is set. An advisory 544 flag indicates that the peer should not delay the acknowledgement 545 of the user message provided [RFC7053]. Another advisory flag 546 indicates whether the application prefers to avoid bundling user 547 data with other outbound DATA chunks (i.e., in the same packet). 548 A payload protocol-id can be provided to pass a value that 549 indicates the type of payload protocol data to the peer. If 550 authenticated chunks are used, the key identifier for 551 authenticating DATA chunks can be provided [RFC4895]. 553 Receive: Messages are received from an association, and optionally a 554 stream within the association, with their size returned. The 555 application is notified of the availability of data via a DATA 556 ARRIVE notification. If the sender has included a payload 557 protocol-id, this value is also returned. If the received message 558 is only a partial delivery of a whole message, a partial flag will 559 indicate so, in which case the stream id and a stream sequence 560 number are provided to the application. A delivery number lets 561 the application detect reordering. 563 Shutdown: This primitive gracefully closes an association, reliably 564 delivering any data that has already been handed over to SCTP. A 565 parameter lets the application control whether further receive or 566 send operations or both are disabled when the call is issued. A 567 return code informs about success or failure of this procedure. 569 Abort: This ungracefully closes an association, by discarding any 570 locally queued data and informing the peer that the association 571 was aborted. Optionally, an abort reason to be passed to the peer 572 may be provided by the application. A return code informs about 573 success or failure of this procedure. 575 Change Heartbeat / Request Heartbeat: This allows the application to 576 enable/disable heartbeats and optionally specify a heartbeat 577 frequency as well as requesting a single heartbeat to be carried 578 out upon a function call, with a notification about success or 579 failure of transmitting the HEARTBEAT chunk to the destination. 581 Configure Max. Retransmissions of an Association: The parameter Asso 582 ciation.Max.Retrans [RFC4960] (called "sasoc_maxrxt" in the SCTP 583 socket API extensions [RFC6458]), allows to configure the number 584 of unsuccessful retransmissions after which an entire association 585 is considered as failed; this should invoke a COMMUNICATION LOST 586 notification. 588 Set Primary: This allows to set a new primary default path for an 589 association by providing a socket. Optionally, a default source 590 address to be used in IP datagrams can be provided. 592 Change Local Address / Set Peer Primary: This allows an endpoint to 593 add/remove local addresses to/from an association. In addition, 594 the peer can be given a hint which address to use as the primary 595 address [RFC5061]. 597 Configure Path Switchover: The abstract API contains a primitive 598 called SET FAILURE THRESHOLD [RFC4960]. This configures the 599 parameter "Path.Max.Retrans", which determines after how many 600 retransmissions a particular transport address is considered as 601 unreachable. If there are more transport addresses available in 602 an association, reaching this limit will invoke a path switchover. 603 An extension called "SCTP-PF" adds a concept of "Potentially 604 Failed" (PF) paths to this method [RFC7829]. When a path is in PF 605 state, SCTP will not entirely give up sending on that path, but it 606 will preferably send data on other active paths if such paths are 607 available. Entering the PF state is done upon exceeding a 608 configured maximum number of retransmissions. Thus, for all paths 609 where this mechanism is used, there are two configurable error 610 thresholds: one to decide that a path is in PF state, and one to 611 decide that the transport address is unreachable. 613 Set / Get Authentication Parameters: This allows an endpoint to add/ 614 remove key material to/from an association. In addition, the 615 chunk types being authenticated can be queried [RFC4895]. 617 Add / Reset Streams, Reset Association: This allows an endpoint to 618 add streams to an existing association or or to reset them 619 individually. Additionally, the association can be reset 620 [RFC6525]. 622 Status: The 'Status' primitive returns a data block with information 623 about a specified association, containing: association connection 624 state; destination transport address list; destination transport 625 address reachability states; current local and peer receiver 626 window sizes; current local congestion window sizes; number of 627 unacknowledged DATA chunks; number of DATA chunks pending receipt; 628 primary path; most recent SRTT on primary path; RTO on primary 629 path; SRTT and RTO on other destination addresses [RFC4960] and 630 MTU per path [RFC6458]. 632 Enable / Disable Interleaving: This allows to enable or disable the 633 negotiation of user message interleaving support for future 634 associations. For existing associations it is possible to query 635 whether user message interleaving support was negotiated or not on 636 a particular association [I-D.ietf-tsvwg-sctp-ndata]. 638 Set Stream Scheduler: This allows to select a stream scheduler per 639 association, with a choice of: First Come First Serve, Round 640 Robin, Round Robin per Packet, Priority Based, Fair Bandwidth, 641 Weighted Fair Queuing [I-D.ietf-tsvwg-sctp-ndata]. 643 Configure Stream Scheduler: This allows to change a parameter per 644 stream for the schedulers: a priority value for the Priority Based 645 scheduler and a weight for the Weighted Fair Queuing scheduler. 647 Enable/disable NODELAY: This turns on/off any Nagle-like algorithm 648 for an association [RFC6458]. 650 Configure send buffer size: This controls the amount of data SCTP 651 may have waiting in internal buffers to be sent or retransmitted 652 [RFC6458]. 654 Configure receive buffer size: This sets the receive buffer size in 655 octets, thereby controlling the receiver window for an association 656 [RFC6458]. 658 Configure message fragmentation: If a user message causes an SCTP 659 packet to exceed the maximum fragmentation size (which can be 660 provided by the application, and is otherwise the PMTU size), then 661 the message will be fragmented by SCTP. Disabling message 662 fragmentation will produce an error instead of fragmenting the 663 message [RFC6458]. 665 Configure Path MTU Discovery: Path MTU Discovery can be enabled or 666 disabled per peer address of an association (section 8.1.12 of 667 [RFC6458]). When it is enabled, the current Path MTU value can be 668 obtained. When it is disabled, the Path MTU to be used can be 669 controlled by the application. 671 Configure delayed SACK timer: The time before sending a SACK can be 672 adjusted; delaying SACKs can be disabled; the number of packets 673 that must be received before a SACK is sent without waiting for 674 the delay timer to expire can be configured [RFC6458]. 676 Set Cookie life value: The Cookie life value can be adjusted 677 (section 8.1.2 of [RFC6458]). "Valid.Cookie.Life" is also one of 678 the parameters that is potentially adjustable with 679 SETPROTOCOLPARAMETERS [RFC4960]. 681 Set maximum burst: The maximum burst of packets that can be emitted 682 by a particular association (default 4, and values above 4 are 683 optional to implement) can be adjusted (section 8.1.2 of 684 [RFC6458]). "Max.Burst" is also one of the parameters that is 685 potentially adjustable with SETPROTOCOLPARAMETERS [RFC4960]. 687 Configure RTO calculation: The abstract API contains the following 688 adjustable parameters: RTO.Initial; RTO.Min; RTO.Max; RTO.Alpha; 689 RTO.Beta. Only the initial, minimum and maximum RTO are also 690 described as configurable in the SCTP sockets API extensions 691 [RFC6458]. 693 Set DSCP value: The DSCP value can be set per peer address of an 694 association (section 8.1.12 of [RFC6458]). 696 Set IPv6 flow label: The flow label field can be set per peer 697 address of an association (section 8.1.12 of [RFC6458]). 699 Set Partial Delivery Point: This allows to specify the size of a 700 message where partial delivery will be invoked. Setting this to a 701 lower value will cause partial deliveries to happen more often 702 [RFC6458]. 704 COMMUNICATION UP notification: When a lost communication to an 705 endpoint is restored or when SCTP becomes ready to send or receive 706 user messages, this notification informs the application process 707 about the affected association, the type of event that has 708 occurred, the complete set of sockets of the peer, the maximum 709 number of allowed streams and the inbound stream count (the number 710 of streams the peer endpoint has requested). If interleaving is 711 supported by both endpoints, this information is also included in 712 this notification. 714 RESTART notification: When SCTP has detected that the peer has 715 restarted, this notification is passed to the upper layer 716 [RFC6458]. 718 DATA ARRIVE notification: When a message is ready to be retrieved 719 via the Receive primitive, the application is informed by this 720 notification. 722 SEND FAILURE notification / Receive Unsent Message / Receive 723 Unacknowledged Message: 724 When a message cannot be delivered via an association, the sender 725 can be informed about it and learn whether the message has just 726 not been acknowledged or (e.g. in case of lifetime expiry) if it 727 has not even been sent. This can also inform the sender that a 728 part of the message has been successfully delivered. 730 NETWORK STATUS CHANGE notification: The NETWORK STATUS CHANGE 731 notification informs the application about a socket becoming 732 active/inactive [RFC4960] or "Potentially Failed" [RFC7829]. 734 COMMUNICATION LOST notification: When SCTP loses communication to an 735 endpoint (e.g. via Heartbeats or excessive retransmission) or 736 detects an abort, this notification informs the application 737 process of the affected association and the type of event (failure 738 OR termination in response to a shutdown or abort request). 740 SHUTDOWN COMPLETE notification: When SCTP completes the shutdown 741 procedures, this notification is passed to the upper layer, 742 informing it about the affected assocation. 744 AUTHENTICATION notification: When SCTP wants to notify the upper 745 layer regarding the key management related to authenticated chunks 746 [RFC4895], this notification is passed to the upper layer. 748 ADAPTATION LAYER INDICATION notification: When SCTP completes the 749 association setup and the peer provided an adaptation layer 750 indication, this is passed to the upper layer [RFC5061], 751 [RFC6458]. 753 STREAM RESET notification: When SCTP completes the procedure for 754 resetting streams [RFC6525], this notification is passed to the 755 upper layer, informing it about the result. 757 ASSOCIATION RESET notification: When SCTP completes the association 758 reset procedure [RFC6525], this notification is passed to the 759 upper layer, informing it about the result. 761 STREAM CHANGE notification: When SCTP completes the procedure used 762 to increase the number of streams [RFC6525], this notification is 763 passed to the upper layer, informing it about the result. 765 SENDER DRY notification: When SCTP has no more user data to send or 766 retransmit on a particular association, this notification is 767 passed to the upper layer [RFC6458]. 769 PARTIAL DELIVERY ABORTED notification: When a receiver has begun to 770 receive parts of a user message but the delivery of this message 771 is then aborted, this notification is passed to the upper layer 772 (section 6.1.7 of [RFC6458]). 774 3.3.1. Excluded Primitives or Parameters 776 The 'Receive' primitive can return certain additional information, 777 but this is optional to implement and therefore not considered. With 778 a COMMUNICATION LOST notification, some more information may 779 optionally be passed to the application (e.g., identification to 780 retrieve unsent and unacknowledged data). SCTP "can invoke" a 781 COMMUNICATION ERROR notification and "may send" a RESTART 782 notification, making these two notifications optional to implement. 783 The list provided under 'Status' includes "etc", indicating that more 784 information could be provided. The primitive 'Get SRTT Report' 785 returns information that is included in the information that 'Status' 786 provides and is therefore not discussed. The 'Destroy SCTP Instance' 787 API function was excluded: it erases the SCTP instance that was 788 created by 'Initialize', but is not a Primitive as defined in this 789 document because it does not relate to a transport feature. The 790 SHUTDOWN EVENT informs an application that the peer has sent a 791 SHUTDOWN, and hence no further data should be sent on this socket 792 (section 6.1 of [RFC6458]). However, if an application would try to 793 send data on the socket, it would get an error message anyway; thus, 794 this event is classified as "just affecting the application 795 programming style, not how the underlying protocol operates" and not 796 included here. 798 3.4. Primitives Provided by UDP and UDP-Lite 800 The initial UDP specification [RFC0768] states: "This User Datagram 801 Protocol (UDP) is defined to make available a datagram mode of 802 packet-switched computer communication in the environment of an 803 interconnected set of computer networks." It "provides a procedure 804 for application programs to send messages to other programs with a 805 minimum of protocol mechanism (..)". 807 The User Interface section of RFC768 states that the user interface 808 to an application should be able to create receive, source and 809 destination ports and addresses, and provide operations to receive 810 data based on ports with an indication of source port and address. 811 Operations should be provided that allow datagrams be sent specifying 812 the source and destination ports and addresses to be sent. 814 UDP offers only a basic transport interface. UDP datagrams may be 815 directly sent and received, without exchanging messages between the 816 endpoints to setup a connection (i.e., no handshake is performed by 817 the transport protocol prior to communication). Neither UDP nor UDP- 818 Lite provide congestion control, retransmission, nor do they have 819 support to optimise fragmentation and other transport functions. 820 This means that applications using UDP need to provide additional 821 functions on top of the UDP transport API [RFC8085]. Guidance on the 822 use of the services provided by UDP is provided in the UDP Guidelines 823 [RFC8085]. 825 The set of pass 1 primitives for UDP and UDP-Lite is documented in 826 [FJ16]. 828 3.5. The service of LEDBAT 830 The service of the Low Extra Delay Background Transport (LEDBAT) 831 congestion control mechanism is described as follows: "LEDBAT is 832 designed for use by background bulk-transfer applications to be no 833 more aggressive than standard TCP congestion control (as specified in 834 RFC 5681) and to yield in the presence of competing flows, thus 835 limiting interference with the network performance of competing 836 flows" [RFC6817]. 838 LEDBAT does not have any primitives, as LEDBAT is not a transport 839 protocol. According to its specification [RFC6817], "LEDBAT can be 840 used as part of a transport protocol or as part of an application, as 841 long as the data transmission mechanisms are capable of carrying 842 timestamps and acknowledging data frequently. LEDBAT can be used 843 with TCP, Stream Control Transmission Protocol (SCTP), and Datagram 844 Congestion Control Protocol (DCCP), with appropriate extensions where 845 necessary; and it can be used with proprietary application protocols, 846 such as those built on top of UDP for peer-to- peer (P2P) 847 applications." At the time of writing, the appropriate extensions 848 for TCP, SCTP or DCCP do not exist. 850 A numer of configurable parameters exist in the LEDBAT specification: 851 TARGET, which is the queuing delay target at which LEDBAT tries to 852 operate, must be set to 100ms or less. ALLOWED_INCREASE (should be 853 1, must be greater than 0) limits the speed at which LEDBAT increases 854 its rate. GAIN, which MUST be set to 1 or less to avoid a faster 855 ramp-up than TCP Reno, determines how quickly the sender responds to 856 changes in queueing delay. Implementations may divide GAIN into two 857 parameters, one for increase and a possibly larger one for decrease. 858 We call these parameters GAIN_INC and GAIN_DEC here. BASE_HISTORY is 859 the size of the list of measured base delays, and SHOULD be 10. This 860 list can be filtered using a FILTER() function which is not 861 prescribed [RFC6817], yielding a list of size CURRENT_FILTER. The 862 initial and minimum congestion windows, INIT_CWND and MIN_CWND, 863 should both be 2. 865 Regarding which of these parameters should be under control of an 866 application, the possible range goes from exposing nothing on the one 867 hand, to considering everything that is not prescribed with a MUST in 868 the specification as a parameter on the other hand. Function 869 implementations are not provided as a parameter to any of the 870 transport protocols discussed here, and hence we do not regard the 871 FILTER() function as a parameter. However, to avoid unnecessarily 872 limiting future implementations, we consider all other parameters 873 above as tunable parameters that should be exposed. 875 4. Pass 2 877 This pass categorizes the primitives from pass 1 based on whether 878 they relate to a connection or to data transmission. Primitives are 879 presented following the nomenclature 880 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 881 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 882 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 883 considered. The DATA category does not have any SUBCATEGORY. The 884 PROTOCOL name "UDP(-Lite)" is used when primitives are equivalent for 885 UDP and UDP-Lite; the PROTOCOL name "TCP" refers to both TCP and 886 MPTCP. We present "connection" as a general protocol-independent 887 concept and use it to refer to, e.g., TCP connections (identifiable 888 by a unique pair of IP addresses and TCP port numbers), SCTP 889 associations (identifiable by multiple IP address and port number 890 pairs), as well UDP and UDP-Lite connections (identifiable by a 891 unique socket pair). 893 Some minor details are omitted for the sake of generalization -- 894 e.g., SCTP's 'close' [RFC4960] returns success or failure, and lets 895 the application control whether further receive or send operations or 896 both are disabled [RFC6458]. This is not described in the same way 897 for TCP [RFC0793], but these details play no significant role for the 898 primitives provided by either TCP or SCTP (for the sake of being 899 generic, it could be assumed that both receive and send operations 900 are disabled in both cases). 902 The TCP 'send' and 'receive' primitives include usage of an "URGENT" 903 mechanism. This mechanism is required to implement the "synch 904 signal" used by telnet [RFC0854], but SHOULD NOT be used by new 905 applications [RFC6093]. Because pass 2 is meant as a basis for the 906 creation of future systems, the "URGENT" mechanism is excluded. This 907 also concerns the notification "Urgent pointer advance" in the 908 ERROR_REPORT (section 4.2.4.1 of [RFC1122]). 910 Since LEDBAT is a congestion control mechanism and not a protocol, it 911 is not currently defined when to enable / disable or configure the 912 mechanism. For instance, it could be a one-time choice upon 913 connection establishment or when listening for incoming connections, 914 in which case it should be categorized under CONNECTION.ESTABLISHMENT 915 or CONNECTION.AVAILABILITY, respectively. To avoid unnecessarily 916 limiting future implementations, it was decided to place it under 917 CONNECTION.MAINTENANCE, with all parameters that are described in the 918 specification [RFC6817] made configurable. 920 4.1. CONNECTION Related Primitives 922 ESTABLISHMENT: 923 Active creation of a connection from one transport endpoint to one or 924 more transport endpoints. 925 Interfaces to UDP and UDP-Lite allow both connection-oriented and 926 connection-less usage of the API [RFC8085]. 928 o CONNECT.TCP: 929 Pass 1 primitive / event: 'open' (active) or 'open' (passive) with 930 socket, followed by 'send' 931 Parameters: 1 local IP address (optional); 1 destination transport 932 address (for active open; else the socket and the local IP address 933 of the succeeding incoming connection request will be maintained); 934 timeout (optional); options (optional); MKT configuration 935 (optional); user message (optional) 936 Comments: If the local IP address is not provided, a default 937 choice will automatically be made. The timeout can also be a 938 retransmission count. The options are IP options to be used on 939 all segments of the connection. At least the Source Route option 940 is mandatory for TCP to provide. 'MKT configuration' refers to 941 the ability to configure Master Key Tuples (MKTs) for 942 authentication. The user message may be transmitted to the peer 943 application immediately upon reception of the TCP SYN packet. To 944 benefit from the lower latency this provides as part of the 945 experimental TFO mechanism, its length must be at most the TCP's 946 maximum segment size (minus TCP options used in the SYN). The 947 message may also be delivered more than once to the application on 948 the remote host. 950 o CONNECT.SCTP: 951 Pass 1 primitive / event: 'initialize', followed by 'enable / 952 disable interleaving' (optional), followed by 'associate' 953 Parameters: list of local SCTP port number / IP address pairs 954 (initialize); one or several sockets (identifying the peer); 955 outbound stream count; maximum allowed inbound stream count; 956 adaptation layer indication (optional); chunk types required to be 957 authenticated (optional); request interleaving on/off; maximum 958 number of INIT attemps (optional); maximum init. RTO for INIT 959 (optional); user message (optional); remote UDP port number 960 (optional) 961 Returns: socket list or failure 962 Comments: 'initialize' needs to be called only once per list of 963 local SCTP port number / IP address pairs. One socket will 964 automatically be chosen; it can later be changed in MAINTENANCE. 965 The user message may be transmitted to the peer application 966 immediately upon reception of the packet containing the COOKIE- 967 ECHO chunk. To benefit from the lower latency this provides, its 968 length must be limited such that it fits into the packet 969 containing the COOKIE-ECHO chunk. If a remote UDP port number is 970 provided, SCTP packets will be encapsulated in UDP. 972 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): 978 Pass 1 primitive / event: 'connect' followed by 'send'. 979 Parameters: 1 local IP address (default (ANY), or specified); 1 980 destination transport address; 1 local port (default (OS chooses), 981 or specified); 1 destination port (default (OS chooses), or 982 specified). 983 Comments: Associates a transport address creating a UDP(-Lite) 984 socket connection. This can be called again with a new transport 985 address to create a new connection. The CONNECT function allows 986 an application to receive errors from messages sent to a transport 987 address. 989 AVAILABILITY: 990 Preparing to receive incoming connection requests. 992 o LISTEN.TCP: 993 Pass 1 primitive / event: 'open' (passive) 994 Parameters: 1 local IP address (optional); 1 socket (optional); 995 timeout (optional); buffer to receive a user message (optional); 996 MKT configuration (optional) 997 Comments: if the socket and/or local IP address is provided, this 998 waits for incoming connections from only and/or to only the 999 provided address. Else this waits for incoming connections 1000 without this / these constraint(s). ESTABLISHMENT can later be 1001 performed with 'send'. If a buffer is provided to receive a user 1002 message, a user message can be received from a TFO-enabled sender 1003 before TCP's connection handshake is completed. This message may 1004 arrive multiple times. 'MKT configuration' refers to the ability 1005 to configure Master Key Tuples (MKTs) for authentication. 1007 o LISTEN.SCTP: 1008 Pass 1 primitive / event: 'initialize', followed by 'COMMUNICATION 1009 UP' or 'RESTART' notification and possibly 'ADAPTATION LAYER' 1010 notification 1011 Parameters: list of local SCTP port number / IP address pairs 1012 (initialize) 1013 Returns: socket list; outbound stream count; inbound stream count; 1014 adaptation layer indication; chunks required to be authenticated; 1015 interleaving supported on both sides yes/no 1016 Comments: initialize needs to be called only once per list of 1017 local SCTP port number / IP address pairs. COMMUNICATION UP can 1018 also follow a COMMUNICATION LOST notification, indicating that the 1019 lost communication is restored. If the peer has provided an 1020 adaptation layer indication, an 'ADAPTATION LAYER' notification is 1021 issued. 1023 o LISTEN.MPTCP: 1024 This is similar to LISTEN.TCP except for one additional boolean 1025 parameter that allows to enable or disable MPTCP for a particular 1026 connection or socket (default: enabled). 1028 o LISTEN.UDP(-Lite): 1029 Pass 1 primitive / event: 'receive'. 1031 Parameters: 1 local IP address (default (ANY), or specified); 1 1032 destination transport address; local port (default (OS chooses), 1033 or specified); destination port (default (OS chooses), or 1034 specified). 1035 Comments: The receive function registers the application to listen 1036 for incoming UDP(-Lite) datagrams at an endpoint. 1038 MAINTENANCE: 1039 Adjustments made to an open connection, or notifications about it. 1040 These are out-of-band messages to the protocol that can be issued at 1041 any time, at least after a connection has been established and before 1042 it has been terminated (with one exception: CHANGE_TIMEOUT.TCP can 1043 only be issued for an open connection when DATA.SEND.TCP is called). 1044 In some cases, these primitives can also be immediately issued during 1045 ESTABLISHMENT or AVAILABILITY, without waiting for the connection to 1046 be opened (e.g. CHANGE_TIMEOUT.TCP can be done using TCP's 'open' 1047 primitive). For UDP and UDP-Lite, these functions may establish a 1048 setting per connection, but may also be changed per datagram message. 1050 o CHANGE_TIMEOUT.TCP: 1051 Pass 1 primitive / event: 'open' or 'send' combined with 1052 unspecified control of per-connection state variables 1053 Parameters: timeout value (optional); ADV_UTO (optional); boolean 1054 UTO_ENABLED (optional, default false); boolean CHANGEABLE 1055 (optional, default true) 1056 Comments: when sending data, an application can adjust the 1057 connection's timeout value (time after which the connection will 1058 be aborted if data could not be delivered). If UTO_ENABLED is 1059 true, the user timeout value (or, if provided, the value ADV_UTO) 1060 will be advertised for the TCP on the other side of the connection 1061 to adapt its own user timeout accordingly. UTO_ENABLED controls 1062 whether the UTO option is enabled for a connection. This applies 1063 to both sending and receiving. CHANGEABLE controls whether the 1064 user timeout may be changed based on a UTO option received from 1065 the other end of the connection; it becomes false when 'timeout 1066 value' is used. 1068 o CHANGE_TIMEOUT.SCTP: 1069 Pass 1 primitive / event: 'Change HeartBeat' combined with 1070 'Configure Max. Retransmissions of an Association' 1071 Parameters: 'Change HeartBeat': heartbeat frequency; 'Configure 1072 Max. Retransmissions of an Association': Association.Max.Retrans 1073 Comments: Change Heartbeat can enable / disable heartbeats in SCTP 1074 as well as change their frequency. The parameter 1075 Association.Max.Retrans defines after how many unsuccessful 1076 transmissions of any packets (including heartbeats) the 1077 association will be terminated; thus these two primitives / 1078 parameters together can yield a similar behavior for SCTP 1079 associations as CHANGE_TIMEOUT.TCP does for TCP connections. 1081 o DISABLE_NAGLE.TCP: 1082 Pass 1 primitive / event: not specified 1083 Parameters: one boolean value 1084 Comments: the Nagle algorithm delays data transmission to increase 1085 the chance to send a full-sized segment. An application must be 1086 able to disable this algorithm for a connection. 1088 o DISABLE_NAGLE.SCTP: 1089 Pass 1 primitive / event: 'Enable/disable NODELAY' 1090 Parameters: one boolean value 1091 Comments: Nagle-like algorithms delay data transmission to 1092 increase the chance to send a full-sized packet. 1094 o REQUEST_HEARTBEAT.SCTP: 1095 Pass 1 primitive / event: 'Request HeartBeat' 1096 Parameters: socket 1097 Returns: success or failure 1098 Comments: requests an immediate heartbeat on a path, returning 1099 success or failure. 1101 o ADD_PATH.MPTCP: 1102 Pass 1 primitive / event: not specified 1103 Parameters: local IP address and optionally the local port number 1104 Comments: the application specifies the local IP address and port 1105 number that must be used for a new subflow. 1107 o ADD_PATH.SCTP: 1108 Pass 1 primitive / event: Change Local Address / Set Peer Primary 1109 Parameters: local IP address 1111 o REM_PATH.MPTCP: 1112 Pass 1 primitive / event: not specified 1113 Parameters: local IP address, local port number, remote IP 1114 address, remote port number 1115 Comments: the application removes the subflow specified by the IP/ 1116 port-pair. The MPTCP implementation must trigger a removal of the 1117 subflow that belongs to this IP/port-pair. 1119 o REM_PATH.SCTP: 1120 Pass 1 primitive / event: 'Change Local Address / Set Peer 1121 Primary' 1122 Parameters: local IP address 1124 o SET_PRIMARY.SCTP: 1125 Pass 1 primitive / event: 'Set Primary' 1126 Parameters: socket 1127 Returns: result of attempting this operation 1128 Comments: update the current primary address to be used, based on 1129 the set of available sockets of the association. 1131 o SET_PEER_PRIMARY.SCTP: 1132 Pass 1 primitive / event: 'Change Local Address / Set Peer 1133 Primary' 1134 Parameters: local IP address 1135 Comments: this is only advisory for the peer. 1137 o CONFIG_SWITCHOVER.SCTP: 1138 Pass 1 primitive / event: 'Configure Path Switchover' 1139 Parameters: primary max retrans (no. of retransmissions after 1140 which a path is considered inactive), PF max retrans (no. of 1141 retransmissions after which a path is considered to be 1142 "Potentially Failed", and others will be preferably used) 1143 (optional) 1145 o STATUS.SCTP: 1146 Pass 1 primitive / event: 'Status', 'Enable / Disable 1147 Interleaving' and 'NETWORK STATUS CHANGE notification'. 1149 Returns: data block with information about a specified 1150 association, containing: association connection state; destination 1151 transport address list; destination transport address reachability 1152 states; current local and peer receiver window sizes; current 1153 local congestion window sizes; number of unacknowledged DATA 1154 chunks; number of DATA chunks pending receipt; primary path; most 1155 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1156 other destination addresses; MTU per path; interleaving supported 1157 yes/no. 1158 Comments: The NETWORK STATUS CHANGE notification informs the 1159 application about a socket becoming active/inactive; this only 1160 affects the programming style, as the same information is also 1161 available via 'Status'. 1163 o STATUS.MPTCP: 1164 Pass 1 primitive / event: not specified 1165 Returns: list of pairs of tuples of IP address and TCP port number 1166 of each subflow. The first of the pair is the local IP and port 1167 number, while the second is the remote IP and port number. 1169 o SET_DSCP.TCP: 1170 Pass 1 primitive / event: not specified 1171 Parameters: DSCP value 1172 Comments: this allows an application to change the DSCP value for 1173 outgoing segments. 1175 o SET_DSCP.SCTP: 1176 Pass 1 primitive / event: 'Set DSCP value' 1177 Parameters: DSCP value 1178 Comments: this allows an application to change the DSCP value for 1179 outgoing packets on a path. 1181 o SET_DSCP.UDP(-Lite): 1182 Pass 1 primitive / event: 'SET_DSCP' 1183 Parameter: DSCP value 1184 Comments: This allows an application to change the DSCP value for 1185 outgoing UDP(-Lite) datagrams. [RFC7657] and [RFC8085] provide 1186 current guidance on using this value with UDP. 1188 o ERROR.TCP: 1189 Pass 1 primitive / event: 'ERROR_REPORT' 1190 Returns: reason (encoding not specified); subreason (encoding not 1191 specified) 1192 Comments: soft errors that can be ignored without harm by many 1193 applications; an application should be able to disable these 1194 notifications. The reported conditions include at least: ICMP 1195 error message arrived; Excessive Retransmissions. 1197 o ERROR.UDP(-Lite): 1198 Pass 1 primitive / event: 'ERROR_REPORT' 1199 Returns: Error report 1200 Comments: This returns soft errors that may be ignored without 1201 harm by many applications; An application must connect to be able 1202 receive these notifications. 1204 o SET_AUTH.TCP: 1205 Pass 1 primitive / event: not specified 1206 Parameters: current_key, rnext_key 1207 Comments: current_key and rnext_key are the preferred outgoing MKT 1208 and the preferred incoming MKT, respectively, for a segment that 1209 is sent on the connection. 1211 o SET_AUTH.SCTP: 1212 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1213 Parameters: key_id, key, hmac_id 1215 o GET_AUTH.TCP: 1216 Pass 1 primitive / event: not specified 1217 Parameters: current_key, rnext_key 1218 Comments: current_key and rnext_key are the preferred outgoing MKT 1219 and the preferred incoming MKT, respectively, that were carried on 1220 a recently received segment. 1222 o GET_AUTH.SCTP: 1223 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1224 Parameters: key_id, chunk_list 1226 o RESET_STREAM.SCTP: 1227 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1228 Parameters: sid, direction 1230 o RESET_STREAM-EVENT.SCTP: 1231 Pass 1 primitive / event: 'STREAM RESET notification' 1232 Parameters: information about the result of RESET_STREAM.SCTP. 1233 Comments: This is issued when the procedure for resetting streams 1234 has completed. 1236 o RESET_ASSOC.SCTP: 1237 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1238 Parameters: information related to the extension, defined in 1239 [RFC3260]. 1241 o RESET_ASSOC-EVENT.SCTP: 1242 Pass 1 primitive / event: 'ASSOCIATION RESET notification' 1243 Parameters: information about the result of RESET_ASSOC.SCTP. 1244 Comments: This is issued when the procedure for resetting an 1245 association has completed. 1247 o ADD_STREAM.SCTP: 1248 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1249 Parameters: number if outgoing and incoming streams to be added 1251 o ADD_STREAM-EVENT.SCTP: 1252 Pass 1 primitive / event: 'STREAM CHANGE notification' 1253 Parameters: information about the result of ADD_STREAM.SCTP. 1254 Comments: This is issued when the procedure for adding a stream 1255 has completed. 1257 o SET_STREAM_SCHEDULER.SCTP: 1258 Pass 1 primitive / event: 'Set Stream Scheduler' 1259 Parameters: scheduler identifier 1260 Comments: choice of First Come First Serve, Round Robin, Round 1261 Robin per Packet, Priority Based, Fair Bandwidth, Weighted Fair 1262 Queuing. 1264 o CONFIGURE_STREAM_SCHEDULER.SCTP: 1265 Pass 1 primitive / event: 'Configure Stream Scheduler' 1266 Parameters: priority 1267 Comments: the priority value only applies when Priority Based or 1268 Weighted Fair Queuing scheduling is chosen with 1269 SET_STREAM_SCHEDULER.SCTP. The meaning of the parameter differs 1270 between these two schedulers but in both cases it realizes some 1271 form of prioritization regarding how bandwidth is divided among 1272 streams. 1274 o SET_FLOWLABEL.SCTP: 1275 Pass 1 primitive / event: 'Set IPv6 flow label' 1276 Parameters: flow label 1277 Comments: this allows an application to change the IPv6 header's 1278 flow label field for outgoing packets on a path. 1280 o AUTHENTICATION_NOTIFICATION-EVENT.SCTP: 1281 Pass 1 primitive / event: 'AUTHENTICATION notification' 1282 Returns: information regarding key management. 1284 o CONFIG_SEND_BUFFER.SCTP: 1285 Pass 1 primitive / event: 'Configure send buffer size' 1286 Parameters: size value in octets 1288 o CONFIG_RECEIVE_BUFFER.SCTP: 1289 Pass 1 primitive / event: 'Configure receive buffer size' 1290 Parameters: size value in octets 1291 Comments: this controls the receiver window. 1293 o CONFIG_FRAGMENTATION.SCTP: 1294 Pass 1 primitive / event: 'Configure message fragmentation' 1295 Parameters: one boolean value (enable/disable), maximum 1296 fragmentation size (optional; default: PMTU) 1297 Comments: if fragmentation is enabled, messages exceeding the 1298 maximum fragmentation size will be fragmented. If fragmentation 1299 is disabled, trying to send a message that exceeds the maximum 1300 fragmentation size will produce an error. 1302 o CONFIG_PMTUD.SCTP: 1303 Pass 1 primitive / event: 'Configure Path MTU Discovery' 1304 Parameters: one boolean value (PMTUD on/off), PMTU value 1305 (optional) 1306 Returns: PMTU value 1307 Comments: This returns a meaningful PMTU value when PMTUD is 1308 enabled (the boolean is true), and the PMTU value can be set if 1309 PMTUD is disabled (the boolean is false) 1311 o CONFIG_DELAYED_SACK.SCTP: 1312 Pass 1 primitive / event: 'Configure delayed SACK timer' 1313 Parameters: one boolean value (delayed SACK on/off), timer value 1314 (optional), number of packets to wait for (default 2) 1315 Comments: If delayed SACK is enabled, SCTP will send a SACK upon 1316 either receiving the provided number of packets or when the timer 1317 expires, whatever occurs first. 1319 o CONFIG_RTO.SCTP: 1320 Pass 1 primitive / event: 'Configure RTO calculation' 1321 Parameters: init (optional), min (optional), max (optional) 1322 Comments: This adjusts the initial, minimum and maximum RTO 1323 values. 1325 o SET_COOKIE_LIFE.SCTP: 1326 Pass 1 primitive / event: 'Set Cookie life value' 1327 Parameters: cookie life value 1329 o SET_MAX_BURST.SCTP: 1330 Pass 1 primitive / event: 'Set maximum burst' 1331 Parameters: max burst value 1332 Comments: not all implementations allow values above the default 1333 of 4. 1335 o SET_PARTIAL_DELIVERY_POINT.SCTP: 1336 Pass 1 primitive / event: 'Set Partial Delivery Point' 1337 Parameters: partial delivery point (integer) 1338 Comments: this parameter must be smaller or equal to the socket 1339 receive buffer size. 1341 o SET_CHECKSUM_ENABLED.UDP: 1342 Pass 1 primitive / event: 'CHECKSUM_ENABLED'. 1343 Parameters: 0 when zero checksum is used at sender, 1 for checksum 1344 at sender (default) 1346 o SET_CHECKSUM_REQUIRED.UDP: 1347 Pass 1 primitive / event: 'REQUIRE_CHECKSUM'. 1348 Parameter: 0 to allow zero checksum, 1 when a non-zero checksum is 1349 required (default) at receiver 1351 o SET_CHECKSUM_COVERAGE.UDP-Lite: 1352 Pass 1 primitive / event: 'SET_CHECKSUM_COVERAGE' 1353 Parameters: Coverage length at sender (default maximum coverage) 1355 o SET_MIN_CHECKSUM_COVERAGE.UDP-Lite: 1356 Pass 1 primitive / event: 'SET_MIN_COVERAGE'. 1357 Parameter: Coverage length at receiver (default minimum coverage) 1359 o SET_DF.UDP(-Lite): 1360 Pass 1 primitive event: 'SET_DF'. 1361 Parameter: 0 when DF is not set (default) in the IPv4 header, 1 1362 when DF is set 1364 o GET_MMS_S.UDP(-Lite): 1365 Pass 1 primitive event: 'GET_MMS_S'. 1366 Comments: this retrieves the maximum transport-message size that 1367 may be sent using a non-fragmented IP packet from the configured 1368 interface. 1370 o GET_MMS_R.UDP(-Lite): 1371 Pass 1 primitive event: 'GET_MMS_R'. 1372 Comments: this retrieves the maximum transport-message size that 1373 may be received from the configured interface. 1375 o SET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1376 Pass 1 primitive / event: 'SET_TTL' and 'SET_IPV6_UNICAST_HOPS' 1377 Parameters: IPv4 TTL value or IPv6 Hop Count value 1378 Comments: This allows an application to change the IPv4 TTL of 1379 IPv6 Hop count value for outgoing UDP(-Lite) datagrams. 1381 o GET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1382 Pass 1 primitive / event: 'GET_TTL' and 'GET_IPV6_UNICAST_HOPS' 1383 Returns: IPv4 TTL value or IPv6 Hop Count value 1384 Comments: This allows an application to read the the IPv4 TTL of 1385 IPv6 Hop count value from a received UDP(-Lite) datagram. 1387 o SET_ECN.UDP(-Lite): 1388 Pass 1 primitive / event: 'SET_ECN' 1389 Parameters: ECN value 1390 Comments: This allows a UDP(-Lite) application to set the ECN 1391 codepoint field for outgoing UDP(-Lite) datagrams. Defaults to 1392 sending '00'. 1394 o GET_ECN.UDP(-Lite): 1395 Pass 1 primitive / event: 'GET_ECN' 1396 Parameters: ECN value 1397 Comments: This allows a UDP(-Lite) application to read the ECN 1398 codepoint field from a received UDP(-Lite) datagram. 1400 o SET_IP_OPTIONS.UDP(-Lite): 1401 Pass 1 primitive / event: 'SET_IP_OPTIONS' 1402 Parameters: options 1403 Comments: This allows a UDP(-Lite) application to set IP Options 1404 for outgoing UDP(-Lite) datagrams. These options can at least be 1405 the Source Route, Record Route, and Time Stamp option. 1407 o GET_IP_OPTIONS.UDP(-Lite): 1408 Pass 1 primitive / event: 'GET_IP_OPTIONS' 1409 Returns: options 1410 Comments: This allows a UDP(-Lite) application to receive any IP 1411 options that are contained in a received UDP(-Lite) datagram. 1413 o CONFIGURE.LEDBAT: 1414 Pass 1 primitive / event: N/A 1415 Parameters: enable (boolean), TARGET, ALLOWED_INCREASE, GAIN_INC, 1416 GAIN_DEC, BASE_HISTORY, CURRENT_FILTER, INIT_CWND, MIN_CWND 1417 Comments: enable is a newly invented parameter that enables or 1418 disables the whole LEDBAT service. 1420 TERMINATION: 1421 Gracefully or forcefully closing a connection, or being informed 1422 about this event happening. 1424 o CLOSE.TCP: 1425 Pass 1 primitive / event: 'close' 1426 Comments: this terminates the sending side of a connection after 1427 reliably delivering all remaining data. 1429 o CLOSE.SCTP: 1430 Pass 1 primitive / event: 'Shutdown' 1431 Comments: this terminates a connection after reliably delivering 1432 all remaining data. 1434 o ABORT.TCP: 1435 Pass 1 primitive / event: 'abort' 1436 Comments: this terminates a connection without delivering 1437 remaining data and sends an error message to the other side. 1439 o ABORT.SCTP: 1440 Pass 1 primitive / event: 'abort' 1441 Parameters: abort reason to be given to the peer (optional) 1442 Comments: this terminates a connection without delivering 1443 remaining data and sends an error message to the other side. 1445 o ABORT.UDP(-Lite): 1446 Pass 1 primitive event: 'CLOSE' 1447 Comments: this terminates a connection without delivering 1448 remaining data. No further UDP(-Lite) datagrams are sent/received 1449 for this transport service instance. 1451 o TIMEOUT.TCP: 1452 Pass 1 primitive / event: 'USER TIMEOUT' event 1453 Comments: the application is informed that the connection is 1454 aborted. This event is executed on expiration of the timeout set 1455 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 1456 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 1458 o TIMEOUT.SCTP: 1459 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1460 Comments: the application is informed that the connection is 1461 aborted. this event is executed on expiration of the timeout that 1462 should be enabled by default (see the beginning of section 8.3 in 1463 [RFC4960]) and was possibly adjusted in 1464 CONNECTION.MAINTENANCE.CHANGE_TIMEOOUT.SCTP. 1466 o ABORT-EVENT.TCP: 1467 Pass 1 primitive / event: not specified. 1469 o ABORT-EVENT.SCTP: 1470 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1471 Returns: abort reason from the peer (if available) 1472 Comments: the application is informed that the other side has 1473 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 1475 o CLOSE-EVENT.TCP: 1476 Pass 1 primitive / event: not specified. 1478 o CLOSE-EVENT.SCTP: 1479 Pass 1 primitive / event: 'SHUTDOWN COMPLETE' event 1480 Comments: the application is informed that 1481 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 1483 4.2. DATA Transfer Related Primitives 1485 All primitives in this section refer to an existing connection, i.e. 1486 a connection that was either established or made available for 1487 receiving data (although this is optional for the primitives of UDP(- 1488 Lite)). In addition to the listed parameters, all sending primitives 1489 contain a reference to a data block and all receiving primitives 1490 contain a reference to available buffer space for the data. Note 1491 that CONNECT.TCP and LISTEN.TCP in the ESTABLISHMENT and AVAILABILITY 1492 category also allow to transfer data (an optional user message) 1493 before the connection is fully established. 1495 o SEND.TCP: 1496 Pass 1 primitive / event: 'send' 1497 Parameters: timeout (optional), current_key (optional), rnext_key 1498 (optional) 1499 Comments: this gives TCP a data block for reliable transmission to 1500 the TCP on the other side of the connection. The timeout can be 1501 configured with this call (see also 1502 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). current_key and 1503 rnext_key are authentication parameters that can be configured 1504 with this call (see also CONNECTION.MAINTENANCE.SET_AUTH.TCP). 1506 o SEND.SCTP: 1507 Pass 1 primitive / event: 'Send' 1508 Parameters: stream number; context (optional); socket (optional); 1509 unordered flag (optional); no-bundle flag (optional); payload 1510 protocol-id (optional); pr-policy (optional) pr-value (optional); 1511 sack-immediately flag (optional); key-id (optional) 1512 Comments: this gives SCTP a data block for transmission to the 1513 SCTP on the other side of the connection (SCTP association). The 1514 'stream number' denotes the stream to be used. The 'context' 1515 number can later be used to refer to the correct message when an 1516 error is reported. The 'socket' can be used to state which path 1517 should be preferred, if there are multiple paths available (see 1518 also CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can 1519 be delivered out-of-order if the 'unordered flag' is set. The 1520 'no-bundle flag' can be set to indicate a preference to avoid 1521 bundling. The 'payload protocol-id' is a number that will, if 1522 provided, be handed over to the receiving application. Using pr- 1523 policy and pr-value the level of reliability can be controlled. 1524 The 'sack-immediately' flag can be used to indicate that the peer 1525 should not delay the sending of a SACK corresponding to the 1526 provided user message. If specified, the provided key-id is used 1527 for authenticating the user message. 1529 o SEND.UDP(-Lite): 1530 Pass 1 primitive / event: 'SEND' 1531 Parameters: IP Address and Port Number of the destination endpoint 1532 (optional if connected). 1533 Comments: This provides a message for unreliable transmission 1534 using UDP(-Lite) to the specified transport address. IP address 1535 and Port may be omitted for connected UDP(-Lite) sockets. All 1536 CONNECTION.MAINTENANCE.SET_*.UDP(-Lite) primitives apply per 1537 message sent. 1539 o RECEIVE.TCP: 1540 Pass 1 primitive / event: 'receive'. 1541 Parameters: current_key (optional), rnext_key (optional). 1542 Comments: current_key and rnext_key are authentication parameters 1543 that can be read with this call (see also 1544 CONNECTION.MAINTENANCE.GET_AUTH.TCP). 1546 o RECEIVE.SCTP: 1547 Pass 1 primitive / event: 'DATA ARRIVE' notification, followed by 1548 'Receive' 1549 Parameters: stream number (optional) 1550 Returns: stream sequence number (optional), partial flag 1551 (optional) 1552 Comments: if the 'stream number' is provided, the call to receive 1553 only receives data on one particular stream. If a partial message 1554 arrives, this is indicated by the 'partial flag', and then the 1555 'stream sequence number' must be provided such that an application 1556 can restore the correct order of data blocks that comprise an 1557 entire message. Additionally, a delivery number lets the 1558 application detect reordering. 1560 o RECEIVE.UDP(-Lite): 1562 Pass 1 primitive / event: 'RECEIVE', 1563 Parameters: Buffer for received datagram. 1564 Comments: All CONNECTION.MAINTENANCE.GET_*.UDP(-Lite) primitives 1565 apply per message received. 1567 o SENDFAILURE-EVENT.SCTP: 1568 Pass 1 primitive / event: 'SEND FAILURE' notification, optionally 1569 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 1570 Message' 1571 Returns: cause code; context; unsent or unacknowledged message 1572 (optional) 1573 Comments: 'cause code' indicates the reason of the failure, and 1574 'context' is the context number if such a number has been provided 1575 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 1576 'Receive Unacknowledged Message', respectively. These primitives 1577 can be used to retrieve the unsent or unacknowledged message (or 1578 part of the message, in case a part was delivered) if desired. 1580 o SEND_FAILURE.UDP(-Lite): 1581 Pass 1 primitive / event: 'SEND' 1582 Comments: This may be used to probe for the effective PMTU when 1583 using in combination with the 'MAINTENANCE.SET_DF' primitive. 1585 o SENDER_DRY-EVENT.SCTP: 1586 Pass 1 primitive / event: 'SENDER DRY' notification 1587 Comments: This informs the application that the stack has no more 1588 user data to send. 1590 o PARTIAL_DELIVERY_ABORTED-EVENT.SCTP: 1591 Pass 1 primitive / event: 'PARTIAL DELIVERY ABORTED' notification 1592 Comments: This informs the receiver of a partial message that the 1593 further delivery of the message has been aborted. 1595 5. Pass 3 1597 This section presents the superset of all transport features in all 1598 protocols that were discussed in the preceding sections, based on the 1599 list of primitives in pass 2 but also on text in pass 1 to include 1600 transport features that can be configured in one protocol and are 1601 static properties in another (congestion control, for example). 1602 Again, some minor details are omitted for the sake of generalization 1603 -- e.g., TCP may provide various different IP options, but only 1604 source route is mandatory to implement, and this detail is not 1605 visible in the Pass 3 transport feature "Specify IP Options". 1607 5.1. CONNECTION Related Transport Features 1609 ESTABLISHMENT: 1610 Active creation of a connection from one transport endpoint to one or 1611 more transport endpoints. 1613 o Connect 1614 Protocols: TCP, SCTP, UDP(-Lite) 1616 o Specify which IP Options must always be used 1617 Protocols: TCP, UDP(-Lite) 1619 o Request multiple streams 1620 Protocols: SCTP 1622 o Limit the number of inbound streams 1623 Protocols: SCTP 1625 o Specify number of attempts and/or timeout for the first 1626 establishment message 1627 Protocols: TCP, SCTP 1629 o Obtain multiple sockets 1630 Protocols: SCTP 1632 o Disable MPTCP 1633 Protocols: MPTCP 1635 o Configure authentication 1636 Protocols: TCP, SCTP 1637 Comments: With TCP, this allows to configure Master Key Tuples 1638 (MKTs). In SCTP, this allows to specify which chunk types must 1639 always be authenticated. DATA, ACK etc. are different 'chunks' in 1640 SCTP; one or more chunks may be included in a single packet. 1642 o Indicate an Adaptation Layer (via an adaptation code point) 1643 Protocols: SCTP 1645 o Request to negotiate interleaving of user messages 1646 Protocols: SCTP 1648 o Hand over a message to transfer (possibly multiple times) before 1649 connection establishment 1650 Protocols: TCP 1652 o Hand over a message to transfer during connection establishment 1653 Protocols: SCTP 1655 o Enable UDP encapsulation with a specified remote UDP port number 1656 Protocols: SCTP 1658 AVAILABILITY: 1659 Preparing to receive incoming connection requests. 1661 o Listen, 1 specified local interface 1662 Protocols: TCP, SCTP, UDP(-Lite) 1664 o Listen, N specified local interfaces 1665 Protocols: SCTP 1667 o Listen, all local interfaces 1668 Protocols: TCP, SCTP, UDP(-Lite) 1670 o Obtain requested number of streams 1671 Protocols: SCTP 1673 o Limit the number of inbound streams 1674 Protocols: SCTP 1676 o Specify which IP Options must always be used 1677 Protocols: TCP, UDP(-Lite) 1679 o Disable MPTCP 1680 Protocols: MPTCP 1682 o Configure authentication 1683 Protocols: TCP, SCTP 1684 Comments: With TCP, this allows to configure Master Key Tuples 1685 (MKTs). In SCTP, this allows to specify which chunk types must 1686 always be authenticated. DATA, ACK etc. are different 'chunks' in 1687 SCTP; one or more chunks may be included in a single packet. 1689 o Indicate an Adaptation Layer (via an adaptation code point) 1690 Protocols: SCTP 1692 MAINTENANCE: 1693 Adjustments made to an open connection, or notifications about it. 1695 o Change timeout for aborting connection (using retransmit limit or 1696 time value) 1697 Protocols: TCP, SCTP 1699 o Suggest timeout to the peer 1700 Protocols: TCP 1702 o Disable Nagle algorithm 1703 Protocols: TCP, SCTP 1705 o Request an immediate heartbeat, returning success/failure 1706 Protocols: SCTP 1708 o Notification of Excessive Retransmissions (early warning below 1709 abortion threshold) 1710 Protocols: TCP 1712 o Add path 1713 Protocols: MPTCP, SCTP 1714 MPTCP Parameters: source-IP; source-Port; destination-IP; 1715 destination-Port 1716 SCTP Parameters: local IP address 1718 o Remove path 1719 Protocols: MPTCP, SCTP 1720 MPTCP Parameters: source-IP; source-Port; destination-IP; 1721 destination-Port 1722 SCTP Parameters: local IP address 1724 o Set primary path 1725 Protocols: SCTP 1727 o Suggest primary path to the peer 1728 Protocols: SCTP 1730 o Configure Path Switchover 1731 Protocols: SCTP 1733 o Obtain status (query or notification) 1734 Protocols: SCTP, MPTCP 1735 SCTP parameters: association connection state; destination 1736 transport address list; destination transport address reachability 1737 states; current local and peer receiver window sizes; current 1738 local congestion window sizes; number of unacknowledged DATA 1739 chunks; number of DATA chunks pending receipt; primary path; most 1740 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1741 other destination addresses; MTU per path; interleaving supported 1742 yes/no 1743 MPTCP parameters: subflow-list (identified by source-IP; source- 1744 Port; destination-IP; destination-Port) 1746 o Specify DSCP field 1747 Protocols: TCP, SCTP, UDP(-Lite) 1749 o Notification of ICMP error message arrival 1750 Protocols: TCP, UDP(-Lite) 1752 o Change authentication parameters 1753 Protocols: TCP, SCTP 1755 o Obtain authentication information 1756 Protocols: TCP, SCTP 1758 o Reset Stream 1759 Protocols: SCTP 1761 o Notification of Stream Reset 1762 Protocols: STCP 1764 o Reset Association 1765 Protocols: SCTP 1767 o Notification of Association Reset 1768 Protocols: STCP 1770 o Add Streams 1771 Protocols: SCTP 1773 o Notification of Added Stream 1774 Protocols: STCP 1776 o Choose a scheduler to operate between streams of an association 1777 Protocols: SCTP 1779 o Configure priority or weight for a scheduler 1780 Protocols: SCTP 1782 o Specify IPv6 flow label field 1783 Protocols: SCTP 1785 o Configure send buffer size 1786 Protocols: SCTP 1788 o Configure receive buffer (and rwnd) size 1789 Protocols: SCTP 1791 o Configure message fragmentation 1792 Protocols: SCTP 1794 o Configure PMTUD 1795 Protocols: SCTP 1797 o Configure delayed SACK timer 1798 Protocols: SCTP 1800 o Set Cookie life value 1801 Protocols: SCTP 1803 o Set maximum burst 1804 Protocols: SCTP 1806 o Configure size where messages are broken up for partial delivery 1807 Protocols: SCTP 1809 o Disable checksum when sending 1810 Protocols: UDP 1812 o Disable checksum requirement when receiving 1813 Protocols: UDP 1815 o Specify checksum coverage used by the sender 1816 Protocols: UDP-Lite 1818 o Specify minimum checksum coverage required by receiver 1819 Protocols: UDP-Lite 1821 o Specify DF field 1822 Protocols: UDP(-Lite) 1824 o Get max. transport-message size that may be sent using a non- 1825 fragmented IP packet from the configured interface 1826 Protocols: UDP(-Lite) 1828 o Get max. transport-message size that may be received from the 1829 configured interface 1830 Protocols: UDP(-Lite) 1832 o Specify TTL/Hop count field 1833 Protocols: UDP(-Lite) 1835 o Obtain TTL/Hop count field 1836 Protocols: UDP(-Lite) 1838 o Specify ECN field 1839 Protocols: UDP(-Lite) 1841 o Obtain ECN field 1842 Protocols: UDP(-Lite) 1844 o Specify IP Options 1845 Protocols: UDP(-Lite) 1847 o Obtain IP Options 1848 Protocols: UDP(-Lite) 1850 o Enable and configure "Low Extra Delay Background Transfer" 1851 Protocols: A protocol implementing the LEDBAT congestion control 1852 mechanism 1854 TERMINATION: 1855 Gracefully or forcefully closing a connection, or being informed 1856 about this event happening. 1858 o Close after reliably delivering all remaining data, causing an 1859 event informing the application on the other side 1860 Protocols: TCP, SCTP 1861 Comments: A TCP endpoint locally only closes the connection for 1862 sending; it may still receive data afterwards. 1864 o Abort without delivering remaining data, causing an event 1865 informing the application on the other side 1866 Protocols: TCP, SCTP 1867 Comments: In SCTP a reason can optionally be given by the 1868 application on the aborting side, which can then be received by 1869 the application on the other side. 1871 o Abort without delivering remaining data, not causing an event 1872 informing the application on the other side 1873 Protocols: UDP(-Lite) 1875 o Timeout event when data could not be delivered for too long 1876 Protocols: TCP, SCTP 1877 Comments: the timeout is configured with CONNECTION.MAINTENANCE 1878 "Change timeout for aborting connection (using retransmit limit or 1879 time value)". 1881 5.2. DATA Transfer Related Transport Features 1883 All transport features in this section refer to an existing 1884 connection, i.e. a connection that was either established or made 1885 available for receiving data. Note that TCP allows to transfer data 1886 (a single optional user message, possibly arriving multiple times) 1887 before the connection is fully established. Reliable data transfer 1888 entails delay -- e.g. for the sender to wait until it can transmit 1889 data, or due to retransmission in case of packet loss. 1891 5.2.1. Sending Data 1893 All transport features in this section are provided by DATA.SEND from 1894 pass 2. DATA.SEND is given a data block from the application, which 1895 we here call a "message" if the beginning and end of the data block 1896 can be identified at the receiver, and "data" otherwise. 1898 o Reliably transfer data, with congestion control 1899 Protocols: TCP 1901 o Reliably transfer a message, with congestion control 1902 Protocols: SCTP 1904 o Unreliably transfer a message, with congestion control 1905 Protocols: SCTP 1907 o Unreliably transfer a message, without congestion control 1908 Protocols: UDP(-Lite) 1910 o Configurable Message Reliability 1911 Protocols: SCTP 1913 o Choice of stream 1914 Protocols: SCTP 1916 o Choice of path (destination address) 1917 Protocols: SCTP 1919 o Choice between unordered (potentially faster) or ordered delivery 1920 of messages 1921 Protocols: SCTP 1923 o Request not to bundle messages 1924 Protocols: SCTP 1926 o Specifying a "payload protocol-id" (handed over as such by the 1927 receiver) 1928 Protocols: SCTP 1930 o Specifying a key id to be used to authenticate a message 1931 Protocols: SCTP 1933 o Request not to delay the acknowledgement (SACK) of a message 1934 Protocols: SCTP 1936 5.2.2. Receiving Data 1938 All transport features in this section are provided by DATA.RECEIVE 1939 from pass 2. DATA.RECEIVE fills a buffer provided by the 1940 application, with what we here call a "message" if the beginning and 1941 end of the data block can be identified at the receiver, and "data" 1942 otherwise. 1944 o Receive data (with no message delineation) 1945 Protocols: TCP 1947 o Receive a message 1948 Protocols: SCTP, UDP(-Lite) 1950 o Choice of stream to receive from 1951 Protocols: SCTP 1953 o Information about partial message arrival 1954 Protocols: SCTP 1955 Comments: In SCTP, partial messages are combined with a stream 1956 sequence number so that the application can restore the correct 1957 order of data blocks an entire message consists of. 1959 o Obtain a message delivery number 1960 Protocols: SCTP 1961 Comments: This number can let applications detect and, if desired, 1962 correct reordering. 1964 5.2.3. Errors 1966 This section describes sending failures that are associated with a 1967 specific call to DATA.SEND from pass 2. 1969 o Notification of an unsent (part of a) message 1970 Protocols: SCTP, UDP(-Lite) 1972 o Notification of an unacknowledged (part of a) message 1973 Protocols: SCTP 1975 o Notification that the stack has no more user data to send 1976 Protocols: SCTP 1978 o Notification to a receiver that a partial message delivery has 1979 been aborted 1980 Protocols: SCTP 1982 6. Acknowledgements 1984 The authors would like to thank (in alphabetical order) Bob Briscoe, 1985 David Hayes, Karen Nielsen, Joe Touch and Brian Trammell for 1986 providing valuable feedback on this document. We especially thank 1987 Christoph Paasch for providing input related to Multipath TCP, and 1988 Gorry Fairhurst and Tom Jones for providing input related to UDP(- 1989 Lite). This work has received funding from the European Union's 1990 Horizon 2020 research and innovation programme under grant agreement 1991 No. 644334 (NEAT). The views expressed are solely those of the 1992 author(s). 1994 7. IANA Considerations 1996 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 1998 This memo includes no request to IANA. 2000 8. Security Considerations 2002 Authentication, confidentiality protection, and integrity protection 2003 are identified as transport features [RFC8095]. As currently 2004 deployed in the Internet, these transport features are generally 2005 provided by a protocol or layer on top of the transport protocol; no 2006 current full-featured standards-track transport protocol provides 2007 these transport features on its own. Therefore, these transport 2008 features are not considered in this document, with the exception of 2009 native authentication capabilities of TCP and SCTP for which the 2010 security considerations in [RFC5925] and [RFC4895] apply. 2012 Security considerations for the use of UDP and UDP-Lite are provided 2013 in the referenced RFCs. Security guidance for application usage is 2014 provided in the UDP-Guidelines [RFC8085]. 2016 9. References 2018 9.1. Normative References 2020 [FJ16] Fairhurst, G. and T. Jones, "Features of the User Datagram 2021 Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport 2022 Protocols", Internet-draft draft-ietf-taps-transports- 2023 usage-udp-02, May 2017. 2025 [I-D.ietf-tsvwg-sctp-ndata] 2026 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2027 "Stream Schedulers and User Message Interleaving for the 2028 Stream Control Transmission Protocol", draft-ietf-tsvwg- 2029 sctp-ndata-08 (work in progress), October 2016. 2031 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 2032 DOI 10.17487/RFC0768, August 1980, 2033 . 2035 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2036 RFC 793, DOI 10.17487/RFC0793, September 1981, 2037 . 2039 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2040 Communication Layers", STD 3, RFC 1122, 2041 DOI 10.17487/RFC1122, October 1989, 2042 . 2044 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 2045 Conrad, "Stream Control Transmission Protocol (SCTP) 2046 Partial Reliability Extension", RFC 3758, 2047 DOI 10.17487/RFC3758, May 2004, 2048 . 2050 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 2051 "Authenticated Chunks for the Stream Control Transmission 2052 Protocol (SCTP)", RFC 4895, DOI 10.17487/RFC4895, August 2053 2007, . 2055 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2056 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2057 . 2059 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 2060 Kozuka, "Stream Control Transmission Protocol (SCTP) 2061 Dynamic Address Reconfiguration", RFC 5061, 2062 DOI 10.17487/RFC5061, September 2007, 2063 . 2065 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 2066 RFC 5482, DOI 10.17487/RFC5482, March 2009, 2067 . 2069 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2070 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2071 June 2010, . 2073 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 2074 Iyengar, "Architectural Guidelines for Multipath TCP 2075 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 2076 . 2078 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 2079 Yasevich, "Sockets API Extensions for the Stream Control 2080 Transmission Protocol (SCTP)", RFC 6458, 2081 DOI 10.17487/RFC6458, December 2011, 2082 . 2084 [RFC6525] Stewart, R., Tuexen, M., and P. Lei, "Stream Control 2085 Transmission Protocol (SCTP) Stream Reconfiguration", 2086 RFC 6525, DOI 10.17487/RFC6525, February 2012, 2087 . 2089 [RFC6817] Shalunov, S., Hazel, G., Iyengar, J., and M. Kuehlewind, 2090 "Low Extra Delay Background Transport (LEDBAT)", RFC 6817, 2091 DOI 10.17487/RFC6817, December 2012, 2092 . 2094 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 2095 "TCP Extensions for Multipath Operation with Multiple 2096 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 2097 . 2099 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 2100 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 2101 March 2013, . 2103 [RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream 2104 Control Transmission Protocol (SCTP) Packets for End-Host 2105 to End-Host Communication", RFC 6951, 2106 DOI 10.17487/RFC6951, May 2013, 2107 . 2109 [RFC7053] Tuexen, M., Ruengeler, I., and R. Stewart, "SACK- 2110 IMMEDIATELY Extension for the Stream Control Transmission 2111 Protocol", RFC 7053, DOI 10.17487/RFC7053, November 2013, 2112 . 2114 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2115 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2116 . 2118 [RFC7496] Tuexen, M., Seggelmann, R., Stewart, R., and S. Loreto, 2119 "Additional Policies for the Partially Reliable Stream 2120 Control Transmission Protocol Extension", RFC 7496, 2121 DOI 10.17487/RFC7496, April 2015, 2122 . 2124 [RFC7829] Nishida, Y., Natarajan, P., Caro, A., Amer, P., and K. 2125 Nielsen, "SCTP-PF: A Quick Failover Algorithm for the 2126 Stream Control Transmission Protocol", RFC 7829, 2127 DOI 10.17487/RFC7829, April 2016, 2128 . 2130 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2131 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2132 March 2017, . 2134 9.2. Informative References 2136 [I-D.draft-gjessing-taps-minset] 2137 Gjessing, S. and M. Welzl, "A Minimal Set of Transport 2138 Services for TAPS Systems", Internet-draft draft-gjessing- 2139 taps-minset-04, March 2017. 2141 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 2142 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 2143 1983, . 2145 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2146 Requirement Levels", BCP 14, RFC 2119, 2147 DOI 10.17487/RFC2119, March 1997, 2148 . 2150 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2151 "Definition of the Differentiated Services Field (DS 2152 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2153 DOI 10.17487/RFC2474, December 1998, 2154 . 2156 [RFC2475] Blake, S., Black, D., Carlson, M., Davies, E., Wang, Z., 2157 and W. Weiss, "An Architecture for Differentiated 2158 Services", RFC 2475, DOI 10.17487/RFC2475, December 1998, 2159 . 2161 [RFC3260] Grossman, D., "New Terminology and Clarifications for 2162 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 2163 . 2165 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 2166 DOI 10.17487/RFC5461, February 2009, 2167 . 2169 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 2170 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 2171 January 2011, . 2173 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 2174 Zimmermann, "A Roadmap for Transmission Control Protocol 2175 (TCP) Specification Documents", RFC 7414, 2176 DOI 10.17487/RFC7414, February 2015, 2177 . 2179 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2180 (Diffserv) and Real-Time Communication", RFC 7657, 2181 DOI 10.17487/RFC7657, November 2015, 2182 . 2184 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2185 Ed., "Services Provided by IETF Transport Protocols and 2186 Congestion Control Mechanisms", RFC 8095, 2187 DOI 10.17487/RFC8095, March 2017, 2188 . 2190 Appendix A. Overview of RFCs used as input for pass 1 2192 TCP: [RFC0793], [RFC1122], [RFC5482], [RFC5925], [RFC7413] 2193 MPTCP: [RFC6182], [RFC6824], [RFC6897] 2194 SCTP: RFCs without a socket API specification: [RFC3758], [RFC4895], 2195 [RFC4960], [RFC5061]. 2196 RFCs that include a socket API specification: [RFC6458], 2197 [RFC6525], [RFC6951], [RFC7053], [RFC7496] [RFC7829]. 2198 UDP(-Lite): See [FJ16] 2199 LEDBAT: [RFC6817]. 2201 Appendix B. How this document was developed 2203 This section gives an overview of the method that was used to develop 2204 this document. It was given to contributors for guidance, and it can 2205 be helpful for future updates or extensions. 2207 This document is only concerned with transport features that are 2208 explicitly exposed to applications via primitives. It also strictly 2209 follows RFC text: if a transport feature is truly relevant for an 2210 application, the RFCs should say so, and they should describe how to 2211 use and configure it. Thus, the approach followed for developing 2212 this document was to identify the right RFCs, then analyze and 2213 process their text. 2215 Primitives that MAY be implemented by a transport protocol were 2216 excluded. To be included, the minimum requirement level for a 2217 primitive to be implemented by a protocol was SHOULD. Where 2218 [RFC2119]-style requirements levels are not used, primitives were 2219 excluded when they are described in conjunction with statements like, 2220 e.g.: "some implementations also provide" or "an implementation may 2221 also". Excluded primitives or parameters were briefly described in a 2222 dedicated subsection. 2224 Pass 1: This began by identifying text that talks about primitives. 2225 An API specification, abstract or not, obviously describes primitives 2226 -- but we are not *only* interested in API specifications. The text 2227 describing the 'send' primitive in the API specified in [RFC0793], 2228 for instance, does not say that data transfer is reliable. TCP's 2229 reliability is clear, however, from this text in Section 1 of 2230 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 2231 use as a highly reliable host-to-host protocol between hosts in 2232 packet-switched computer communication networks, and in 2233 interconnected systems of such networks." 2235 Some text for pass 1 subsections was developed copy+pasting all the 2236 relevant text parts from the relevant RFCs, then adjusting 2237 terminology to match the terminology in Section 1 and adjusting 2238 (shortening!) phrasing to match the general style of the document. 2239 An effort was made to formulate everything as a primitive description 2240 such that the primitive descriptions became as complete as possible 2241 (e.g., the "SEND.TCP" primitive in pass 2 is explicitly described as 2242 reliably transferring data); text that is relevant for the primitives 2243 presented in this pass but still does not fit directly under any 2244 primitive was used in a subsection's introduction. 2246 Pass 2: The main goal of this pass is unification of primitives. As 2247 input, only text from pass 1 was used (no exterior sources). The 2248 list in pass 2 is not arranged by protocol ("first protocol X, here 2249 are all the primitives; then protocol Y, here are all the primitives, 2250 ..") but by primitive ("primitive A, implemented this way in protocol 2251 X, this way in protocol Y, ..."). It was a goal to obtain as many 2252 similar pass 2 primitives as possible. For instance, this was 2253 sometimes achieved by not always maintaining a 1:1 mapping between 2254 pass 1 and pass 2 primitives, renaming primitives etc. For every new 2255 primitive, the already existing primitives were considered to try to 2256 make them as coherent as possible. 2258 For each primitive, the following style was used: 2260 o PRIMITIVENAME.PROTOCOL: 2261 Pass 1 primitive / event: 2262 Parameters: 2263 Returns: 2264 Comments: 2266 The entries "Parameters", "Returns" and "Comments" were skipped when 2267 a primitive had no parameters, no described return value or no 2268 comments seemed necessary, respectively. Optional parameters are 2269 followed by "(optional)". When a default value is known, this was 2270 also provided. 2272 Pass 3: the main point of this pass is to identify transport features 2273 that are the result of static properties of protocols, for which all 2274 protocols have to be listed together; this is then the final list of 2275 all available transport features. This list was primarily based on 2276 text from pass 2, with additional input from pass 1 (but no external 2277 sources). 2279 Appendix C. Revision information 2281 XXX RFC-Ed please remove this section prior to publication. 2283 -00 (from draft-welzl-taps-transports): this now covers TCP based on 2284 all TCP RFCs (this means: if you know of something in any TCP RFC 2285 that you think should be addressed, please speak up!) as well as 2286 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 2287 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 2288 in line with [RFC8095]. Addressed comments by Karen Nielsen and 2289 Gorry Fairhurst; various other fixes. Appendices (TCP overview and 2290 how-to-contribute) added. 2292 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 2293 [RFC6897]. 2295 -02: included UDP, UDP-Lite, and all extensions of SCTPs. This 2296 includes fixing the [RFC6458] omission from -00. 2298 -03: wrote security considerations. The "how to contribute" section 2299 was updated to reflect how the document WAS created, not how it 2300 SHOULD BE created; it also no longer wrongly says that Experimental 2301 RFCs are excluded. Included LEDBAT. Changed abstract and intro to 2302 reflect which protocols/mechanisms are covered (TCP, MPTCP, SCTP, 2303 UDP, UDP-Lite, LEDBAT) instead of talking about "transport 2304 protocols". Interleaving and stream scheduling added (draft-ietf- 2305 tsvwg-sctp-ndata). TFO added. "Set protocol parameters" in SCTP 2306 replaced with per-parameter (or parameter group) primitives. More 2307 primitives added, mostly previously overlooked ones from [RFC6458]. 2308 Updated terminology (s/transport service feature/transport feature) 2309 in line with an update of [RFC8095]. Made sequence of transport 2310 features / primitives more logical. Combined MPTCP's add/rem subflow 2311 with SCTP's add/remove local address. 2313 -04: changed UDP's close into an ABORT (to better fit with the 2314 primitives of TCP and SCTP), and incorporated the corresponding 2315 transport feature in step 3 (this addresses a comment from Gorry 2316 Fairhurst). Added TCP Authentication (RFC 5925, section 7.1). 2317 Changed TFO from looking like a primitive in pass 1 to be a part of 2318 'open'. Changed description of SCTP authentication in pass 3 to 2319 encompass both TCP and SCTP. Added citations of [RFC8095] and minset 2321 [I-D.draft-gjessing-taps-minset] to the intro, to give the context of 2322 this document. 2324 -05: minor fix to TCP authentication (comment from Joe Touch), 2325 several fixes from Gorry Fairhurst and Tom Jones. Language fixes; 2326 updated to align with latest taps-transport-usage-udp ID. 2328 Authors' Addresses 2330 Michael Welzl 2331 University of Oslo 2332 PO Box 1080 Blindern 2333 Oslo N-0316 2334 Norway 2336 Email: michawe@ifi.uio.no 2338 Michael Tuexen 2339 Muenster University of Applied Sciences 2340 Stegerwaldstrasse 39 2341 Steinfurt 48565 2342 Germany 2344 Email: tuexen@fh-muenster.de 2346 Naeem Khademi 2347 University of Oslo 2348 PO Box 1080 Blindern 2349 Oslo N-0316 2350 Norway 2352 Email: naeemk@ifi.uio.no