idnits 2.17.1 draft-ietf-taps-transports-usage-03.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 11 instances of lines with non-RFC2606-compliant FQDNs in the document. 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 (March 8, 2017) is 2606 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 830, but not defined == Unused Reference: 'RFC2119' is defined on line 2019, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-taps-transports-usage-udp-00 == Outdated reference: A later version (-13) exists of draft-ietf-tsvwg-sctp-ndata-08 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) ** Obsolete normative reference: RFC 6824 (Obsoleted by RFC 8684) ** Obsolete normative reference: RFC 7053 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 6093 (Obsoleted by RFC 9293) Summary: 4 errors (**), 0 flaws (~~), 7 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: September 9, 2017 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 March 8, 2017 10 On the Usage of Transport Features Provided by IETF Transport Protocols 11 draft-ietf-taps-transports-usage-03 13 Abstract 15 This document describes how TCP, MPTCP, SCTP, UDP and UDP-Lite expose 16 services to applications and how an application can configure and use 17 the transport features that make up these services. It also 18 discusses the service provided by the LEDBAT congestion control 19 mechanism. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 9, 2017. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . . 5 59 3.1.1. Excluded Primitives or Parameters . . . . . . . . . . 8 60 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . . 9 61 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 10 62 3.3.1. Excluded Primitives or Parameters . . . . . . . . . . 17 63 3.4. Primitives Provided by UDP and UDP-Lite . . . . . . . . . 17 64 3.5. The service of LEDBAT . . . . . . . . . . . . . . . . . . 17 65 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 66 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 19 67 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . . 30 68 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 69 5.1. CONNECTION Related Transport Features . . . . . . . . . . 33 70 5.2. DATA Transfer Related Transport Features . . . . . . . . . 39 71 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . . 39 72 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . . 40 73 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . 40 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 41 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 41 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 78 9.1. Normative References . . . . . . . . . . . . . . . . . . . 41 79 9.2. Informative References . . . . . . . . . . . . . . . . . . 44 80 Appendix A. Overview of RFCs used as input for pass 1 . . . . . . 45 81 Appendix B. How this document was developed . . . . . . . . . . . 45 82 Appendix C. Revision information . . . . . . . . . . . . . . . . 47 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47 85 1. Terminology 87 Transport Feature: a specific end-to-end feature that the transport 88 layer provides to an application. Examples include 89 confidentiality, reliable delivery, ordered delivery, message- 90 versus-stream orientation, etc. 91 Transport Service: a set of Transport Features, without an 92 association to any given framing protocol, which provides a 93 complete service to an application. 94 Transport Protocol: an implementation that provides one or more 95 different transport services using a specific framing and header 96 format on the wire. 97 Transport Protocol Component: an implementation of a Transport 98 Feature within a protocol. 99 Transport Service Instance: an arrangement of transport protocols 100 with a selected set of features and configuration parameters that 101 implements a single transport service, e.g., a protocol stack (RTP 102 over UDP). 103 Application: an entity that uses the transport layer for end-to-end 104 delivery of data across the network (this may also be an upper 105 layer protocol or tunnel encapsulation). 106 Endpoint: an entity that communicates with one or more other 107 endpoints using a transport protocol. 108 Connection: shared state of two or more endpoints that persists 109 across messages that are transmitted between these endpoints. 110 Primitive: a function call that is used to locally communicate 111 between an application and a transport endpoint and is related to 112 one or more Transport Features. 113 Parameter: a value passed between an application and a transport 114 protocol by a primitive. 115 Socket: the combination of a destination IP address and a 116 destination port number. 117 Transport Address: the combination of an IP address, transport 118 protocol and the port number used by the transport protocol. 120 2. Introduction 122 This document presents defined interactions between applications and 123 the transport protocols TCP, MPTCP, SCTP, UDP and UDP-Lite as well as 124 the LEDBAT congestion control mechanism in the form of primitives and 125 Transport Features. Primitives can be invoked by an application or a 126 transport protocol; the latter type is called an "event". The list 127 of primitives and Transport Features in this document is strictly 128 based on the parts of protocol specifications that describe what the 129 protocol provides to an application using it and how the application 130 interacts with it. 132 Parts of a protocol that are explicitly stated as optional to 133 implement are not covered. Interactions between the application and 134 a transport protocol that are not directly related to the operation 135 of the protocol are also not covered. For example, [RFC6458] 136 explains how an application can use socket options to indicate its 137 interest in receiving certain notifications. However, for the 138 purpose of identifying primitives and Transport Services, the ability 139 to enable or disable the reception of notifications is irrelevant. 140 Similarly, one-to-many style sockets described in [RFC6458] just 141 affect the application programming style, not how the underlying 142 protocol operates, and they are therefore not discussed here. The 143 same is true for the ability to obtain the unchanged value of a 144 parameter that an application has previously set (this is the case 145 for the "get" in many get/set operations in [RFC6458]). 147 The document presents a three-pass process to arrive at a list of 148 Transport Features. In the first pass, the relevant RFC text is 149 discussed per protocol. In the second pass, this discussion is used 150 to derive a list of primitives that are uniformly categorized across 151 protocols. Here, an attempt is made to present or -- where text 152 describing primitives does not yet exist -- construct primitives in a 153 slightly generalized form to highlight similarities. This is, for 154 example, achieved by renaming primitives of protocols or by avoiding 155 a strict 1:1-mapping between the primitives in the protocol 156 specification and primitives in the list. Finally, the third pass 157 presents Transport Features based on pass 2, identifying which 158 protocols implement them. 160 In the list resulting from the second pass, some Transport Features 161 are missing because they are implicit in some protocols, and they 162 only become explicit when we consider the superset of all features 163 offered by all protocols. For example, TCP always carries out 164 congestion control; we have to consider it together with a protocol 165 like UDP (which does not have congestion control) before we can 166 consider congestion control as a Transport Feature. The complete 167 list of features across all protocols is therefore only available 168 after pass 3. 170 This document discusses unicast transport protocols and a unicast 171 congestion control mechanism. Transport protocols provide 172 communication between processes that operate on network endpoints, 173 which means that they allow for multiplexing of communication between 174 the same IP addresses, and normally this multiplexing is achieved 175 using port numbers. Port multiplexing is therefore assumed to be 176 always provided and not discussed in this document. 178 Some protocols are connection-oriented. Connection-oriented 179 protocols often use an initial call to a specific transport primitive 180 to open a connection before communication can progress, and require 181 communication to be explicitly terminated by issuing another call to 182 a transport primitive (usually called "close"). A "connection" is 183 the common state that some transport primitives refer to, e.g., to 184 adjust general configuration settings. Connection establishment, 185 maintenance and termination are therefore used to categorize 186 transport primitives of connection-oriented transport protocols in 187 pass 2 and pass 3. For this purpose, UDP is assumed to be used with 188 "connected" sockets, i.e. sockets that are bound to a specific pair 189 of addresses and ports [FJ16]. 191 3. Pass 1 193 This first iteration summarizes the relevant text parts of the RFCs 194 describing the protocols, focusing on what each transport protocol 195 provides to the application and how it is used (abstract API 196 descriptions, where they are available). 198 3.1. Primitives Provided by TCP 200 [RFC0793] states: "The Transmission Control Protocol (TCP) is 201 intended for use as a highly reliable host-to-host protocol between 202 hosts in packet-switched computer communication networks, and in 203 interconnected systems of such networks". Section 3.8 in [RFC0793] 204 further specifies the interaction with the application by listing 205 several transport primitives. It is also assumed that an Operating 206 System provides a means for TCP to asynchronously signal the 207 application; the primitives representing such signals are called 208 'events' in this section. This section describes the relevant 209 primitives. 211 open: this is either active or passive, to initiate a connection or 212 listen for incoming connections. All other primitives are 213 associated with a specific connection, which is assumed to first 214 have been opened. An active open call contains a socket. A 215 passive open call with a socket waits for a particular connection; 216 alternatively, a passive open call can leave the socket 217 unspecified to accept any incoming connection. A fully specified 218 passive call can later be made active by calling 'send'. 219 Optionally, a timeout can be specified, after which TCP will abort 220 the connection if data has not been successfully delivered to the 221 destination (else a default timeout value is used). [RFC1122] 222 describes a procedure for aborting the connection that must be 223 used to avoid excessive retransmissions, and states that an 224 application must be able to control the threshold used to 225 determine the condition for aborting -- and that this threshold 226 may be measured in time units or as a count of retransmission. 228 This indicates that the timeout could also be specified as a count 229 of retransmission. 231 Also optional, for multihomed hosts, the local IP address can be 232 provided [RFC1122]. If it is not provided, a default choice will 233 be made in case of active open calls. A passive open call will 234 await incoming connection requests to all local addresses and then 235 maintain usage of the local IP address where the incoming 236 connection request has arrived. Finally, the 'options' parameter 237 is explained in [RFC1122] to allow the application to specify IP 238 options such as source route, record route, or timestamp. It is 239 not stated on which segments of a connection these options should 240 be applied, but probably all segments, as this is also stated in a 241 specification given for the usage of source route (section 4.2.3.8 242 of [RFC1122]). Source route is the only non-optional IP option in 243 this parameter, allowing an application to specify a source route 244 when it actively opens a TCP connection. 246 send: this is the primitive that an application uses to give the 247 local TCP transport endpoint a number of bytes that TCP should 248 reliably send to the other side of the connection. The URGENT 249 flag, if set, states that the data handed over by this send call 250 is urgent and this urgency should be indicated to the receiving 251 process in case the receiving application has not yet consumed all 252 non-urgent data preceding it. An optional timeout parameter can 253 be provided that updates the connection's timeout (see 'open'). 255 receive: This primitive allocates a receiving buffer for a provided 256 number of bytes. It returns the number of received bytes provided 257 in the buffer when these bytes have been received and written into 258 the buffer by TCP. The application is informed of urgent data via 259 an URGENT flag: if it is on, there is urgent data. If it is off, 260 there is no urgent data or this call to 'receive' has returned all 261 the urgent data. 263 close: This primitive closes one side of a connection. It is 264 semantically equivalent to "I have no more data to send" but does 265 not mean "I will not receive any more", as the other side may 266 still have data to send. This call reliably delivers any data 267 that has already been given to TCP (and if that fails, 'close' 268 becomes 'abort'). 270 abort: This primitive causes all pending 'send' and 'receive' calls 271 to be aborted. A TCP RESET message is sent to the TCP endpoint on 272 the other side of the connection [RFC0793]. 274 close event: TCP uses this primitive to inform an application that 275 the application on the other side has called the 'close' 276 primitive, so the local application can also issue a 'close' and 277 terminate the connection gracefully. See [RFC0793], Section 3.5. 279 abort event: When TCP aborts a connection upon receiving a "Reset" 280 from the peer, it "advises the user and goes to the CLOSED state." 281 See [RFC0793], Section 3.4. 283 USER TIMEOUT event: This event, described in Section 3.9 of 284 [RFC0793], is executed when the user timeout expires (see 'open'). 285 All queues are flushed and the application is informed that the 286 connection had to be aborted due to user timeout. 288 ERROR_REPORT event: This event, described in Section 4.2.4.1 of 289 [RFC1122], informs the application of "soft errors" that can be 290 safely ignored [RFC5461], including the arrival of an ICMP error 291 message or excessive retransmissions (reaching a threshold below 292 the threshold where the connection is aborted). 294 Type-of-Service: Section 4.2.4.2 of [RFC1122] states that the 295 application layer MUST be able to specify the Type-of-Service 296 (TOS) for segments that are sent on a connection. The application 297 should be able to change the TOS during the connection lifetime, 298 and the TOS value should be passed to the IP layer unchanged. 299 Since then the TOS field has been redefined. A part of the field 300 has been assigned to ECN [RFC3168] and the six most significant 301 bits have been assigned to carry the DiffServ CodePoint, DSField 302 [RFC3260]. Staying with the intention behind the application's 303 ability to specify the "Type of Service", this should probably be 304 interpreted to mean the value in the DSField, which is the 305 Differentiated Services Codepoint (DSCP). 307 Nagle: The Nagle algorithm, described in Section 4.2.3.4 of 308 [RFC1122], delays sending data for some time to increase the 309 likelihood of sending a full-sized segment. An application can 310 disable the Nagle algorithm for an individual connection. 312 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 313 one end of a TCP connection to advertise its current user timeout 314 value so that the other end of the TCP connection can adapt its 315 own user timeout accordingly. In addition to the configurable 316 value of the User Timeout (see 'send'), [RFC5482] introduces three 317 per-connection state variables that an application can adjust to 318 control the operation of the User Timeout Option (UTO): ADV_UTO is 319 the value of the UTO advertised to the remote TCP peer (default: 320 system-wide default user timeout); ENABLED (default false) is a 321 boolean-type flag that controls whether the UTO option is enabled 322 for a connection. This applies to both sending and receiving. 323 CHANGEABLE is a boolean-type flag (default true) that controls 324 whether the user timeout may be changed based on a UTO option 325 received from the other end of the connection. CHANGEABLE becomes 326 false when an application explicitly sets the user timeout (see 327 'send'). 329 Fast Open: TCP Fast Open (TFO) [RFC7413] allows to immediately hand 330 over a message from the active open to the passive open side of a 331 TCP connection together with the first message establishment 332 packet (the SYN). This can be useful for applications that are 333 sensitive to TCP's connection setup delay. TCP implementations 334 MUST NOT use TFO by default, but only use TFO if requested 335 explicitly by the application on a per-service-port basis. To 336 benefit from TFO, the first application data unit (e.g., an HTTP 337 request) needs to be no more than TCP's maximum segment size 338 (minus options used in the SYN). For the active open side, 339 [RFC7413] recommends changing or replacing the connect() call in 340 order to support a user data buffer argument. For the passive 341 open side, the application needs to enable the reception of Fast 342 Open requests, e.g. via a new TCP_FASTOPEN setsockopt() socket 343 option before listen(). The receiving application must be 344 prepared to accept duplicates of the TFO message, as the first 345 data written to a socket can be delivered more than once to the 346 application on the remote host. 348 3.1.1. Excluded Primitives or Parameters 350 The 'open' primitive specified in [RFC0793] can be handed optional 351 Precedence or security/compartment information according to 352 [RFC0793], but this was not included here because it is mostly 353 irrelevant today, as explained in [RFC7414]. 355 The 'status' primitive was not included because [RFC0793] describes 356 this primitive as "implementation dependent" and states that it 357 "could be excluded without adverse effect". Moreover, while a data 358 block containing specific information is described, it is also stated 359 that not all of this information may always be available. The 'send' 360 primitive described in [RFC0793] includes an optional PUSH flag 361 which, if set, requires data to be promptly transmitted to the 362 receiver without delay; the 'receive' primitive described in 363 [RFC0793] can (under some conditions) yield the status of the PUSH 364 flag. Because PUSH functionality is made optional to implement for 365 both the 'send' and 'receive' primitives in [RFC1122], this 366 functionality is not included here. [RFC1122] also introduces keep- 367 alives to TCP, but these are optional to implement and hence not 368 considered here. [RFC1122] describes that "some TCP implementations 369 have included a FLUSH call", indicating that this call is also 370 optional to implement. It is therefore not considered here. 372 3.2. Primitives Provided by MPTCP 374 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 375 multiple paths for a single data-stream. It achieves this by 376 creating different so-called TCP subflows for each of the interfaces 377 and scheduling the traffic across these TCP subflows. The service 378 provided by MPTCP is described in [RFC6182] "Multipath TCP MUST 379 follow the same service model as TCP [RFC0793]: in- order, reliable, 380 and byte-oriented delivery. Furthermore, a Multipath TCP connection 381 SHOULD provide the application with no worse throughput or resilience 382 than it would expect from running a single TCP connection over any 383 one of its available paths." 385 Further, [RFC6182] states constraints on the API exposed by MPTCP: "A 386 multipath-capable equivalent of TCP MUST retain some level of 387 backward compatibility with existing TCP APIs, so that existing 388 applications can use the newer merely by upgrading the operating 389 systems of the end hosts." As such, the primitives provided by MPTCP 390 are equivalent to the ones provided by TCP. Nevertheless, [RFC6824] 391 and [RFC6897] clarify some parts of TCP's primitives with respect to 392 MPTCP and add some extensions for better control on MPTCP's subflows. 393 Hereafter is a list of the clarifications and extensions the above 394 cited RFCs provide to TCP's primitives. 396 open: [RFC6897] states "An application should be able to request to 397 turn on or turn off the usage of MPTCP.". The RFC states that 398 this functionality can be provided through a socket-option called 399 TCP_MULTIPATH_ENABLE. Further, [RFC6897] says that MPTCP must be 400 disabled in case the application is binding to a specific address. 402 send/receive: [RFC6824] states that the sending and receiving of 403 data does not require any changes to the application when MPTCP is 404 being used. The MPTCP-layer will "take one input data stream from 405 an application, and split it into one or more subflows, with 406 sufficient control information to allow it to be reassembled and 407 delivered reliably and in order to the recipient application." 408 The use of the Urgent-Pointer is special in MPTCP and [RFC6824] 409 says "a TCP subflow MUST NOT use the Urgent Pointer to interrupt 410 an existing mapping." 412 address and subflow management: MPTCP uses different addresses and 413 allows a host to announce these addresses as part of the protocol. 414 [RFC6897] says "An application should be able to restrict MPTCP to 415 binding to a given set of addresses." and thus allows applications 416 to limit the set of addresses that are being used by MPTCP. 418 Further, "An application should be able to obtain information on 419 the pairs of addresses used by the MPTCP subflows.". 421 3.3. Primitives Provided by SCTP 423 Section 1.1 of [RFC4960] lists limitations of TCP that SCTP removes. 424 Three of the four mentioned limitations directly translate into 425 Transport Features that are visible to an application using SCTP: 1) 426 it allows for preservation of message delineations; 2) these 427 messages, while reliably transferred, do not require to be in order 428 unless the application wants it; 3) multi-homing is supported. In 429 SCTP, connections are called "associations" and they can be between 430 not only two (as in TCP) but multiple addresses at each endpoint. 432 Section 10 of [RFC4960] further specifies the interaction with the 433 application (which RFC [RFC4960] calls the "Upper Layer Protocol" 434 (ULP)). It is assumed that the Operating System provides a means for 435 SCTP to asynchronously signal the application; the primitives 436 representing such signals are called 'events' in this section. Here, 437 we describe the relevant primitives. In addition to the abstract API 438 described in Section 10 of [RFC4960], an extension to the socket API 439 is described in [RFC6458], covering the functionality of the base 440 protocol specified in [RFC4960] and its extensions specified in 441 [RFC3758], [RFC4895], and [RFC5061]. For the protocol extensions 442 specified in [RFC6525], [RFC6951], [RFC7053], [RFC7496], [RFC7829] 443 and [I-D.ietf-tsvwg-sctp-ndata], the corresponding extensions of the 444 socket API are specified in these protocol specifications. The 445 functionality exposed to the ULP through this socket API is 446 considered here in addition to the abstract API specified in Section 447 10 of [RFC4960]. 449 [RFC4960] contains a "SETPROTOCOLPARAMETERS" primitive that allows to 450 adjust elements of a parameter list; it is stated that SCTP 451 implementations "may allow ULP to customize some of these protocol 452 parameters", indicating that none of the elements of this parameter 453 list are mandatory to make ULP-configurable. Thus, we only consider 454 the parameters in [RFC4960] that are also covered in one of the other 455 RFCs listed above, which leads us to exclude the parameters 456 RTO.Alpha, RTO.Beta and HB.Max.Burst. For clarity, we also replace 457 "SETPROTOCOLPARAMETERS" itself with primitives that adjust parameters 458 or groups of parameters which fit together. 460 Initialize: Initialize, described in [RFC4960], creates a local SCTP 461 instance that it binds to a set of local addresses (and, if 462 provided, port number). Initialize needs to be called only once 463 per set of local addresses. [RFC6458] also describes a number of 464 per-association initialization parameters that can be used when an 465 association is created, but before it is connected (via the 466 primitive 'Associate' below): the maximum number of inbound 467 streams the application is prepared to support, the maximum number 468 of attempts to be made when sending the INIT (the first message of 469 association establishment), and the maximum retransmission timeout 470 (RTO) value to use when attempting an INIT. At this point, before 471 connecting, an application can also enable UDP encapsulation by 472 configuring the remote UDP encapsulation port number [RFC6951]. 474 Associate: This creates an association (the SCTP equivalent of a 475 connection) that connects the local SCTP instance and a remote 476 SCTP instance. To identify the remote endpoint, it can be given 477 one or multiple (using connectx as described in section 9.9 of 478 [RFC6458]) sockets. Most primitives are associated with a 479 specific association, which is assumed to first have been created. 480 Associate can return a list of destination transport addresses so 481 that multiple paths can later be used. One of the returned 482 sockets will be selected by the local endpoint as default primary 483 path for sending SCTP packets to this peer, but this choice can be 484 changed by the application using the list of destination 485 addresses. Associate is also given the number of outgoing streams 486 to request and optionally returns the number of negotiated 487 outgoing streams. An optional parameter of 32 bits, the 488 adaptation layer indication, can be provided, as specified in 489 [RFC5061]. If the extension specified in [RFC4895] is used, the 490 chunk types required to be sent authenticated by the peer can be 491 provided. [RFC6458] describes a 'SCTP_CANT_STR_ASSOC' 492 notification that is used to inform the application of a failure 493 to create an association. [RFC6458] describes how an application 494 could use sendto() or sendmsg() to implicitly setup an 495 association, thereby handing over a message that SCTP might send 496 during the association setup phase. Note that this mechanism is 497 different from TCP's TFO mechanism: the message would arrive only 498 once, after at least one RTT, as it is sent together with the 499 third message exchanged during association setup, the COOKIE-ECHO 500 chunk). 502 Send: This sends a message of a certain length in bytes over an 503 association. A number can be provided to later refer to the 504 correct message when reporting an error, and a stream id is 505 provided to specify the stream to be used inside an association 506 (we consider this as a mandatory parameter here for simplicity: if 507 not provided, the stream id defaults to 0). A condition to 508 abandon the message can be specified (for example limiting the 509 number of retransmissions or the lifetime of the user message). 510 This allows to control the partial reliability extension specified 511 in [RFC3758] and [RFC7496]. An optional maximum life time can 512 specify the time after which the message should be discarded 513 rather than sent. A choice (advisory, i.e. not guaranteed) of the 514 preferred path can be made by providing a socket, and the message 515 can be delivered out-of-order if the unordered flag is set. An 516 advisory flag indicates that the peer should not delay the 517 acknowledgement of the user message provided by making use of the 518 I-bit specified in [RFC7053]. Another advisory flag indicates 519 whether the application prefers to avoid bundling user data with 520 other outbound DATA chunks (i.e., in the same packet). A payload 521 protocol-id can be provided to pass a value that indicates the 522 type of payload protocol data to the peer. If the extension 523 specified in [RFC4895] is used, the key identifier used for 524 authenticating the DATA chunks can be provided. 526 Receive: Messages are received from an association, and optionally a 527 stream within the association, with their size returned. The 528 application is notified of the availability of data via a DATA 529 ARRIVE notification. If the sender has included a payload 530 protocol-id, this value is also returned. If the received message 531 is only a partial delivery of a whole message, a partial flag will 532 indicate so, in which case the stream id and a stream sequence 533 number are provided to the application. A delivery number lets 534 the application detect reordering. 536 Shutdown: This primitive gracefully closes an association, reliably 537 delivering any data that has already been handed over to SCTP. A 538 parameter lets the application control whether further receive or 539 send operations or both are disabled when the call is issued. A 540 return code informs about success or failure of this procedure. 542 Abort: This ungracefully closes an association, by discarding any 543 locally queued data and informing the peer that the association 544 was aborted. Optionally, an abort reason to be passed to the peer 545 may be provided by the application. A return code informs about 546 success or failure of this procedure. 548 Change Heartbeat / Request Heartbeat: This allows the application to 549 enable/disable heartbeats and optionally specify a heartbeat 550 frequency as well as requesting a single heartbeat to be carried 551 out upon a function call, with a notification about success or 552 failure of transmitting the HEARTBEAT chunk to the destination. 554 Configure Max. Retransmissions of an Association: The parameter 555 Association.Max.Retrans in [RFC4960], called sasoc_maxrxt in 556 [RFC6458], allows to configure the number of unsuccessful 557 retransmissions after which an entire association is considered as 558 failed (which should invoke a COMMUNICATION LOST notification). 560 Set Primary: This allows to set a new primary default path for an 561 association by providing a socket. Optionally, a default source 562 address to be used in IP datagrams can be provided. 564 Change Local Address / Set Peer Primary: This allows an endpoint to 565 add/remove local addresses to/from an association. In addition, 566 the peer can be given a hint which address to use as the primary 567 address. This is provided by the protocol extension defined in 568 [RFC5061]. 570 Configure Path Switchover: [RFC4960] contains a primitive called SET 571 FAILURE THRESHOLD. This configures the parameter 572 "Path.Max.Retrans", which determines after how many 573 retransmissions a particular transport address is considered as 574 unreachable. If there are more transport addresses available in 575 an association, reaching this limit will invoke a path switchover. 576 [RFC7829] extends this method with a concept of "Potentially 577 Failed" (PF) paths. When a path is in PF state, SCTP will not 578 entirely give up sending on that path, but it will preferably send 579 data on other active paths if such paths are available. Entering 580 the PF state is done upon exceeding a configured maximum number of 581 retransmissions. Thus, for all paths where this mechanism is 582 used, there are two configurable error thresholds: one to decide 583 that a path is in PF state, and one to decide that the transport 584 address is unreachable. 586 Set / Get Authentication Parameters: This allows an endpoint to add/ 587 remove key material to/from an association. In addition, the 588 chunk types being authenticated can be queried. This is provided 589 by the protocol extension defined in [RFC4895]. 591 Add / Reset Streams, Reset Association: This allows an endpoint to 592 add streams to an existing association or or to reset them 593 individually. Additionally, the association can be reset. This 594 is provided by the protocol extension defined in [RFC6525]. 596 Status: The 'Status' primitive returns a data block with information 597 about a specified association, containing: association connection 598 state; destination transport address list; destination transport 599 address reachability states; current local and peer receiver 600 window sizes; current local congestion window sizes; number of 601 unacknowledged DATA chunks; number of DATA chunks pending receipt; 602 primary path; most recent SRTT on primary path; RTO on primary 603 path; SRTT and RTO on other destination addresses [RFC4960] and 604 MTU per path [RFC6458]. 606 Enable / Disable Interleaving: This allows to enable or disable the 607 negotiation of user message interleaving support for future 608 associations. For existing associations it is possible to query 609 whether user message interleaving support was negotiated or not on 610 a particular association [I-D.ietf-tsvwg-sctp-ndata]. 612 Set Stream Scheduler: This allows to select a stream scheduler per 613 association, with a choice of: First Come First Serve, Round 614 Robin, Round Robin per Packet, Priority Based, Fair Bandwidth, 615 Weighted Fair Queuing. How these schedulers operate is described 616 in detail in [I-D.ietf-tsvwg-sctp-ndata]. 618 Configure Stream Scheduler: This allows to change a parameter per 619 stream for the schedulers: a priority value for the Priority Based 620 scheduler and a weight for the Weighted Fair Queuing scheduler. 622 Enable/disable NODELAY: This turns on/off any Nagle-like algorithm 623 for an association [RFC6458]. 625 Configure send buffer size: This controls the amount of data SCTP 626 may have waiting in internal buffers to be sent or retransmitted 627 [RFC6458]. 629 Configure receive buffer size: This sets the receive buffer size in 630 octets, thereby controlling the receiver window for an association 631 [RFC6458]. 633 Configure message fragmentation: If a user message causes an SCTP 634 packet to exceed the maximum fragmentation size (which can be 635 provided by the application, and is otherwise the PMTU size), then 636 the message will be fragmented by SCTP. Disabling message 637 fragmentation will produce an error instead of fragmenting the 638 message [RFC6458]. 640 Configure Path MTU Discovery: Section 8.1.12 of [RFC6458] explains 641 how Path MTU Discovery can be enabled or disabled per peer address 642 of an association. When it is enabled, the current Path MTU value 643 can be obtained. When it is disabled, the Path MTU to be used can 644 be controlled by the application. 646 Configure delayed SACK timer: The time before sending a SACK can be 647 adjusted; delaying SACKs can be disabled; the number of packets 648 that must be received before a SACK is sent without waiting for 649 the delay timer to expire can be configured [RFC6458]. 651 Set Cookie life value: The Cookie life value can be adjusted as 652 explained in Section 8.1.2 of [RFC6458]. "Valid.Cookie.Life" is 653 also one of the parameters listed as potentially adjustable with 654 SETPROTOCOLPARAMETERS in [RFC4960]. 656 Set maximum burst: The maximum burst of packets that can be emitted 657 by a particular association (default 4, and values above 4 are 658 optional to implement) can be adjusted as explained in Section 659 8.1.2 of [RFC6458]. "Max.Burst" is also one of the parameters 660 listed as potentially adjustable with SETPROTOCOLPARAMETERS in 661 [RFC4960]. 663 Configure RTO calculation: [RFC4960] lists the following adjustable 664 parameters: RTO.Initial; RTO.Min; RTO.Max; RTO.Alpha; RTO.Beta. 665 Only the initial, minimum and maximum RTO are also described as 666 configurable [RFC6458]. 668 Set DSCP value: Section 8.1.12 of [RFC6458] explains how to set the 669 DSCP value per peer address of an association. 671 Set IPv6 flow label: Section 8.1.12 of [RFC6458] explains how to set 672 the flow label field per peer address of an association. 674 Set Partial Delivery Point: This allows to specify the size of a 675 message where partial delivery will be invoked. Setting this to a 676 lower value will cause partial deliveries to happen more often 677 [RFC6458]. 679 COMMUNICATION UP notification: When a lost communication to an 680 endpoint is restored or when SCTP becomes ready to send or receive 681 user messages, this notification informs the application process 682 about the affected association, the type of event that has 683 occurred, the complete set of sockets of the peer, the maximum 684 number of allowed streams and the inbound stream count (the number 685 of streams the peer endpoint has requested). If interleaving is 686 supported by both endpoints, this information is also included in 687 this notification. 689 RESTART notification: When SCTP has detected that the peer has 690 restarted, this notification is passed to the upper layer 691 [RFC6458]. 693 DATA ARRIVE notification: When a message is ready to be retrieved 694 via the Receive primitive, the application is informed by this 695 notification. 697 SEND FAILURE notification / Receive Unsent Message / Receive 698 Unacknowledged Message: When a message cannot be delivered via an 699 association, the sender can be informed about it and learn whether 700 the message has just not been acknowledged or (e.g. in case of 701 lifetime expiry) if it has not even been sent. This can also 702 inform the sender that a part of the message has been successfully 703 delivered. 705 NETWORK STATUS CHANGE notification: The NETWORK STATUS CHANGE 706 notification informs the application about a socket becoming 707 active/inactive [RFC4960] or "Potentially Failed" [RFC7829]. 709 COMMUNICATION LOST notification: When SCTP loses communication to an 710 endpoint (e.g. via Heartbeats or excessive retransmission) or 711 detects an abort, this notification informs the application 712 process of the affected association and the type of event (failure 713 OR termination in response to a shutdown or abort request). 715 SHUTDOWN COMPLETE notification: When SCTP completes the shutdown 716 procedures, this notification is passed to the upper layer, 717 informing it about the affected assocation. 719 AUTHENTICATION notification: When SCTP wants to notify the upper 720 layer regarding the key management related to the extension 721 defined in [RFC4895], this notification is passed to the upper 722 layer. 724 ADAPTATION LAYER INDICATION notification: When SCTP completes the 725 association setup and the peer provided an adaptation layer 726 indication, this is passed to the upper layer. This extension is 727 defined in [RFC5061] and [RFC6458]. 729 STREAM RESET notification: When SCTP completes the procedure for 730 resetting streams as specified in [RFC6525], this notification is 731 passed to the upper layer, informing it about the result. 733 ASSOCIATION RESET notification: When SCTP completes the association 734 reset procedure as specified in [RFC6525], this notification is 735 passed to the upper layer, informing it about the result. 737 STREAM CHANGE notification: When SCTP completes the procedure used 738 to increase the number of streams as specified in [RFC6525], this 739 notification is passed to the upper layer, informing it about the 740 result. 742 SENDER DRY notification: When SCTP has no more user data to send or 743 retransmit on a particular association, this notification is 744 passed to the upper layer [RFC6458]. 746 PARTIAL DELIVERY ABORTED notification: When a receiver has begun to 747 receive parts of a user message but the delivery of this message 748 is then aborted, this notification is passed to the upper layer 749 (section 6.1.7 of [RFC6458]). 751 3.3.1. Excluded Primitives or Parameters 753 The 'Receive' primitive can return certain additional information, 754 but this is optional to implement and therefore not considered. With 755 a COMMUNICATION LOST notification, some more information may 756 optionally be passed to the application (e.g., identification to 757 retrieve unsent and unacknowledged data). SCTP "can invoke" a 758 COMMUNICATION ERROR notification and "may send" a RESTART 759 notification, making these two notifications optional to implement. 760 The list provided under 'Status' includes "etc", indicating that more 761 information could be provided. The primitive 'Get SRTT Report' 762 returns information that is included in the information that 'Status' 763 provides and is therefore not discussed. The 'Destroy SCTP Instance' 764 API function was excluded: it erases the SCTP instance that was 765 created by 'Initialize', but is not a Primitive as defined in this 766 document because it does not relate to a Transport Feature. The 767 SHUTDOWN EVENT described in Section 6.1 of [RFC6458] informs an 768 application that the peer has sent a SHUTDOWN, and hence no further 769 data should be sent on this socket. However, if an application would 770 try to send data on the socket, it would get an error message anyway; 771 thus, this event is classified as "just affecting the application 772 programming style, not how the underlying protocol operates" and not 773 included here. 775 3.4. Primitives Provided by UDP and UDP-Lite 777 The primitives provided by UDP and UDP-Lite are described in [FJ16]. 779 3.5. The service of LEDBAT 781 The service of the Low Extra Delay Background Transport (LEDBAT) 782 congestion control mechanism is described in the abstract of 783 [RFC6817] as follows: "LEDBAT is designed for use by background bulk- 784 transfer applications to be no more aggressive than standard TCP 785 congestion control (as specified in RFC 5681) and to yield in the 786 presence of competing flows, thus limiting interference with the 787 network performance of competing flows." 788 LEDBAT does not have any primitives, as LEDBAT is not a transport 789 protocol. [RFC6817] states: "LEDBAT can be used as part of a 790 transport protocol or as part of an application, as long as the data 791 transmission mechanisms are capable of carrying timestamps and 792 acknowledging data frequently. LEDBAT can be used with TCP, Stream 793 Control Transmission Protocol (SCTP), and Datagram Congestion Control 794 Protocol (DCCP), with appropriate extensions where necessary; and it 795 can be used with proprietary application protocols, such as those 796 built on top of UDP for peer-to- peer (P2P) applications." At the 797 time of writing, the appropriate extensions for TCP, SCTP or DCCP do 798 not exist. 800 A numer of configurable parameters exist in the LEDBAT specification: 801 TARGET, which is the queuing delay target at which LEDBAT tries to 802 operate, must be set to 100ms or less. ALLOWED_INCREASE (should be 803 1, must be greater than 0) limits the speed at which LEDBAT increases 804 its rate. GAIN, which MUST be set to 1 or less to avoid a faster 805 ramp-up than TCP Reno, determines how quickly the sender responds to 806 changes in queueing delay. Implementations may divide GAIN into two 807 parameters, one for increase and a possibly larger one for decrease. 808 We call these parameters GAIN_INC and GAIN_DEC here. BASE_HISTORY is 809 the size of the list of measured base delays, and SHOULD be 10. This 810 list can be filtered using a FILTER() function which is not 811 prescribed in [RFC6817], yielding a list of size CURRENT_FILTER. The 812 initial and minimum congestion windows, INIT_CWND and MIN_CWND, 813 should both be 2. 815 Regarding which of these parameters should be under control of an 816 application, the possible range goes from exposing nothing on the one 817 hand, to considering everything that is not fully prescribed with a 818 MUST in [RFC6817] as a parameter on the other hand. Function 819 implementations are not provided as a parameter to any of the 820 transport protocols discussed here, and hence we do not regard the 821 FILTER() function as a parameter. However, to avoid unnecessarily 822 limiting future implementations, we consider all other parameters 823 above as tunable parameters that a TAPS system should expose. 825 4. Pass 2 827 This pass categorizes the primitives from pass 1 based on whether 828 they relate to a connection or to data transmission. Primitives are 829 presented following the nomenclature 830 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 831 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 832 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 833 considered. The DATA category does not have any SUBCATEGORY. The 834 PROTOCOL name "UDP(-Lite)" is used when primitives are equivalent for 835 UDP and UDP-Lite; the PROTOCOL name "TCP" refers to both TCP and 836 MPTCP. We present "connection" as a general protocol-independent 837 concept and use it to refer to, e.g., TCP connections (identifiable 838 by a unique pair of IP addresses and TCP port numbers), SCTP 839 associations (identifiable by multiple IP address and port number 840 pairs), as well UDP and UDP-Lite connections (identifiable by a 841 unique socket pair). 843 Some minor details are omitted for the sake of generalization -- 844 e.g., SCTP's 'close' [RFC4960] returns success or failure, and lets 845 the application control whether further receive or send operations or 846 both are disabled [RFC6458]. This is not described in the same way 847 for TCP in [RFC0793], but these details play no significant role for 848 the primitives provided by either TCP or SCTP (for the sake of being 849 generic, it could be assumed that both receive and send operations 850 are disabled in both cases). 852 The TCP 'send' and 'receive' primitives include usage of an "URGENT" 853 mechanism. This mechanism is required to implement the "synch 854 signal" used by telnet [RFC0854], but SHOULD NOT be used by new 855 applications [RFC6093]. Because pass 2 is meant as a basis for the 856 creation of TAPS systems, the "URGENT" mechanism is excluded. This 857 also concerns the notification "Urgent pointer advance" in the 858 ERROR_REPORT described in Section 4.2.4.1 of [RFC1122]. 860 Since LEDBAT is a congestion control mechanism and not a protocol, it 861 is not currently defined when to enable / disable or configure the 862 mechanism. For instance, it could be a one-time choice upon 863 connection establishment or when listening for incoming connections, 864 in which case it should be categorized under CONNECTION.ESTABLISHMENT 865 or CONNECTION.AVAILABILITY, respectively. To avoid unnecessarily 866 limiting future implementations, it was decided to place it under 867 CONNECTION.MAINTENANCE, with all parameters that are described in 868 [RFC6817] made configurable. 870 4.1. CONNECTION Related Primitives 872 ESTABLISHMENT: 873 Active creation of a connection from one transport endpoint to one or 874 more transport endpoints. 875 Interfaces to UDP and UDP-Lite allow both connection-oriented and 876 connection-less usage of the API . [RFC8085] 878 o CONNECT.TCP: 879 Pass 1 primitive / event: 'open' (active) or 'open' (passive) with 880 socket, followed by 'send' 881 Parameters: 1 local IP address (optional); 1 destination transport 882 address (for active open; else the socket and the local IP address 883 of the succeeding incoming connection request will be maintained); 884 timeout (optional); options (optional); user message (optional) 885 Comments: If the local IP address is not provided, a default 886 choice will automatically be made. The timeout can also be a 887 retransmission count. The options are IP options to be used on 888 all segments of the connection. At least the Source Route option 889 is mandatory for TCP to provide. The user message may be 890 transmitted to the peer application immediately upon reception of 891 the TCP SYN packet. To benefit from the lower latency this 892 provides as part of the experimental TFO mechanism, its length 893 must be at most the TCP's maximum segment size (minus TCP options 894 used in the SYN). The message may also be delivered more than 895 once to the application on the remote host. 897 o CONNECT.SCTP: 898 Pass 1 primitive / event: 'initialize', followed by 'enable / 899 disable interleaving' (optional), followed by 'associate' 900 Parameters: list of local SCTP port number / IP address pairs 901 (initialize); one or several sockets (identifying the peer); 902 outbound stream count; maximum allowed inbound stream count; 903 adaptation layer indication (optional); chunk types required to be 904 authenticated (optional); request interleaving on/off; maximum 905 number of INIT attemps (optional); maximum init. RTO for INIT 906 (optional); user message (optional); remote UDP port number 907 (optional) 908 Returns: socket list or failure 909 Comments: 'initialize' needs to be called only once per list of 910 local SCTP port number / IP address pairs. One socket will 911 automatically be chosen; it can later be changed in MAINTENANCE. 912 The user message may be transmitted to the peer application 913 immediately upon reception of the packet containing the COOKIE- 914 ECHO chunk. To benefit from the lower latency this provides, its 915 length must be limited such that it fits into the packet 916 containing the COOKIE-ECHO chunk. If a remote UDP port number is 917 provided, SCTP packets will be encapsulated in UDP. 919 o CONNECT.MPTCP: 920 This is similar to CONNECT.TCP except for one additional boolean 921 parameter that allows to enable or disable MPTCP for a particular 922 connection or socket (default: enabled). 924 o CONNECT.UDP(-Lite): 925 Pass 1 primitive / event: 'connect' followed by 'send'. 926 Parameters: 1 local IP address (default (ANY), or specified); 1 927 destination transport address; 1 local port (default (OS chooses), 928 or specified); 1 destination port (default (OS chooses), or 929 specified). 930 Comments: Associates a transport address creating a UDP(-Lite) 931 socket connection. This can be called again with a new transport 932 address to create a new connection. The CONNECT function allows 933 an application to receive errors from messages sent to a transport 934 address. 936 AVAILABILITY: 937 Preparing to receive incoming connection requests. 939 o LISTEN.TCP: 940 Pass 1 primitive / event: 'open' (passive) 941 Parameters: 1 local IP address (optional); 1 socket (optional); 942 timeout (optional); buffer to receive a user message (optional) 943 Comments: if the socket and/or local IP address is provided, this 944 waits for incoming connections from only and/or to only the 945 provided address. Else this waits for incoming connections 946 without this / these constraint(s). ESTABLISHMENT can later be 947 performed with 'send'. If a buffer is provided to receive a user 948 message, a user message can be received from a TFO-enabled sender 949 before TCP's connection handshake is completed. This message may 950 arrive multiple times. 952 o LISTEN.SCTP: 953 Pass 1 primitive / event: 'initialize', followed by 'COMMUNICATION 954 UP' or 'RESTART' notification and possibly 'ADAPTATION LAYER' 955 notification 956 Parameters: list of local SCTP port number / IP address pairs 957 (initialize) 958 Returns: socket list; outbound stream count; inbound stream count; 959 adaptation layer indication; chunks required to be authenticated; 960 interleaving supported on both sides yes/no 961 Comments: initialize needs to be called only once per list of 962 local SCTP port number / IP address pairs. COMMUNICATION UP can 963 also follow a COMMUNICATION LOST notification, indicating that the 964 lost communication is restored. If the peer has provided an 965 adaptation layer indication, an 'ADAPTATION LAYER' notification is 966 issued. 968 o LISTEN.MPTCP: 969 This is similar to LISTEN.TCP except for one additional boolean 970 parameter that allows to enable or disable MPTCP for a particular 971 connection or socket (default: enabled). 973 o LISTEN.UDP(-Lite): 974 Pass 1 primitive / event: 'receive'. 975 Parameters: 1 local IP address (default (ANY), or specified); 1 976 destination transport address; local port (default (OS chooses), 977 or specified); destination port (default (OS chooses), or 978 specified). 979 Comments: The receive function registers the application to listen 980 for incoming UDP(-Lite) datagrams at an endpoint. 982 MAINTENANCE: 983 Adjustments made to an open connection, or notifications about it. 984 These are out-of-band messages to the protocol that can be issued at 985 any time, at least after a connection has been established and before 986 it has been terminated (with one exception: CHANGE_TIMEOUT.TCP can 987 only be issued for an open connection when DATA.SEND.TCP is called). 988 In some cases, these primitives can also be immediately issued during 989 ESTABLISHMENT or AVAILABILITY, without waiting for the connection to 990 be opened (e.g. CHANGE_TIMEOUT.TCP can be done using TCP's 'open' 991 primitive). For UDP and UDP-Lite, these functions may establish a 992 setting per connection, but may also be changed per datagram message. 994 o CHANGE_TIMEOUT.TCP: 995 Pass 1 primitive / event: 'open' or 'send' combined with 996 unspecified control of per-connection state variables 997 Parameters: timeout value (optional); ADV_UTO (optional); boolean 998 UTO_ENABLED (optional, default false); boolean CHANGEABLE 999 (optional, default true) 1000 Comments: when sending data, an application can adjust the 1001 connection's timeout value (time after which the connection will 1002 be aborted if data could not be delivered). If UTO_ENABLED is 1003 true, the user timeout value (or, if provided, the value ADV_UTO) 1004 will be advertised for the TCP on the other side of the connection 1005 to adapt its own user timeout accordingly. UTO_ENABLED controls 1006 whether the UTO option is enabled for a connection. This applies 1007 to both sending and receiving. CHANGEABLE controls whether the 1008 user timeout may be changed based on a UTO option received from 1009 the other end of the connection; it becomes false when 'timeout 1010 value' is used. 1012 o CHANGE_TIMEOUT.SCTP: 1013 Pass 1 primitive / event: 'Change HeartBeat' combined with 1014 'Configure Max. Retransmissions of an Association' 1015 Parameters: 'Change HeartBeat': heartbeat frequency; 'Configure 1016 Max. Retransmissions of an Association': Association.Max.Retrans 1017 Comments: Change Heartbeat can enable / disable heartbeats in SCTP 1018 as well as change their frequency. The parameter 1019 Association.Max.Retrans defines after how many unsuccessful 1020 transmissions of any packets (including heartbeats) the 1021 association will be terminated; thus these two primitives / 1022 parameters together can yield a similar behavior for SCTP 1023 associations as CHANGE_TIMEOUT.TCP does for TCP connections. 1025 o DISABLE_NAGLE.TCP: 1026 Pass 1 primitive / event: not specified 1027 Parameters: one boolean value 1028 Comments: the Nagle algorithm delays data transmission to increase 1029 the chance to send a full-sized segment. An application must be 1030 able to disable this algorithm for a connection. 1032 o DISABLE_NAGLE.SCTP: 1033 Pass 1 primitive / event: 'Enable/disable NODELAY' 1034 Parameters: one boolean value 1035 Comments: Nagle-like algorithms delay data transmission to 1036 increase the chance to send a full-sized packet. 1038 o REQUEST_HEARTBEAT.SCTP: 1039 Pass 1 primitive / event: 'Request HeartBeat' 1040 Parameters: socket 1041 Returns: success or failure 1042 Comments: requests an immediate heartbeat on a path, returning 1043 success or failure. 1045 o ADD_PATH.MPTCP: 1046 Pass 1 primitive / event: not specified 1047 Parameters: local IP address and optionally the local port number 1048 Comments: the application specifies the local IP address and port 1049 number that must be used for a new subflow. 1051 o ADD_PATH.SCTP: 1052 Pass 1 primitive / event: Change Local Address / Set Peer Primary 1053 Parameters: local IP address 1055 o REM_PATH.MPTCP: 1056 Pass 1 primitive / event: not specified 1057 Parameters: local IP address, local port number, remote IP 1058 address, remote port number 1059 Comments: the application removes the subflow specified by the IP/ 1060 port-pair. The MPTCP implementation must trigger a removal of the 1061 subflow that belongs to this IP/port-pair. 1063 o REM_PATH.SCTP: 1064 Pass 1 primitive / event: 'Change Local Address / Set Peer 1065 Primary' 1066 Parameters: local IP address 1068 o SET_PRIMARY.SCTP: 1069 Pass 1 primitive / event: 'Set Primary' 1070 Parameters: socket 1071 Returns: result of attempting this operation 1072 Comments: update the current primary address to be used, based on 1073 the set of available sockets of the association. 1075 o SET_PEER_PRIMARY.SCTP: 1076 Pass 1 primitive / event: 'Change Local Address / Set Peer 1077 Primary' 1078 Parameters: local IP address 1079 Comments: this is only advisory for the peer. 1081 o CONFIG_SWITCHOVER.SCTP: 1082 Pass 1 primitive / event: 'Configure Path Switchover' 1083 Parameters: primary max retrans (no. of retransmissions after 1084 which a path is considered inactive), PF max retrans (no. of 1085 retransmissions after which a path is considered to be 1086 "Potentially Failed", and others will be preferably used) 1087 (optional) 1089 o STATUS.SCTP: 1090 Pass 1 primitive / event: 'Status', 'Enable / Disable 1091 Interleaving' and 'NETWORK STATUS CHANGE notification'. 1092 Returns: data block with information about a specified 1093 association, containing: association connection state; destination 1094 transport address list; destination transport address reachability 1095 states; current local and peer receiver window sizes; current 1096 local congestion window sizes; number of unacknowledged DATA 1097 chunks; number of DATA chunks pending receipt; primary path; most 1098 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1099 other destination addresses; MTU per path; interleaving supported 1100 yes/no. 1101 Comments: The NETWORK STATUS CHANGE notification informs the 1102 application about a socket becoming active/inactive; this only 1103 affects the programming style, as the same information is also 1104 available via 'Status'. 1106 o STATUS.MPTCP: 1107 Pass 1 primitive / event: not specified 1108 Returns: list of pairs of tuples of IP address and TCP port number 1109 of each subflow. The first of the pair is the local IP and port 1110 number, while the second is the remote IP and port number. 1112 o SET_DSCP.TCP: 1113 Pass 1 primitive / event: not specified 1114 Parameters: DSCP value 1115 Comments: this allows an application to change the DSCP value for 1116 outgoing segments. For TCP this was originally specified for the 1117 TOS field [RFC1122], which is here interpreted to refer to the 1118 DSField [RFC3260]. 1120 o SET_DSCP.SCTP: 1121 Pass 1 primitive / event: 'Set DSCP value' 1122 Parameters: DSCP value 1123 Comments: this allows an application to change the DSCP value for 1124 outgoing packets on a path. 1126 o SET_DSCP.UDP(-Lite): 1127 Pass 1 primitive / event: 'SET_DSCP' 1128 Parameter: DSCP value 1129 Comments: This allows an application to change the DSCP value for 1130 outgoing UDP(-Lite) datagrams. [RFC7657] and [RFC8085] provide 1131 current guidance on using this value with UDP. 1133 o ERROR.TCP: 1134 Pass 1 primitive / event: 'ERROR_REPORT' 1135 Returns: reason (encoding not specified); subreason (encoding not 1136 specified) 1137 Comments: soft errors that can be ignored without harm by many 1138 applications; an application should be able to disable these 1139 notifications. The reported conditions include at least: ICMP 1140 error message arrived; Excessive Retransmissions. 1142 o ERROR.UDP(-Lite): 1143 Pass 1 primitive / event: 'ERROR_REPORT'. 1144 Returns: Error report 1145 Comments: This returns soft errors that may be ignored without 1146 harm by many applications; An application must connect to be able 1147 receive these notifications. 1149 o SET_AUTH.SCTP: 1150 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1151 Parameters: key_id, key, hmac_id 1153 o GET_AUTH.SCTP: 1154 Pass 1 primitive / event: 'Set / Get Authentication Parameters' 1155 Parameters: key_id, chunk_list 1157 o RESET_STREAM.SCTP: 1158 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1159 Parameters: sid, direction 1161 o RESET_STREAM-EVENT.SCTP: 1162 Pass 1 primitive / event: 'STREAM RESET notification' 1163 Parameters: information about the result of RESET_STREAM.SCTP. 1164 Comments: This is issued when the procedure for resetting streams 1165 has completed. 1167 o RESET_ASSOC.SCTP: 1168 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1169 Parameters: information related to the extension defined in 1170 [RFC3260]. 1172 o RESET_ASSOC-EVENT.SCTP: 1173 Pass 1 primitive / event: 'ASSOCIATION RESET notification' 1174 Parameters: information about the result of RESET_ASSOC.SCTP. 1175 Comments: This is issued when the procedure for resetting an 1176 association has completed. 1178 o ADD_STREAM.SCTP: 1179 Pass 1 primitive / event: 'Add / Reset Streams, Reset Association' 1180 Parameters: number if outgoing and incoming streams to be added 1182 o ADD_STREAM-EVENT.SCTP: 1183 Pass 1 primitive / event: 'STREAM CHANGE notification' 1184 Parameters: information about the result of ADD_STREAM.SCTP. 1185 Comments: This is issued when the procedure for adding a stream 1186 has completed. 1188 o SET_STREAM_SCHEDULER.SCTP: 1189 Pass 1 primitive / event: 'Set Stream Scheduler' 1190 Parameters: scheduler identifier 1191 Comments: choice of First Come First Serve, Round Robin, Round 1192 Robin per Packet, Priority Based, Fair Bandwidth, Weighted Fair 1193 Queuing. 1195 o CONFIGURE_STREAM_SCHEDULER.SCTP: 1196 Pass 1 primitive / event: 'Configure Stream Scheduler' 1197 Parameters: priority 1198 Comments: the priority value only applies when Priority Based or 1199 Weighted Fair Queuing scheduling is chosen with 1200 SET_STREAM_SCHEDULER.SCTP. The meaning of the parameter differs 1201 between these two schedulers but in both cases it realizes some 1202 form of prioritization regarding how bandwidth is divided among 1203 streams. 1205 o SET_FLOWLABEL.SCTP: 1206 Pass 1 primitive / event: 'Set IPv6 flow label' 1207 Parameters: flow label 1208 Comments: this allows an application to change the IPv6 header's 1209 flow label field for outgoing packets on a path. 1211 o AUTHENTICATION_NOTIFICATION-EVENT.SCTP: 1212 Pass 1 primitive / event: 'AUTHENTICATION notification' 1213 Returns: information regarding key management. 1215 o CONFIG_SEND_BUFFER.SCTP: 1216 Pass 1 primitive / event: 'Configure send buffer size' 1217 Parameters: size value in octets 1219 o CONFIG_RECEIVE_BUFFER.SCTP: 1220 Pass 1 primitive / event: 'Configure receive buffer size' 1221 Parameters: size value in octets 1222 Comments: this controls the receiver window. 1224 o CONFIG_FRAGMENTATION.SCTP: 1225 Pass 1 primitive / event: 'Configure message fragmentation' 1226 Parameters: one boolean value (enable/disable), maximum 1227 fragmentation size (optional; default: PMTU) 1228 Comments: if fragmentation is enabled, messages exceeding the 1229 maximum fragmentation size will be fragmented. If fragmentation 1230 is disabled, trying to send a message that exceeds the maximum 1231 fragmentation size will produce an error. 1233 o CONFIG_PMTUD.SCTP: 1234 Pass 1 primitive / event: 'Configure Path MTU Discovery' 1235 Parameters: one boolean value (PMTUD on/off), PMTU value 1236 (optional) 1237 Returns: PMTU value 1238 Comments: This returns a meaningful PMTU value when PMTUD is 1239 enabled (the boolean is true), and the PMTU value can be set if 1240 PMTUD is disabled (the boolean is false) 1242 o CONFIG_DELAYED_SACK.SCTP: 1243 Pass 1 primitive / event: 'Configure delayed SACK timer' 1244 Parameters: one boolean value (delayed SACK on/off), timer value 1245 (optional), number of packets to wait for (default 2) 1246 Comments: If delayed SACK is enabled, SCTP will send a SACK upon 1247 either receiving the provided number of packets or when the timer 1248 expires, whatever occurs first. 1250 o CONFIG_RTO.SCTP: 1251 Pass 1 primitive / event: 'Configure RTO calculation' 1252 Parameters: init (optional), min (optional), max (optional) 1253 Comments: This adjusts the initial, minimum and maximum RTO 1254 values. 1256 o SET_COOKIE_LIFE.SCTP: 1257 Pass 1 primitive / event: 'Set Cookie life value' 1258 Parameters: cookie life value 1260 o SET_MAX_BURST.SCTP: 1261 Pass 1 primitive / event: 'Set maximum burst' 1262 Parameters: max burst value 1263 Comments: not all implementations allow values above the default 1264 of 4. 1266 o SET_PARTIAL_DELIVERY_POINT.SCTP: 1267 Pass 1 primitive / event: 'Set Partial Delivery Point' 1268 Parameters: partial delivery point (integer) 1269 Comments: this parameter must be smaller or equal to the socket 1270 receive buffer size. 1272 o CHECKSUM.UDP: 1273 Pass 1 primitive / event: 'DISABLE_CHECKSUM'. 1274 Parameters: 0 when no checksum is used at sender, 1 for checksum 1275 at sender (default) 1277 o CHECKSUM_REQUIRED.UDP: 1278 Pass 1 primitive / event: 'REQUIRE_CHECKSUM'. 1279 Parameter: 0 when checksum is required at receiver, 1 to allow 1280 zero checksum at receiver (default) 1282 o SET_CHECKSUM_COVERAGE.UDP-Lite: 1283 Pass 1 primitive / event: 'SET_CHECKSUM_COVERAGE' 1284 Parameters: Coverage length at sender (default maximum coverage) 1286 o SET_MIN_CHECKSUM_COVERAGE.UDP-Lite: 1287 Pass 1 primitive / event: 'SET_MIN_COVERAGE'. 1288 Parameter: Coverage length at receiver (default minimum coverage) 1290 o SET_DF.UDP(-Lite): 1291 Pass 1 primitive event: 'SET_DF'. 1292 Parameter: 0 when DF is not set (default), 1 when DF is set 1294 o SET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1295 Pass 1 primitive / event: 'SET_TTL' and 'SET_IPV6_UNICAST_HOPS' 1296 Parameters: IPv4 TTL value or IPv6 Hop Count value 1297 Comments: This allows an application to change the IPv4 TTL of 1298 IPv6 Hop count value for outgoing UDP(-Lite) datagrams. 1300 o GET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 1301 Pass 1 primitive / event: 'GET_TTL' and 'GET_IPV6_UNICAST_HOPS' 1302 Returns: IPv4 TTL value or IPv6 Hop Count value 1303 Comments: This allows an application to read the the IPv4 TTL of 1304 IPv6 Hop count value from a received UDP(-Lite) datagram. 1306 o SET_ECN.UDP(-Lite): 1307 Pass 1 primitive / event: 'SET_ECN' 1308 Parameters: ECN value 1309 Comments: This allows a UDP(-Lite) application to set the ECN 1310 codepoint field for outgoing UDP(-Lite) datagrams. 1312 o GET_ECN.UDP(-Lite): 1313 Pass 1 primitive / event: 'GET_ECN' 1314 Parameters: ECN value 1315 Comments: This allows a UDP(-Lite) application to read the ECN 1316 codepoint field from a received UDP(-Lite) datagram. 1318 o SET_IP_OPTIONS.UDP(-Lite): 1319 Pass 1 primitive / event: 'SET_IP_OPTIONS' 1320 Parameters: options 1321 Comments: This allows a UDP(-Lite) application to set IP Options 1322 for outgoing UDP(-Lite) datagrams. These options can at least be 1323 the Source Route, Record Route, and Time Stamp option. 1325 o GET_IP_OPTIONS.UDP(-Lite): 1326 Pass 1 primitive / event: 'GET_IP_OPTIONS' 1327 Returns: options 1328 Comments: This allows a UDP(-Lite) application to receive any IP 1329 options that are contained in a received UDP(-Lite) datagram. 1331 o CONFIGURE.LEDBAT: 1332 Pass 1 primitive / event: N/A 1333 Parameters: enable (boolean), TARGET, ALLOWED_INCREASE, GAIN_INC, 1334 GAIN_DEC, BASE_HISTORY, CURRENT_FILTER, INIT_CWND, MIN_CWND 1335 Comments: enable is a newly invented parameter that enables or 1336 disables the whole LEDBAT service. 1338 TERMINATION: 1339 Gracefully or forcefully closing a connection, or being informed 1340 about this event happening. 1342 o CLOSE.TCP: 1343 Pass 1 primitive / event: 'close' 1344 Comments: this terminates the sending side of a connection after 1345 reliably delivering all remaining data. 1347 o CLOSE.SCTP: 1348 Pass 1 primitive / event: 'Shutdown' 1349 Comments: this terminates a connection after reliably delivering 1350 all remaining data. 1352 o CLOSE.UDP(-Lite): 1353 Pass 1 primitive event: 'CLOSE' 1354 Comments: No further UDP(-Lite) datagrams are sent/received on 1355 this connection. 1357 o ABORT.TCP: 1358 Pass 1 primitive / event: 'abort' 1359 Comments: this terminates a connection without delivering 1360 remaining data and sends an error message to the other side. 1362 o ABORT.SCTP: 1363 Pass 1 primitive / event: 'abort' 1364 Parameters: abort reason to be given to the peer (optional) 1365 Comments: this terminates a connection without delivering 1366 remaining data and sends an error message to the other side. 1368 o TIMEOUT.TCP: 1369 Pass 1 primitive / event: 'USER TIMEOUT' event 1370 Comments: the application is informed that the connection is 1371 aborted. This event is executed on expiration of the timeout set 1372 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 1373 CONNECTION.MAINTENANCE.CHANGE_TIMEOUT.TCP). 1375 o TIMEOUT.SCTP: 1376 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1377 Comments: the application is informed that the connection is 1378 aborted. this event is executed on expiration of the timeout that 1379 should be enabled by default (see beginning of section 8.3 in 1380 [RFC4960]) and was possibly adjusted in 1381 CONNECTION.MAINTENANCE.CHANGE_TIMEOOUT.SCTP. 1383 o ABORT-EVENT.TCP: 1384 Pass 1 primitive / event: not specified. 1386 o ABORT-EVENT.SCTP: 1387 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1388 Returns: abort reason from the peer (if available) 1389 Comments: the application is informed that the other side has 1390 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 1392 o CLOSE-EVENT.TCP: 1393 Pass 1 primitive / event: not specified. 1395 o CLOSE-EVENT.SCTP: 1396 Pass 1 primitive / event: 'SHUTDOWN COMPLETE' event 1397 Comments: the application is informed that 1398 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 1400 4.2. DATA Transfer Related Primitives 1402 All primitives in this section refer to an existing connection, i.e. 1403 a connection that was either established or made available for 1404 receiving data (although this is optional for the primitives of UDP(- 1405 Lite)). In addition to the listed parameters, all sending primitives 1406 contain a reference to a data block and all receiving primitives 1407 contain a reference to available buffer space for the data. Note 1408 that CONNECT.TCP and LISTEN.TCP in the ESTABLISHMENT and AVAILABILITY 1409 category also allow to transfer data (an optional user message) 1410 before the connection is fully established. 1412 o SEND.TCP: 1413 Pass 1 primitive / event: 'send' 1414 Parameters: timeout (optional) 1415 Comments: this gives TCP a data block for reliable transmission to 1416 the TCP on the other side of the connection. The timeout can be 1417 configured with this call whenever data are sent (see also 1418 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 1420 o SEND.SCTP: 1421 Pass 1 primitive / event: 'Send' 1422 Parameters: stream number; context (optional); socket (optional); 1423 unordered flag (optional); no-bundle flag (optional); payload 1424 protocol-id (optional); pr-policy (optional) pr-value (optional); 1425 sack-immediately flag (optional); key-id (optional) 1426 Comments: this gives SCTP a data block for transmission to the 1427 SCTP on the other side of the connection (SCTP association). The 1428 'stream number' denotes the stream to be used. The 'context' 1429 number can later be used to refer to the correct message when an 1430 error is reported. The 'socket' can be used to state which path 1431 should be preferred, if there are multiple paths available (see 1432 also CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can 1433 be delivered out-of-order if the 'unordered flag' is set. The 1434 'no-bundle flag' can be set to indicate a preference to avoid 1435 bundling. The 'payload protocol-id' is a number that will, if 1436 provided, be handed over to the receiving application. Using pr- 1437 policy and pr-value the level of reliability can be controlled. 1438 The 'sack-immediately' flag can be used to indicate that the peer 1439 should not delay the sending of a SACK corresponding to the 1440 provided user message. If specified, the provided key-id is used 1441 for authenticating the user message. 1443 o SEND.UDP(-Lite): 1444 Pass 1 primitive / event: 'SEND' 1445 Parameters: IP Address and Port Number of the destination endpoint 1446 (optional if connected). 1447 Comments: This provides a message for unreliable transmission 1448 using UDP(-Lite) to the specified transport address. IP address 1449 and Port may be omitted for connected UDP(-Lite) sockets. All 1450 CONNECTION.MAINTENANCE.SET_*.UDP(-Lite) primitives apply per 1451 message sent. 1453 o RECEIVE.TCP: 1454 Pass 1 primitive / event: 'receive'. 1456 o RECEIVE.SCTP: 1457 Pass 1 primitive / event: 'DATA ARRIVE' notification, followed by 1458 'Receive' 1459 Parameters: stream number (optional) 1460 Returns: stream sequence number (optional), partial flag 1461 (optional) 1462 Comments: if the 'stream number' is provided, the call to receive 1463 only receives data on one particular stream. If a partial message 1464 arrives, this is indicated by the 'partial flag', and then the 1465 'stream sequence number' must be provided such that an application 1466 can restore the correct order of data blocks that comprise an 1467 entire message. Additionally, a delivery number lets the 1468 application detect reordering. 1470 o RECEIVE.UDP(-Lite): 1471 Pass 1 primitive / event: 'RECEIVE', 1472 Parameters: Buffer for received datagram. 1473 Comments: All CONNECTION.MAINTENANCE.GET_*.UDP(-Lite) primitives 1474 apply per message received. 1476 o SENDFAILURE-EVENT.SCTP: 1477 Pass 1 primitive / event: 'SEND FAILURE' notification, optionally 1478 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 1479 Message' 1480 Returns: cause code; context; unsent or unacknowledged message 1481 (optional) 1482 Comments: 'cause code' indicates the reason of the failure, and 1483 'context' is the context number if such a number has been provided 1484 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 1485 'Receive Unacknowledged Message', respectively. These primitives 1486 can be used to retrieve the unsent or unacknowledged message (or 1487 part of the message, in case a part was delivered) if desired. 1489 o SEND_FAILURE.UDP(-Lite): 1490 Pass 1 primitive / event: 'SEND' 1491 Comments: This may be used to probe for the effective PMTU when 1492 using in combination with the 'MAINTENANCE.SET_DF' primitive. 1494 o SENDER_DRY-EVENT.SCTP: 1495 Pass 1 primitive / event: 'SENDER DRY' notification 1496 Comments: This informs the application that the stack has no more 1497 user data to send. 1499 o PARTIAL_DELIVERY_ABORTED-EVENT.SCTP: 1500 Pass 1 primitive / event: 'PARTIAL DELIVERY ABORTED' notification 1501 Comments: This informs the receiver of a partial message that the 1502 further delivery of the message has been aborted. 1504 5. Pass 3 1506 This section presents the superset of all Transport Features in all 1507 protocols that were discussed in the preceding sections, based on the 1508 list of primitives in pass 2 but also on text in pass 1 to include 1509 features that can be configured in one protocol and are static 1510 properties in another (congestion control, for example). Again, some 1511 minor details are omitted for the sake of generalization -- e.g., TCP 1512 may provide various different IP options, but only source route is 1513 mandatory to implement, and this detail is not visible in the Pass 3 1514 feature "Specify IP Options". 1516 5.1. CONNECTION Related Transport Features 1518 ESTABLISHMENT: 1519 Active creation of a connection from one transport endpoint to one or 1520 more transport endpoints. 1522 o Connect 1523 Protocols: TCP, SCTP, UDP(-Lite) 1525 o Specify which IP Options must always be used 1526 Protocols: TCP 1528 o Request multiple streams 1529 Protocols: SCTP 1531 o Limit the number of inbound streams 1532 Protocols: SCTP 1534 o Specify number of attempts and/or timeout for the first 1535 establishment message 1536 Protocols: TCP, SCTP 1538 o Obtain multiple sockets 1539 Protocols: SCTP 1541 o Disable MPTCP 1542 Protocols: MPTCP 1544 o Specify which chunk types must always be authenticated 1545 Protocols: SCTP 1546 Comments: DATA, ACK etc. are different 'chunks' in SCTP; one or 1547 more chunks may be included in a single packet. 1549 o Indicate an Adaptation Layer (via an adaptation code point) 1550 Protocols: SCTP 1552 o Request to negotiate interleaving of user messages 1553 Protocols: SCTP 1555 o Hand over a message to transfer (possibly multiple times) before 1556 connection establishment 1557 Protocols: TCP 1559 o Hand over a message to transfer during connection establishment 1560 Protocols: SCTP 1562 o Enable UDP encapsulation with a specified remote UDP port number 1563 Protocols: SCTP 1565 AVAILABILITY: 1566 Preparing to receive incoming connection requests. 1568 o Listen, 1 specified local interface 1569 Protocols: TCP, SCTP, UDP(-Lite) 1571 o Listen, N specified local interfaces 1572 Protocols: SCTP, UDP(-Lite) 1574 o Listen, all local interfaces 1575 Protocols: TCP, SCTP, UDP(-Lite) 1577 o Obtain requested number of streams 1578 Protocols: SCTP 1580 o Limit the number of inbound streams 1581 Protocols: SCTP 1583 o Specify which IP Options must always be used 1584 Protocols: TCP 1586 o Disable MPTCP 1587 Protocols: MPTCP 1589 o Specify which chunk types must always be authenticated 1590 Protocols: SCTP 1591 Comments: DATA, ACK etc. are different 'chunks' in SCTP; one or 1592 more chunks may be included in a single packet. 1594 o Indicate an Adaptation Layer (via an adaptation code point) 1595 Protocols: SCTP 1597 MAINTENANCE: 1598 Adjustments made to an open connection, or notifications about it. 1600 o Change timeout for aborting connection (using retransmit limit or 1601 time value) 1602 Protocols: TCP, SCTP 1604 o Suggest timeout to the peer 1605 Protocols: TCP 1607 o Disable Nagle algorithm 1608 Protocols: TCP, SCTP 1610 o Request an immediate heartbeat, returning success/failure 1611 Protocols: SCTP 1613 o Notification of Excessive Retransmissions (early warning below 1614 abortion threshold) 1615 Protocols: TCP 1617 o Add path 1618 Protocols: MPTCP, SCTP 1619 MPTCP Parameters: source-IP; source-Port; destination-IP; 1620 destination-Port 1621 SCTP Parameters: local IP address 1623 o Remove path 1624 Protocols: MPTCP, SCTP 1625 MPTCP Parameters: source-IP; source-Port; destination-IP; 1626 destination-Port 1627 SCTP Parameters: local IP address 1629 o Set primary path 1630 Protocols: SCTP 1632 o Suggest primary path to the peer 1633 Protocols: SCTP 1635 o Configure Path Switchover 1636 Protocols: SCTP 1638 o Obtain status (query or notification) 1639 Protocols: SCTP, MPTCP 1640 SCTP parameters: association connection state; destination 1641 transport address list; destination transport address reachability 1642 states; current local and peer receiver window sizes; current 1643 local congestion window sizes; number of unacknowledged DATA 1644 chunks; number of DATA chunks pending receipt; primary path; most 1645 recent SRTT on primary path; RTO on primary path; SRTT and RTO on 1646 other destination addresses; MTU per path; interleaving supported 1647 yes/no 1648 MPTCP parameters: subflow-list (identified by source-IP; source- 1649 Port; destination-IP; destination-Port) 1651 o Specify DSCP field 1652 Protocols: TCP, SCTP, UDP(-Lite) 1654 o Notification of ICMP error message arrival 1655 Protocols: TCP, UDP(-Lite) 1657 o Change authentication parameters 1658 Protocols: SCTP 1660 o Obtain authentication information 1661 Protocols: SCTP 1663 o Reset Stream 1664 Protocols: SCTP 1666 o Notification of Stream Reset 1667 Protocols: STCP 1669 o Reset Association 1670 Protocols: SCTP 1672 o Notification of Association Reset 1673 Protocols: STCP 1675 o Add Streams 1676 Protocols: SCTP 1678 o Notification of Added Stream 1679 Protocols: STCP 1681 o Choose a scheduler to operate between streams of an association 1682 Protocols: SCTP 1684 o Configure priority or weight for a scheduler 1685 Protocols: SCTP 1687 o Specify IPv6 flow label field 1688 Protocols: SCTP 1690 o Configure send buffer size 1691 Protocols: SCTP 1693 o Configure receive buffer (and rwnd) size 1694 Protocols: SCTP 1696 o Configure message fragmentation 1697 Protocols: SCTP 1699 o Configure PMTUD 1700 Protocols: SCTP 1702 o Configure delayed SACK timer 1703 Protocols: SCTP 1705 o Set Cookie life value 1706 Protocols: SCTP 1708 o Set maximum burst 1709 Protocols: SCTP 1711 o Configure size where messages are broken up for partial delivery 1712 Protocols: SCTP 1714 o Disable checksum when sending 1715 Protocols: UDP 1717 o Disable checksum requirement when receiving 1718 Protocols: UDP 1720 o Specify checksum coverage used by the sender 1721 Protocols: UDP-Lite 1723 o Specify minimum checksum coverage required by receiver 1724 Protocols: UDP-Lite 1726 o Specify DF field 1727 Protocols: UDP(-Lite) 1729 o Specify TTL/Hop count field 1730 Protocols: UDP(-Lite) 1732 o Obtain TTL/Hop count field 1733 Protocols: UDP(-Lite) 1735 o Specify ECN field 1736 Protocols: UDP(-Lite) 1738 o Obtain ECN field 1739 Protocols: UDP(-Lite) 1741 o Specify IP Options 1742 Protocols: UDP(-Lite) 1744 o Obtain IP Options 1745 Protocols: UDP(-Lite) 1747 o Enable and configure "Low Extra Delay Background Transfer" 1748 Protocols: A protocol implementing the LEDBAT congestion control 1749 mechanism 1751 TERMINATION: 1752 Gracefully or forcefully closing a connection, or being informed 1753 about this event happening. 1755 o Close after reliably delivering all remaining data, causing an 1756 event informing the application on the other side 1757 Protocols: TCP, SCTP 1758 Comments: A TCP endpoint locally only closes the connection for 1759 sending; it may still receive data afterwards. 1761 o Abort without delivering remaining data, causing an event 1762 informing the application on the other side 1763 Protocols: TCP, SCTP 1764 Comments: In SCTP a reason can optionally be given by the 1765 application on the aborting side, which can then be received by 1766 the application on the other side. 1768 o Timeout event when data could not be delivered for too long 1769 Protocols: TCP, SCTP 1770 Comments: the timeout is configured with CONNECTION.MAINTENANCE 1771 "Change timeout for aborting connection (using retransmit limit or 1772 time value)". 1774 5.2. DATA Transfer Related Transport Features 1776 All features in this section refer to an existing connection, i.e. a 1777 connection that was either established or made available for 1778 receiving data. Note that TCP allows to transfer data (a single 1779 optional user message, possibly arriving multiple times) before the 1780 connection is fully established. Reliable data transfer entails 1781 delay -- e.g. for the sender to wait until it can transmit data, or 1782 due to retransmission in case of packet loss. 1784 5.2.1. Sending Data 1786 All features in this section are provided by DATA.SEND from pass 2. 1787 DATA.SEND is given a data block from the application, which we here 1788 call a "message" if the beginning and end of the data block can be 1789 identified at the receiver, and "data" otherwise. 1791 o Reliably transfer data, with congestion control 1792 Protocols: TCP 1794 o Reliably transfer a message, with congestion control 1795 Protocols: SCTP 1797 o Unreliably transfer a message, with congestion control 1798 Protocols: SCTP 1800 o Unreliably transfer a message, without congestion control 1801 Protocols: UDP(-Lite) 1803 o Configurable Message Reliability 1804 Protocols: SCTP 1806 o Choice of stream 1807 Protocols: SCTP 1809 o Choice of path (destination address) 1810 Protocols: SCTP 1812 o Choice between unordered (potentially faster) or ordered delivery 1813 of messages 1814 Protocols: SCTP 1816 o Request not to bundle messages 1817 Protocols: SCTP 1819 o Specifying a "payload protocol-id" (handed over as such by the 1820 receiver) 1821 Protocols: SCTP 1823 o Specifying a key id to be used to authenticate a message 1824 Protocols: SCTP 1826 o Request not to delay the acknowledgement (SACK) of a message 1827 Protocols: SCTP 1829 5.2.2. Receiving Data 1831 All features in this section are provided by DATA.RECEIVE from pass 1832 2. DATA.RECEIVE fills a buffer provided by the application, with 1833 what we here call a "message" if the beginning and end of the data 1834 block can be identified at the receiver, and "data" otherwise. 1836 o Receive data (with no message delineation) 1837 Protocols: TCP 1839 o Receive a message 1840 Protocols: SCTP, UDP(-Lite) 1842 o Choice of stream to receive from 1843 Protocols: SCTP 1845 o Information about partial message arrival 1846 Protocols: SCTP 1847 Comments: In SCTP, partial messages are combined with a stream 1848 sequence number so that the application can restore the correct 1849 order of data blocks an entire message consists of. 1851 o Obtain a message delivery number 1852 Protocols: SCTP 1853 Comments: This number can let applications detect and, if desired, 1854 correct reordering. 1856 5.2.3. Errors 1858 This section describes sending failures that are associated with a 1859 specific call to DATA.SEND from pass 2. 1861 o Notification of an unsent (part of a) message 1862 Protocols: SCTP, UDP(-Lite) 1864 o Notification of an unacknowledged (part of a) message 1865 Protocols: SCTP 1867 o Notification that the stack has no more user data to send 1868 Protocols: SCTP 1870 o Notification to a receiver that a partial message delivery has 1871 been aborted 1872 Protocols: SCTP 1874 6. Acknowledgements 1876 The authors would like to thank (in alphabetical order) Bob Briscoe, 1877 Gorry Fairhurst, David Hayes, Tom Jones, Karen Nielsen, Joe Touch and 1878 Brian Trammell for providing valuable feedback on this document. We 1879 especially thank Christoph Paasch for providing input related to 1880 Multipath TCP. This work has received funding from the European 1881 Union's Horizon 2020 research and innovation programme under grant 1882 agreement No. 644334 (NEAT). The views expressed are solely those of 1883 the author(s). 1885 7. IANA Considerations 1887 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 1889 This memo includes no request to IANA. 1891 8. Security Considerations 1893 Authentication, confidentiality protection, and integrity protection 1894 are identified as Transport Features by [RFC8095]. As currently 1895 deployed in the Internet, these features are generally provided by a 1896 protocol or layer on top of the transport protocol; no current full- 1897 featured standards-track transport protocol provides these features 1898 on its own. Therefore, these features are not considered in this 1899 document, with the exception of native authentication capabilities of 1900 SCTP for which the security considerations in [RFC4895] apply. 1902 9. References 1904 9.1. Normative References 1906 [FJ16] Fairhurst, G. and T. Jones, "Features of the User Datagram 1907 Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport 1908 Protocols", draft-ietf-taps-transports-usage-udp-00 (work 1909 in progress), November 2016. 1911 [I-D.ietf-tsvwg-sctp-ndata] 1912 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 1913 "Stream Schedulers and User Message Interleaving for the 1914 Stream Control Transmission Protocol", 1915 draft-ietf-tsvwg-sctp-ndata-08 (work in progress), 1916 October 2016. 1918 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1919 RFC 793, DOI 10.17487/RFC0793, September 1981, 1920 . 1922 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1923 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 1924 RFC1122, October 1989, 1925 . 1927 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 1928 Conrad, "Stream Control Transmission Protocol (SCTP) 1929 Partial Reliability Extension", RFC 3758, DOI 10.17487/ 1930 RFC3758, May 2004, 1931 . 1933 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 1934 "Authenticated Chunks for the Stream Control Transmission 1935 Protocol (SCTP)", RFC 4895, DOI 10.17487/RFC4895, 1936 August 2007, . 1938 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1939 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1940 . 1942 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 1943 Kozuka, "Stream Control Transmission Protocol (SCTP) 1944 Dynamic Address Reconfiguration", RFC 5061, DOI 10.17487/ 1945 RFC5061, September 2007, 1946 . 1948 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 1949 RFC 5482, DOI 10.17487/RFC5482, March 2009, 1950 . 1952 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 1953 Iyengar, "Architectural Guidelines for Multipath TCP 1954 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 1955 . 1957 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1958 Yasevich, "Sockets API Extensions for the Stream Control 1959 Transmission Protocol (SCTP)", RFC 6458, DOI 10.17487/ 1960 RFC6458, December 2011, 1961 . 1963 [RFC6525] Stewart, R., Tuexen, M., and P. Lei, "Stream Control 1964 Transmission Protocol (SCTP) Stream Reconfiguration", 1965 RFC 6525, DOI 10.17487/RFC6525, February 2012, 1966 . 1968 [RFC6817] Shalunov, S., Hazel, G., Iyengar, J., and M. Kuehlewind, 1969 "Low Extra Delay Background Transport (LEDBAT)", RFC 6817, 1970 DOI 10.17487/RFC6817, December 2012, 1971 . 1973 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1974 "TCP Extensions for Multipath Operation with Multiple 1975 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1976 . 1978 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 1979 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 1980 March 2013, . 1982 [RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream 1983 Control Transmission Protocol (SCTP) Packets for End-Host 1984 to End-Host Communication", RFC 6951, DOI 10.17487/ 1985 RFC6951, May 2013, 1986 . 1988 [RFC7053] Tuexen, M., Ruengeler, I., and R. Stewart, "SACK- 1989 IMMEDIATELY Extension for the Stream Control Transmission 1990 Protocol", RFC 7053, DOI 10.17487/RFC7053, November 2013, 1991 . 1993 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 1994 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 1995 . 1997 [RFC7496] Tuexen, M., Seggelmann, R., Stewart, R., and S. Loreto, 1998 "Additional Policies for the Partially Reliable Stream 1999 Control Transmission Protocol Extension", RFC 7496, 2000 DOI 10.17487/RFC7496, April 2015, 2001 . 2003 [RFC7829] Nishida, Y., Natarajan, P., Caro, A., Amer, P., and K. 2004 Nielsen, "SCTP-PF: A Quick Failover Algorithm for the 2005 Stream Control Transmission Protocol", RFC 7829, 2006 DOI 10.17487/RFC7829, April 2016, 2007 . 2009 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2010 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2011 March 2017, . 2013 9.2. Informative References 2015 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 2016 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, 2017 May 1983, . 2019 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2020 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2021 RFC2119, March 1997, 2022 . 2024 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 2025 of Explicit Congestion Notification (ECN) to IP", 2026 RFC 3168, DOI 10.17487/RFC3168, September 2001, 2027 . 2029 [RFC3260] Grossman, D., "New Terminology and Clarifications for 2030 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 2031 . 2033 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 2034 DOI 10.17487/RFC5461, February 2009, 2035 . 2037 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 2038 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 2039 January 2011, . 2041 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 2042 Zimmermann, "A Roadmap for Transmission Control Protocol 2043 (TCP) Specification Documents", RFC 7414, DOI 10.17487/ 2044 RFC7414, February 2015, 2045 . 2047 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2048 (Diffserv) and Real-Time Communication", RFC 7657, 2049 DOI 10.17487/RFC7657, November 2015, 2050 . 2052 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2053 Ed., "Services Provided by IETF Transport Protocols and 2054 Congestion Control Mechanisms", RFC 8095, DOI 10.17487/ 2055 RFC8095, March 2017, 2056 . 2058 Appendix A. Overview of RFCs used as input for pass 1 2060 TCP: [RFC0793], [RFC1122], [RFC5482], [RFC7413] 2061 MPTCP: [RFC6182], [RFC6824], [RFC6897] 2062 SCTP: RFCs without a socket API specification: [RFC3758], [RFC4895], 2063 [RFC4960], [RFC5061]. RFCs that include a socket API 2064 specification: [RFC6458], [RFC6525], [RFC6951], [RFC7053], 2065 [RFC7496] [RFC7829]. 2066 UDP(-Lite): See [FJ16] 2067 LEDBAT: [RFC6817]. 2069 Appendix B. How this document was developed 2071 This section gives an overview of the method that was used to develop 2072 this document. It was given to contributors for guidance, and it can 2073 be helpful for future updates or extensions. 2075 This document is only concerned with Transport Features that are 2076 explicitly exposed to applications via primitives. It also strictly 2077 follows RFC text: if a feature is truly relevant for an application, 2078 the RFCs should say so, and they should describe how to use and 2079 configure it. Thus, the approach followed for developing this 2080 document was to identify the right RFCs, then analyze and process 2081 their text. 2083 Primitives that MAY be implemented by a transport protocol were 2084 excluded. To be included, the minimum requirement level for a 2085 primitive to be implemented by a protocol was SHOULD. Where 2086 [RFC2119]-style requirements levels are not used, primitives were 2087 excluded when they are described in conjunction with statements like, 2088 e.g.: "some implementations also provide" or "an implementation may 2089 also". Excluded primitives or parameters were briefly described in a 2090 dedicated subsection. 2092 Pass 1: This began by identifying text that talks about primitives. 2093 An API specification, abstract or not, obviously describes primitives 2094 -- but we are not *only* interested in API specifications. The text 2095 describing the 'send' primitive in the API specified in [RFC0793], 2096 for instance, does not say that data transfer is reliable. TCP's 2097 reliability is clear, however, from this text in Section 1 of 2098 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 2099 use as a highly reliable host-to-host protocol between hosts in 2100 packet-switched computer communication networks, and in 2101 interconnected systems of such networks." 2103 Some text for pass 1 subsections was developed copy+pasting all the 2104 relevant text parts from the relevant RFCs, then adjusting 2105 terminology to match the terminology in Section 1 and adjusting 2106 (shortening!) phrasing to match the general style of the document. 2107 An effort was made to formulate everything as a primitive description 2108 such that the primitive descriptions became as complete as possible 2109 (e.g., the "SEND.TCP" primitive in pass 2 is explicitly described as 2110 reliably transferring data); text that is relevant for the primitives 2111 presented in this pass but still does not fit directly under any 2112 primitive was used in a subsection's introduction. 2114 Pass 2: The main goal of this pass is unification of primitives. As 2115 input, only text from pass 1 was used (no exterior sources). The 2116 list in pass 2 is not arranged by protocol ("first protocol X, here 2117 are all the primitives; then protocol Y, here are all the primitives, 2118 ..") but by primitive ("primitive A, implemented this way in protocol 2119 X, this way in protocol Y, ..."). It was a goal to obtain as many 2120 similar pass 2 primitives as possible. For instance, this was 2121 sometimes achieved by not always maintaining a 1:1 mapping between 2122 pass 1 and pass 2 primitives, renaming primitives etc. For every new 2123 primitive, the already existing primitives were considered to try to 2124 make them as coherent as possible. 2126 For each primitive, the following style was used: 2128 o PRIMITIVENAME.PROTOCOL: 2129 Pass 1 primitive / event: 2130 Parameters: 2131 Returns: 2132 Comments: 2134 The entries "Parameters", "Returns" and "Comments" were skipped when 2135 a primitive had no parameters, no described return value or no 2136 comments seemed necessary, respectively. Optional parameters are 2137 followed by "(optional)". When a default value is known, this was 2138 also provided. 2140 Pass 3: the main point of this pass is to identify transport protocol 2141 features that are the result of static properties of protocols, for 2142 which all protocols have to be listed together; this is then the 2143 final list of all available Transport Features. This list was 2144 primarily based on text from pass 2, with additional input from pass 2145 1 (but no external sources). 2147 Appendix C. Revision information 2149 XXX RFC-Ed please remove this section prior to publication. 2151 -00 (from draft-welzl-taps-transports): this now covers TCP based on 2152 all TCP RFCs (this means: if you know of something in any TCP RFC 2153 that you think should be addressed, please speak up!) as well as 2154 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 2155 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 2156 in line with [RFC8095]. Addressed comments by Karen Nielsen and 2157 Gorry Fairhurst; various other fixes. Appendices (TCP overview and 2158 how-to-contribute) added. 2160 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 2161 [RFC6897]. 2163 -02: included UDP, UDP-Lite, and all extensions of SCTPs. This 2164 includes fixing the [RFC6458] omission from -00. 2166 -03: wrote security considerations. The "how to contribute" section 2167 was updated to reflect how the document WAS created, not how it 2168 SHOULD BE created; it also no longer wrongly says that Experimental 2169 RFCs are excluded. Included LEDBAT. Changed abstract and intro to 2170 reflect which protocols/mechanisms are covered (TCP, MPTCP, SCTP, 2171 UDP, UDP-Lite, LEDBAT) instead of talking about "transport 2172 protocols". Interleaving and stream scheduling added 2173 (draft-ietf-tsvwg-sctp-ndata). TFO added. "Set protocol parameters" 2174 in SCTP replaced with per-parameter (or parameter group) primitives. 2175 More primitives added, mostly previously overlooked ones from 2176 [RFC6458]. Updated terminology (s/transport service feature/ 2177 transport feature) in line with an update of [RFC8095]. Made 2178 sequence of transport features / primitives more logical. Combined 2179 MPTCP's add/rem subflow with SCTP's add/remove local address. 2181 Authors' Addresses 2183 Michael Welzl 2184 University of Oslo 2185 PO Box 1080 Blindern 2186 Oslo, N-0316 2187 Norway 2189 Phone: +47 22 85 24 20 2190 Email: michawe@ifi.uio.no 2191 Michael Tuexen 2192 Muenster University of Applied Sciences 2193 Stegerwaldstrasse 39 2194 Steinfurt 48565 2195 Germany 2197 Email: tuexen@fh-muenster.de 2199 Naeem Khademi 2200 University of Oslo 2201 PO Box 1080 Blindern 2202 Oslo, N-0316 2203 Norway 2205 Email: naeemk@ifi.uio.no