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