idnits 2.17.1 draft-ietf-taps-transports-usage-01.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 10 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 8, 2016) is 2843 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 537, but not defined == Unused Reference: 'RFC2119' is defined on line 1134, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) -- Unexpected draft version: The latest known version of draft-fairhurst-taps-transports is -00, but you're referring to -08. -- Obsolete informational reference (is this intentional?): RFC 6093 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 6824 (Obsoleted by RFC 8684) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 4 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: January 9, 2017 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 July 8, 2016 10 On the Usage of Transport Service Features Provided by IETF Transport 11 Protocols 12 draft-ietf-taps-transports-usage-01 14 Abstract 16 This document describes how transport protocols expose services to 17 applications and how an application can configure and use the 18 features of a transport service. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 9, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . 4 58 3.1.1. Excluded Primitives . . . . . . . . . . . . . . . . . 7 59 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . 8 60 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 9 61 3.3.1. Excluded Primitives . . . . . . . . . . . . . . . . . 12 62 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 13 64 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . 19 65 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 66 5.1. CONNECTION Related Transport Service Features . . . . . . 21 67 5.2. DATA Transfer Related Transport Service Features . . . . 25 68 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . 25 69 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . 26 70 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . 27 71 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 27 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 75 9.1. Normative References . . . . . . . . . . . . . . . . . . 27 76 9.2. Informative References . . . . . . . . . . . . . . . . . 28 77 Appendix A. Overview of RFCs used as input for pass 1 . . . . . 29 78 Appendix B. How to contribute . . . . . . . . . . . . . . . . . 29 79 Appendix C. Revision information . . . . . . . . . . . . . . . . 31 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 82 1. Terminology 84 Transport Service Feature: a specific end-to-end feature that a 85 transport service provides to its clients. Examples include 86 confidentiality, reliable delivery, ordered delivery, message- 87 versus-stream orientation, etc. 88 Transport Service: a set of transport service features, without an 89 association to any given framing protocol, which provides a 90 complete service to an application. 91 Transport Protocol: an implementation that provides one or more 92 different transport services using a specific framing and header 93 format on the wire. 94 Transport Protocol Component: an implementation of a transport 95 service feature within a protocol. 97 Transport Service Instance: an arrangement of transport protocols 98 with a selected set of features and configuration parameters that 99 implements a single transport service, e.g., a protocol stack (RTP 100 over UDP). 101 Application: an entity that uses the transport layer for end-to-end 102 delivery of data across the network (this may also be an upper 103 layer protocol or tunnel encapsulation). 104 Endpoint: an entity that communicates with one or more other 105 endpoints using a transport protocol. 106 Connection: shared state of two or more endpoints that persists 107 across messages that are transmitted between these endpoints. 108 Primitive: a function call that is used to locally communicate 109 between an application and a transport endpoint and is related to 110 one or more Transport Service Features. 111 Parameter: a value passed between an application and a transport 112 protocol by a primitive. 113 Socket: the combination of a destination IP address and a 114 destination port number. 116 2. Introduction 118 This document presents defined interactions between transport 119 protocols and applications in the form of 'primitives' (function 120 calls). Primitives can be invoked by an application or a transport 121 protocol; the latter type is called an "event". The list of 122 transport service features and primitives in this document is 123 strictly based on the parts of protocol specifications that relate to 124 what the protocol provides to an application using it and how the 125 application interacts with it. It does not cover parts of a protocol 126 that are explicitly stated as optional to implement. 128 The document presents a three-pass process to arrive at a list of 129 transport service features. In the first pass, the relevant RFC text 130 is discussed per protocol. In the second pass, this discussion is 131 used to derive a list of primitives that are uniformly categorized 132 across protocols. Here, an attempt is made to present or -- where 133 text describing primitives does not yet exist -- construct primitives 134 in a slightly generalized form to highlight similarities. This is, 135 for example, achieved by renaming primitives of protocols or by 136 avoiding a strict 1:1-mapping between the primitives in the protocol 137 specification and primitives in the list. Finally, the third pass 138 presents transport service features based on pass 2, identifying 139 which protocols implement them. 141 In the list resulting from the second pass, some transport service 142 features are missing because they are implicit in some protocols, and 143 they only become explicit when we consider the superset of all 144 features offered by all protocols. For example, TCP's reliability 145 includes integrity via a checksum, but we have to include a protocol 146 like UDP-Lite as specified in [RFC3828] (which has a configurable 147 checksum) in the list before we can consider an always-on checksum as 148 a transport service feature. Similar arguments apply to other 149 protocol functions (e.g. congestion control). The complete list of 150 features across all protocols is therefore only available after pass 151 3. 153 This document discusses unicast transport protocols. [AUTHOR'S NOTE: 154 we skip "congestion control mechanisms" for now. This simplifies the 155 discussion; the congestion control mechanisms part is about LEDBAT, 156 which should be easy to add later.] Transport protocols provide 157 communication between processes that operate on network endpoints, 158 which means that they allow for multiplexing of communication between 159 the same IP addresses, and normally this multiplexing is achieved 160 using port numbers. Port multiplexing is therefore assumed to be 161 always provided and not discussed in this document. 163 Some protocols are connection-oriented. Connection-oriented 164 protocols often use an initial call to a specific transport primitive 165 to open a connection before communication can progress, and require 166 communication to be explicitly terminated by issuing another call to 167 a transport primitive (usually called "close"). A "connection" is 168 the common state that some transport primitives refer to, e.g., to 169 adjust general configuration settings. Connection establishment, 170 maintenance and termination are therefore used to categorize 171 transport primitives of connection-oriented transport protocols in 172 pass 2 and pass 3. 174 3. Pass 1 176 This first iteration summarizes the relevant text parts of the RFCs 177 describing the protocols, focusing on what each transport protocol 178 provides to the application and how it is used (abstract API 179 descriptions, where they are available). 181 3.1. Primitives Provided by TCP 183 [RFC0793] states: "The Transmission Control Protocol (TCP) is 184 intended for use as a highly reliable host-to-host protocol between 185 hosts in packet-switched computer communication networks, and in 186 interconnected systems of such networks". Section 3.8 in [RFC0793] 187 further specifies the interaction with the application by listing 188 several transport primitives. It is also assumed that an Operating 189 System provides a means for TCP to asynchronously signal the 190 application; the primitives representing such signals are called 191 'events' in this section. This section describes the relevant 192 primitives. 194 open: this is either active or passive, to initiate a connection or 195 listen for incoming connections. All other primitives are 196 associated with a specific connection, which is assumed to first 197 have been opened. An active open call contains a socket. A 198 passive open call with a socket waits for a particular connection; 199 alternatively, a passive open call can leave the socket 200 unspecified to accept any incoming connection. A fully specified 201 passive call can later be made active by calling 'send'. 202 Optionally, a timeout can be specified, after which TCP will abort 203 the connection if data has not been successfully delivered to the 204 destination (else a default timeout value is used). [RFC1122] 205 describes a procedure for aborting the connection that must be 206 used to avoid excessive retransmissions, and states that an 207 application must be able to control the threshold used to 208 determine the condition for aborting -- and that this threshold 209 may be measured in time units or as a count of retransmission. 210 This indicates that the timeout could also be specified as a count 211 of retransmission. 213 Also optional, for multihomed hosts, the local IP address can be 214 provided [RFC1122]. If it is not provided, a default choice will 215 be made in case of active open calls. A passive open call will 216 await incoming connection requests to all local addresses and then 217 maintain usage of the local IP address where the incoming 218 connection request has arrived. Finally, the 'options' parameter 219 is explained in [RFC1122] to allow the application to specify IP 220 options such as source route, record route, or timestamp. It is 221 not stated on which segments of a connection these options should 222 be applied, but probably all segments, as this is also stated in a 223 specification given for the usage of source route (section 4.2.3.8 224 of [RFC1122]). Source route is the only non-optional IP option in 225 this parameter, allowing an application to specify a source route 226 when it actively opens a TCP connection. 228 send: this is the primitive that an application uses to give the 229 local TCP transport endpoint a number of bytes that TCP should 230 reliably send to the other side of the connection. The URGENT 231 flag, if set, states that the data handed over by this send call 232 is urgent and this urgency should be indicated to the receiving 233 process in case the receiving application has not yet consumed all 234 non-urgent data preceding it. An optional timeout parameter can 235 be provided that updates the connection's timeout (see 'open'). 237 receive: This primitive allocates a receiving buffer for a provided 238 number of bytes. It returns the number of received bytes provided 239 in the buffer when these bytes have been received and written into 240 the buffer by TCP. The application is informed of urgent data via 241 an URGENT flag: if it is on, there is urgent data. If it is off, 242 there is no urgent data or this call to 'receive' has returned all 243 the urgent data. 245 close: This primitive closes one side of a connection. It is 246 semantically equivalent to "I have no more data to send" but does 247 not mean "I will not receive any more", as the other side may 248 still have data to send. This call reliably delivers any data 249 that has already been given to TCP (and if that fails, 'close' 250 becomes 'abort'). 252 abort: This primitive causes all pending 'send' and 'receive' calls 253 to be aborted. A TCP RESET message is sent to the TCP endpoint on 254 the other side of the connection [RFC0793]. 256 close event: TCP uses this primitive to inform an application that 257 the application on the other side has called the 'close' 258 primitive, so the local application can also issue a 'close' and 259 terminate the connection gracefully. See [RFC0793], Section 3.5. 261 abort event: When TCP aborts a connection upon receiving a "Reset" 262 from the peer, it "advises the user and goes to the CLOSED state." 263 See [RFC0793], Section 3.4. 265 USER TIMEOUT event: This event, described in Section 3.9 of 266 [RFC0793], is executed when the user timeout expires (see 'open'). 267 All queues are flushed and the application is informed that the 268 connection had to be aborted due to user timeout. 270 ERROR_REPORT event: This event, described in Section 4.2.4.1 of 271 [RFC1122], informs the application of "soft errors" that can be 272 safely ignored [RFC5461], including the arrival of an ICMP error 273 message or excessive retransmissions (reaching a threshold below 274 the threshold where the connection is aborted). 276 Type-of-Service: Section 4.2.4.2 of [RFC1122] states that the 277 application layer MUST be able to specify the Type-of-Service 278 (TOS) for segments that are sent on a connection. The application 279 should be able to change the TOS during the connection lifetime, 280 and the TOS value should be passed to the IP layer unchanged. 282 Since then the TOS field has been redefined. A part of the field 283 has been assigned to ECN [RFC3168] and the six most significant 284 bits have been assigned to carry the DiffServ CodePoint, DSField 285 [RFC3260]. Staying with the intention behind the application's 286 ability to specify the "Type of Service", this should probably be 287 interpreted to mean the value in the DSField, which is the 288 Differentiated Services Codepoint (DSCP). 290 Nagle: The Nagle algorithm, described in Section 4.2.3.4 of 291 [RFC1122], delays sending data for some time to increase the 292 likelihood of sending a full-sized segment. An application can 293 disable the Nagle algorithm for an individual connection. 295 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 296 one end of a TCP connection to advertise its current user timeout 297 value so that the other end of the TCP connection can adapt its 298 own user timeout accordingly. In addition to the configurable 299 value of the User Timeout (see 'send'), [RFC5482] introduces three 300 per-connection state variables that an application can adjust to 301 control the operation of the User Timeout Option (UTO): ADV_UTO is 302 the value of the UTO advertised to the remote TCP peer (default: 303 system-wide default user timeout); ENABLED (default false) is a 304 boolean-type flag that controls whether the UTO option is enabled 305 for a connection. This applies to both sending and receiving. 306 CHANGEABLE is a boolean-type flag (default true) that controls 307 whether the user timeout may be changed based on a UTO option 308 received from the other end of the connection. CHANGEABLE becomes 309 false when an application explicitly sets the user timeout (see 310 'send'). 312 3.1.1. Excluded Primitives 314 The 'open' primitive specified in [RFC0793] can be handed optional 315 Precedence or security/compartment information according to 316 [RFC0793], but this was not included here because it is mostly 317 irrelevant today, as explained in [RFC7414]. 319 The 'status' primitive was not included because [RFC0793] describes 320 this primitive as "implementation dependent" and states that it 321 "could be excluded without adverse effect". Moreover, while a data 322 block containing specific information is described, it is also stated 323 that not all of this information may always be available. The 'send' 324 primitive described in [RFC0793] includes an optional PUSH flag 325 which, if set, requires data to be promptly transmitted to the 326 receiver without delay; the 'receive' primitive described in 327 [RFC0793] can (under some conditions) yield the status of the PUSH 328 flag. Because PUSH functionality is made optional to implement for 329 both the 'send' and 'receive' primitives in [RFC1122], this 330 functionality is not included here. [RFC1122] also introduces keep- 331 alives to TCP, but these are optional to implement and hence not 332 considered here. [RFC1122] describes that "some TCP implementations 333 have included a FLUSH call", indicating that this call is also 334 optional to implement. It is therefore not considered here. 336 3.2. Primitives Provided by MPTCP 338 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 339 multiple paths for a single data-stream. It achieves this by 340 creating different so-called TCP subflows for each of the interfaces 341 and scheduling the traffic across these TCP subflows. The service 342 provided by MPTCP is described in [RFC6182] "Multipath TCP MUST 343 follow the same service model as TCP [RFC0793]: in- order, reliable, 344 and byte-oriented delivery. Furthermore, a Multipath TCP connection 345 SHOULD provide the application with no worse throughput or resilience 346 than it would expect from running a single TCP connection over any 347 one of its available paths." 349 Further, [RFC6182] states constraints on the API exposed by MPTCP: "A 350 multipath-capable equivalent of TCP MUST retain some level of 351 backward compatibility with existing TCP APIs, so that existing 352 applications can use the newer merely by upgrading the operating 353 systems of the end hosts." As such, the primitives provided by MPTCP 354 are equivalent to the ones provided by TCP. Nevertheless, [RFC6824] 355 and [RFC6897] clarify some parts of TCP's primitives with respect to 356 MPTCP and add some extensions for better control on MPTCP's subflows. 357 Hereafter is a list of the clarifications and extensions the above 358 cited RFCs provide to TCP's primitives. 360 open: [RFC6897] states "An application should be able to request to 361 turn on or turn off the usage of MPTCP.". The RFC states that 362 this functionality can be provided through a socket-option called 363 TCP_MULTIPATH_ENABLE. Further, [RFC6897] says that MPTCP must be 364 disabled in case the application is binding to a specific address. 366 send/receive: [RFC6824] states that the sending and receiving of 367 data does not require any changes to the application when MPTCP is 368 being used. The MPTCP-layer will "take one input data stream from 369 an application, and split it into one or more subflows, with 370 sufficient control information to allow it to be reassembled and 371 delivered reliably and in order to the recipient application." 372 The use of the Urgent-Pointer is special in MPTCP and [RFC6824] 373 says "a TCP subflow MUST NOT use the Urgent Pointer to interrupt 374 an existing mapping." 376 address and subflow management:: MPTCP uses different addresses and 377 allows a host to announce these addresses as part of the protocol. 378 [RFC6897] says "An application should be able to restrict MPTCP to 379 binding to a given set of addresses." and thus allows applications 380 to limit the set of addresses that are being used by MPTCP. 381 Further, "An application should be able to obtain information on 382 the pairs of addresses used by the MPTCP subflows.". 384 3.3. Primitives Provided by SCTP 386 Section 1.1 of [RFC4960] lists limitations of TCP that SCTP removes. 387 Three of the four mentioned limitations directly translate into a 388 transport service features that are visible to an application using 389 SCTP: 1) it allows for preservation of message delineations; 2) these 390 messages, while reliably transferred, do not require to be in order 391 unless the application wants it; 3) multi-homing is supported. In 392 SCTP, connections are called "association" and they can be between 393 not only two (as in TCP) but multiple addresses at each endpoint. 395 Section 10 of [RFC4960] further specifies the interaction with the 396 application (which RFC [RFC4960] calls the "Upper Layer Protocol" 397 (ULP)). It is assumed that the Operating System provides a means for 398 SCTP to asynchronously signal the application; the primitives 399 representing such signals are called 'events' in this section. Here, 400 we describe the relevant primitives. 402 Initialize: Initialize creates a local SCTP instance that it binds 403 to a set of local addresses (and, if provided, port number). 404 Initialize needs to be called only once per set of local 405 addresses. 407 Associate: This creates an association (the SCTP equivalent of a 408 connection) between the local SCTP instance and a remote SCTP 409 instance. Most primitives are associated with a specific 410 association, which is assumed to first have been created. 411 Associate can return a list of destination transport addresses so 412 that multiple paths can later be used. One of the returned 413 sockets will be selected by the local endpoint as default primary 414 path for sending SCTP packets to this peer, but this choice can be 415 changed by the application using the list of destination 416 addresses. Associate is also given the number of outgoing streams 417 to request and optionally returns the number of outgoing streams 418 negotiated. 420 Send: This sends a message of a certain length in bytes over an 421 association. A number can be provided to later refer to the 422 correct message when reporting an error, and a stream id is 423 provided to specify the stream to be used inside an association 424 (we consider this as a mandatory parameter here for simplicity: if 425 not provided, the stream id defaults to 0). An optional maximum 426 life time can specify the time after which the message should be 427 discarded rather than sent. A choice (advisory, i.e. not 428 guaranteed) of the preferred path can be made by providing a 429 socket, and the message can be delivered out-of-order if the 430 unordered flag is set. Another advisory flag indicates whether 431 the application prefers to avoid bundling user data with other 432 outbound DATA chunks (i.e., in the same packet). A payload 433 protocol-id can be provided to pass a value that indicates the 434 type of payload protocol data to the peer. 436 Receive: Messages are received from an association, and optionally a 437 stream within the association, with their size returned. The 438 application is notified of the availability of data via a DATA 439 ARRIVE notification. If the sender has included a payload 440 protocol-id, this value is also returned. If the received message 441 is only a partial delivery of a whole message, a partial flag will 442 indicate so, in which case the stream id and a stream sequence 443 number are provided to the application. 445 Shutdown: This primitive gracefully closes an association, reliably 446 delivering any data that has already been handed over to SCTP. A 447 return code informs about success or failure of this procedure. 449 Abort: This ungracefully closes an association, by discarding any 450 locally queued data and informing the peer that the association 451 was aborted. Optionally, an abort reason to be passed to the peer 452 may be provided by the application. A return code informs about 453 success or failure of this procedure. 455 Change Heartbeat / Request Heartbeat: This allows the application to 456 enable/disable heartbeats and optionally specify a heartbeat 457 frequency as well as requesting a single heartbeat to be carried 458 out upon a function call, with a notification about success or 459 failure of transmitting the HEARTBEAT chunk to the destination. 461 Set Protocol Parameters: This allows to set values for protocol 462 parameters per association; for some parameters, a setting can be 463 made per socket. The set listed in [RFC4960] is: RTO.Initial; 464 RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; RTO.Beta; 465 Valid.Cookie.Life; Association.Max.Retrans; Path.Max.Retrans; 466 Max.Init.Retransmits; HB.interval; HB.Max.Burst. 468 Set Primary: This allows to set a new primary default path for an 469 association by providing a socket. Optionally, a default source 470 address to be used in IP datagrams can be provided. 472 Status: The 'Status' primitive returns a data block with information 473 about a specified association, containing: association connection 474 state; socket list; destination transport address reachability 475 states; current receiver window size; current congestion window 476 sizes; number of unacknowledged DATA chunks; number of DATA chunks 477 pending receipt; primary path; most recent SRTT on primary path; 478 RTO on primary path; SRTT and RTO on other destination addresses. 480 COMMUNICATION UP notification: When a lost communication to an 481 endpoint is restored or when SCTP becomes ready to send or receive 482 user messages, this notification informs the application process 483 about the affected association, the type of event that has 484 occurred, the complete set of sockets of the peer, the maximum 485 number of allowed streams and the inbound stream count (the number 486 of streams the peer endpoint has requested). 488 DATA ARRIVE notification: When a message is ready to be retrieved 489 via the Receive primitive, the application is informed by this 490 notification. 492 SEND FAILURE notification / Receive Unsent Message 493 / Receive Unacknowledged Message: 494 When a message cannot be delivered via an association, the sender 495 can be informed about it and learn whether the message has just 496 not been acknowledged or (e.g. in case of lifetime expiry) if it 497 has not even been sent. 499 NETWORK STATUS CHANGE notification: The NETWORK STATUS CHANGE 500 notification informs the application about a socket becoming 501 active/inactive. 503 COMMUNICATION LOST notification: When SCTP loses communication to an 504 endpoint (e.g. via Heartbeats or excessive retransmission) or 505 detects an abort, this notification informs the application 506 process of the affected association and the type of event (failure 507 OR termination in response to a shutdown or abort request). 509 SHUTDOWN COMPLETE notification: When SCTP completes the shutdown 510 procedures, this notification is passed to the upper layer, 511 informing it about the affected assocation. 513 3.3.1. Excluded Primitives 515 The 'Receive' primitive can return certain additional information, 516 but this is optional to implement and therefore not considered. With 517 a COMMUNICATION LOST notification, some more information may 518 optionally be passed to the application (e.g., identification to 519 retrieve unsent and unacknowledged data). SCTP "can invoke" a 520 COMMUNICATION ERROR notification and "may send" a RESTART 521 notification, making these two notifications optional to implement. 522 The list provided under 'Status' includes "etc", indicating that more 523 information could be provided. The primitive 'Get SRTT Report' 524 returns information that is included in the information that 'Status' 525 provides and is therefore not discussed. Similarly, 'Set Failure 526 Threshold' sets only one out of various possible parameters included 527 in 'Set Protocol Parameters'. The 'Destroy SCTP Instance' API 528 function was excluded: it erases the SCTP instance that was created 529 by 'Initialize', but is not a Primitive as defined in this document 530 because it does not relate to a Transport Service Feature. 532 4. Pass 2 534 This pass categorizes the primitives from pass 1 based on whether 535 they relate to a connection or to data transmission. Primitives are 536 presented following the nomenclature: 537 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 538 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 539 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 540 considered. The DATA category does not have any SUBCATEGORY (as of 541 now). A connection is a general protocol-independent concept and 542 refers to, e.g., TCP connections (identifiable by a unique pair of IP 543 addresses and TCP port numbers) as well as SCTP associations 544 (identifiable by multiple IP address and port number pairs). 546 Some minor details are omitted for the sake of generalization -- 547 e.g., SCTP's 'close' [RFC4960] returns success or failure, whereas 548 this is not described in the same way for TCP in [RFC0793], but this 549 detail plays no significant role for the primitives provided by 550 either TCP or SCTP. 552 The TCP 'send' and 'receive' primitives include usage of an "URGENT" 553 mechanism. This mechanism is required to implement the "synch 554 signal" used by telnet [RFC0854], but SHOULD NOT be used by new 555 applications [RFC6093]. Because pass 2 is meant as a basis for the 556 creation of TAPS systems, the "URGENT" mechanism is excluded. This 557 also concerns the notification "Urgent pointer advance" in the 558 ERROR_REPORT described in Section 4.2.4.1 of [RFC1122]. 560 4.1. CONNECTION Related Primitives 562 ESTABLISHMENT: 563 Active creation of a connection from one transport endpoint to one or 564 more transport endpoints. 566 o CONNECT.TCP: 567 Pass 1 primitive / event: 'open' (active) or 'open' (passive) with 568 socket, followed by 'send' 569 Parameters: 1 local IP address (optional); 1 destination transport 570 address (for active open; else the socket and the local IP address 571 of the succeeding incoming connection request will be maintained); 572 timeout (optional); options (optional) 573 Comments: If the local IP address is not provided, a default 574 choice will automatically be made. The timeout can also be a 575 retransmission count. The options are IP options to be used on 576 all segments of the connection. At least the Source Route option 577 is mandatory for TCP to provide. 579 o CONNECT.SCTP: 580 Pass 1 primitive / event: 'initialize', followed by 'associate' 581 Parameters: list of local SCTP port number / IP address pairs 582 (initialize); 1 socket; outbound stream count 583 Returns: socket list 584 Comments: 'initialize' needs to be called only once per list of 585 local SCTP port number / IP address pairs. One socket will 586 automatically be chosen; it can later be changed in MAINTENANCE. 588 o Disable-MPTCP.MPTCP: 589 Pass 1 primitive / event: 'open' (active) or 'open' (passive) 590 Parameters: one boolean value 591 Comments: MPTCP is by default enabled on all TCP connections. 592 However, an application is still able to disable MPTCP for a 593 particular connection or socket prior to the CONNECT.TCP and 594 LISTEN.TCP primitives. 596 AVAILABILITY: 597 Preparing to receive incoming connection requests. 599 o LISTEN.TCP: 600 Pass 1 primitive / event: 'open' (passive) 601 Parameters: 1 local IP address (optional); 1 socket (optional); 602 timeout (optional) 603 Comments: if the socket and/or local IP address is provided, this 604 waits for incoming connections from only and/or to only the 605 provided address. Else this waits for incoming connections 606 without this / these constraint(s). ESTABLISHMENT can later be 607 performed with 'send'. 609 o LISTEN.SCTP: 610 Pass 1 primitive / event: 'initialize', followed by 'COMMUNICATION 611 UP' notification 612 Parameters: list of local SCTP port number / IP address pairs 613 (initialize) 614 Returns: socket list; outbound stream count; inbound stream count 615 Comments: initialize needs to be called only once per list of 616 local SCTP port number / IP address pairs. COMMUNICATION UP can 617 also follow a COMMUNICATION LOST notification, indicating that the 618 lost communication is restored. 620 MAINTENANCE: 621 Adjustments made to an open connection, or notifications about it. 622 These are out-of-band messages to the protocol that can be issued at 623 any time, at least after a connection has been established and before 624 it has been terminated (with one exception: CHANGE-TIMEOUT.TCP can 625 only be issued when DATA.SEND.TCP is called). 627 o CHANGE-TIMEOUT.TCP: 629 Pass 1 primitive / event: 'send' combined with unspecified control 630 of per-connection state variables 631 Parameters: timeout value (optional); ADV_UTO (optional); boolean 632 UTO_ENABLED (optional, default false); boolean CHANGEABLE 633 (optional, default true) 634 Comments: when sending data, an application can adjust the 635 connection's timeout value (time after which the connection will 636 be aborted if data could not be delivered). If UTO_ENABLED is 637 true, the user timeout value (or, if provided, the value ADV_UTO) 638 will be advertised for the TCP on the other side of the connection 639 to adapt its own user timeout accordingly. UTO_ENABLED controls 640 whether the UTO option is enabled for a connection. This applies 641 to both sending and receiving. CHANGEABLE controls whether the 642 user timeout may be changed based on a UTO option received from 643 the other end of the connection; it becomes false when 'timeout 644 value' is used. 646 o CHANGE-TIMEOUT.SCTP: 647 Pass 1 primitive / event: 'Change HeartBeat' combined with 'Set 648 Protocol Parameters' 649 Parameters: 'Change HeartBeat': heartbeat frequency; 'Set Protocol 650 Parameters': Association.Max.Retrans (whole association) or 651 Path.Max.Retrans (per socket) 652 Comments: Change Heartbeat can enable / disable heartbeats in SCTP 653 as well as change their frequency. The parameter 654 Association.Max.Retrans defines after how many unsuccessful 655 heartbeats the connection will be terminated; thus these two 656 primitives / parameters together can yield a similar behavior to 657 CHANGE-TIMEOUT.TCP. 659 o DISABLE-NAGLE.TCP: 660 Pass 1 primitive / event: not specified 661 Parameters: one boolean value 662 Comments: the Nagle algorithm delays data transmission to increase 663 the chance to send a full-sized segment. An application must be 664 able to disable this algorithm for a connection. This is related 665 to the no-bundle flag in DATA.SEND.SCTP. 667 o REQUESTHEARTBEAT.SCTP: 668 Pass 1 primitive / event: 'Request HeartBeat' 669 Parameters: socket 670 Returns: success or failure 671 Comments: requests an immediate heartbeat on a path, returning 672 success or failure. 674 o SETPROTOCOLPARAMETERS.SCTP: 675 Pass 1 primitive / event: 'Set Protocol Parameters' 676 Parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; 677 RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 678 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst 680 o SETPRIMARY.SCTP: 681 Pass 1 primitive / event: 'Set Primary' 682 Parameters: socket 683 Returns: result of attempting this operation 684 Comments: update the current primary address to be used, based on 685 the set of available sockets of the association. 687 o ERROR.TCP: 688 Pass 1 primitive / event: 'ERROR_REPORT' 689 Returns: reason (encoding not specified); subreason (encoding not 690 specified) 691 Comments: soft errors that can be ignored without harm by many 692 applications; an application should be able to disable these 693 notifications. The reported conditions include at least: ICMP 694 error message arrived; Excessive Retransmissions. 696 o STATUS.SCTP: 697 Pass 1 primitive / event: 'Status' and 'NETWORK STATUS CHANGE' 698 notification 699 Returns: data block with information about a specified 700 association, containing: association connection state; socket 701 list; destination transport address reachability states; current 702 receiver window size; current congestion window sizes; number of 703 unacknowledged DATA chunks; number of DATA chunks pending receipt; 704 primary path; most recent SRTT on primary path; RTO on primary 705 path; SRTT and RTO on other destination addresses. The NETWORK 706 STATUS CHANGE notification informs the application about a socket 707 becoming active/inactive. 709 o STATUS.MPTCP: 710 Pass 1 primitive / event: not specified 711 Returns: list of pairs of tuples of IP address and TCP port number 712 of each subflow. The first of the pair is the local IP and port 713 number, while the second is the remote IP and port number. 715 o CHANGE-DSCP.TCP: 716 Pass 1 primitive / event: not specified 717 Parameters: DSCP value 718 Comments: this allows an application to change the DSCP value. 719 For TCP this was originally specified for the TOS field [RFC1122], 720 which is here interpreted to refer to the DSField [RFC3260]. 722 o ADD_SUBFLOW.MPTCP: 723 Pass 1 primitive / event: not specified 724 Parameters: local IP address and optionally the local port number 725 Comments: the application specifies the local IP address and port 726 number that must be used for a new subflow. 728 o REM_SUBFLOW.MPTCP: 729 Pass 1 primitive / event: not specified 730 Parameters: local IP address, local port number, remote IP 731 address, remote port number 732 Comments: the application removes the subflow specified by the IP/ 733 port-pair. The MPTCP implementation must trigger a removal of the 734 subflow that belongs to this IP/port-pair. 736 TERMINATION: 737 Gracefully or forcefully closing a connection, or being informed 738 about this event happening. 740 o CLOSE.TCP: 741 Pass 1 primitive / event: 'close' 742 Comments: this terminates the sending side of a connection after 743 reliably delivering all remaining data. 745 o CLOSE.SCTP: 746 Pass 1 primitive / event: 'Shutdown' 747 Comments: this terminates a connection after reliably delivering 748 all remaining data. 750 o ABORT.TCP: 751 Pass 1 primitive / event: 'abort' 752 Comments: this terminates a connection without delivering 753 remaining data and sends an error message to the other side. 755 o ABORT.SCTP: 756 Pass 1 primitive / event: 'abort' 757 Parameters: abort reason to be given to the peer (optional) 758 Comments: this terminates a connection without delivering 759 remaining data and sends an error message to the other side. 761 o TIMEOUT.TCP: 762 Pass 1 primitive / event: 'USER TIMEOUT' event 763 Comments: the application is informed that the connection is 764 aborted. This event is executed on expiration of the timeout set 765 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 766 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 768 o TIMEOUT.SCTP: 769 Pass 1 primitive / event: 'COMMUNICATION LOST' event 770 Comments: the application is informed that the connection is 771 aborted. this event is executed on expiration of the timeout that 772 should be enabled by default (see beginning of section 8.3 in 773 [RFC4960]) and was possibly adjusted in 774 CONNECTION.MAINTENANCE.CHANGE-TIMEOOUT.SCTP. 776 o ABORT-EVENT.TCP: 777 Pass 1 primitive / event: not specified. 779 o ABORT-EVENT.SCTP: 780 Pass 1 primitive / event: 'COMMUNICATION LOST' event 781 Returns: abort reason from the peer (if available) 782 Comments: the application is informed that the other side has 783 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 785 o CLOSE-EVENT.TCP: 786 Pass 1 primitive / event: not specified. 788 o CLOSE-EVENT.SCTP: 789 Pass 1 primitive / event: 'SHUTDOWN COMPLETE' event 790 Comments: the application is informed that 791 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 793 4.2. DATA Transfer Related Primitives 795 All primitives in this section refer to an existing connection, i.e. 796 a connection that was either established or made available for 797 receiving data. In addition to the listed parameters, all sending 798 primitives contain a reference to a data block and all receiving 799 primitives contain a reference to available buffer space for the 800 data. 802 o SEND.TCP: 803 Pass 1 primitive / event: 'send' 804 Parameters: timeout (optional) 805 Comments: this gives TCP a data block for reliable transmission to 806 the TCP on the other side of the connection. The timeout can be 807 configured with this call whenever data are sent (see also 808 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 810 o SEND.SCTP: 811 Pass 1 primitive / event: 'Send' 812 Parameters: stream number; context (optional); life time 813 (optional); socket (optional); unordered flag (optional); no- 814 bundle flag (optional); payload protocol-id (optional) 815 Comments: this gives SCTP a data block for reliable transmission 816 to the SCTP on the other side of the connection (SCTP 817 association). The 'stream number' denotes the stream to be used. 818 The 'context' number can later be used to refer to the correct 819 message when an error is reported. The 'life time' specifies a 820 time after which this data block will not be sent. The 'socket' 821 can be used to state which path should be preferred, if there are 822 multiple paths available (see also 823 CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can be 824 delivered out-of-order if the 'unordered flag' is set. The 'no- 825 bundle flag' can be set to indicate a preference to avoid 826 bundling. The 'payload protocol-id' is a number that will, if 827 provided, be handed over to the receiving application. 829 o RECEIVE.TCP: 830 Pass 1 primitive / event: 'receive'. 832 o RECEIVE.SCTP: 833 Pass 1 primitive / event: 'DATA ARRIVE' notification, followed by 834 'Receive' 835 Parameters: stream number (optional) 836 Returns: stream sequence number (optional), partial flag 837 (optional) 838 Comments: if the 'stream number' is provided, the call to receive 839 only receives data on one particular stream. If a partial message 840 arrives, this is indicated by the 'partial flag', and then the 841 'stream sequence number' must be provided such that an application 842 can restore the correct order of data blocks that comprise an 843 entire message. 845 o SENDFAILURE-EVENT.SCTP: 846 Pass 1 primitive / event: 'SEND FAILURE' notification, optionally 847 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 848 Message' 849 Returns: cause code; context; unsent or unacknowledged message 850 (optional) 851 Comments: 'cause code' indicates the reason of the failure, and 852 'context' is the context number if such a number has been provided 853 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 854 'Receive Unacknowledged Message', respectively. These primitives 855 can be used to retrieve the complete unsent or unacknowledged 856 message if desired. 858 5. Pass 3 860 This section presents the superset of all transport service features 861 in all protocols that were discussed in the preceding sections, based 862 on the list of primitives in pass 2 but also on text in pass 1 to 863 include features that can be configured in one protocol and are 864 static properties in another. Again, some minor details are omitted 865 for the sake of generalization -- e.g., TCP may provide various 866 different IP options, but only source route is mandatory to 867 implement, and this detail is not visible in the Pass 3 feature 868 "Specify IP Options". 870 [AUTHOR'S NOTE: the list here looks pretty similar to the list in 871 pass 2 for now. This will change as more protocols are added. For 872 example, when we add UDP, we will find that UDP does not do 873 congestion control, which is relevant to the application using it. 874 This will have to be reflected in pass 1 and pass 2, only for UDP. 875 In pass 3, we can then derive "no congestion control" as a transport 876 service feature of UDP; however, since it would be strange to call 877 the lack of congestion control a feature, the natural outcome is then 878 to list "congestion control" as a feature of TCP and SCTP.] 880 5.1. CONNECTION Related Transport Service Features 882 ESTABLISHMENT: 883 Active creation of a connection from one transport endpoint to one or 884 more transport endpoints. 886 o Connect 887 Protocols: TCP, SCTP 889 o Specify IP Options 890 Protocols: TCP 892 o Request multiple streams 893 Protocols: SCTP 895 o Obtain multiple sockets 896 Protocols: SCTP 898 o Disable MPTCP 899 Protocols: MPTCP/TCP 901 AVAILABILITY: 902 Preparing to receive incoming connection requests. 904 o Listen, 1 specified local interface 905 Protocols: TCP, SCTP 907 o Listen, N specified local interfaces 908 Protocols: SCTP 910 o Listen, all local interfaces 911 Protocols: TCP, SCTP 913 o Obtain requested number of streams 914 Protocols: SCTP 916 MAINTENANCE: 917 Adjustments made to an open connection, or notifications about it. 918 NOTE: all features except "set primary path" in this category apply 919 to one out of multiple possible paths (identified via sockets) in 920 SCTP, whereas TCP uses only one path (one socket). 922 o Change timeout for aborting connection (using retransmit limit or 923 time value) 924 Protocols: TCP, SCTP 926 o Control advertising timeout for aborting connection to remote 927 endpoint 928 Protocols: TCP 930 o Disable Nagle algorithm 931 Protocols: TCP, SCTP 932 Comments: This is not specified in [RFC4960] but in [RFC6458]. 934 o Request an immediate heartbeat, returning success/failure 935 Protocols: SCTP 937 o Set protocol parameters 938 Protocols: SCTP 939 SCTP parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; 940 RTO.Alpha; RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 941 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst 942 Comments: in future versions of this document, it might make sense 943 to split out some of these parameters -- e.g., if a different 944 protocol provides means to adjust the RTO calculation there could 945 be a common feature for them called "adjust RTO calculation". 947 o Notification of Excessive Retransmissions (early warning below 948 abortion threshold) 949 Protocols: TCP 951 o Notification of ICMP error message arrival 952 Protocols: TCP 954 o Status (query or notification) 955 Protocols: SCTP, MPTCP 956 SCTP parameters: association connection state; socket list; socket 957 reachability states; current receiver window size; current 958 congestion window sizes; number of unacknowledged DATA chunks; 959 number of DATA chunks pending receipt; primary path; most recent 960 SRTT on primary path; RTO on primary path; SRTT and RTO on other 961 destination addresses; socket becoming active / inactive 962 MPTCP parameters: subflow-list (identified by source-IP; source- 963 Port; destination-IP; destination-Port) 965 o Set primary path 966 Protocols: SCTP 968 o Change DSCP 969 Protocols: TCP 970 Comments: This is described to be changeable for SCTP too in 971 [RFC6458]. 973 o Add subflow 974 Protocols: MPTCP 975 MPTCP Parameters: source-IP; source-Port; destination-IP; 976 destination-Port 978 o Remove subflow 979 Protocols: MPTCP 980 MPTCP Parameters: source-IP; source-Port; destination-IP; 981 destination-Port 983 TERMINATION: 984 Gracefully or forcefully closing a connection, or being informed 985 about this event happening. 987 o Close after reliably delivering all remaining data, causing an 988 event informing the application on the other side 989 Protocols: TCP, SCTP 990 Comments: A TCP endpoint locally only closes the connection for 991 sending; it may still receive data afterwards. 993 o Abort without delivering remaining data, causing an event 994 informing the application on the other side 995 Protocols: TCP, SCTP 996 Comments: In SCTP a reason can optionally be given by the 997 application on the aborting side, which can then be received by 998 the application on the other side. 1000 o Timeout event when data could not be delivered for too long 1001 Protocols: TCP, SCTP 1002 Comments: the timeout is configured with CONNECTION.MAINTENANCE 1003 "Change timeout for aborting connection (using retransmit limit or 1004 time value)". 1006 5.2. DATA Transfer Related Transport Service Features 1008 All features in this section refer to an existing connection, i.e. a 1009 connection that was either established or made available for 1010 receiving data. Reliable data transfer entails delay -- e.g. for the 1011 sender to wait until it can transmit data, or due to retransmission 1012 in case of packet loss. 1014 5.2.1. Sending Data 1016 All features in this section are provided by DATA.SEND from pass 2. 1017 DATA.SEND is given a data block from the application, which we here 1018 call a "message". 1020 o Reliably transfer data 1021 Protocols: TCP, SCTP 1023 o Message identification 1024 Protocols: SCTP 1026 o Choice of stream 1027 Protocols: SCTP 1029 o Choice of path (destination address) 1030 Protocols: SCTP 1032 o Message lifetime 1033 Protocols: SCTP 1035 o Choice between unordered (potentially faster) or ordered delivery 1036 of messages 1037 Protocols: SCTP 1039 o Request not to bundle messages 1040 Protocols: SCTP 1042 o Specifying a "payload protocol-id" (handed over as such by the 1043 receiver) 1044 Protocols: SCTP 1046 5.2.2. Receiving Data 1048 All features in this section are provided by DATA.RECEIVE from pass 1049 2. DATA.RECEIVE fills a buffer provided to the application, with 1050 what we here call a "message". 1052 o Receive data 1053 Protocols: TCP, SCTP 1055 o Choice of stream to receive from 1056 Protocols: SCTP 1058 o Message identification 1059 Protocols: SCTP 1060 Comments: In SCTP, this is optionally achieved with a "stream 1061 sequence number". The stream sequence number is always provided 1062 in case of partial message arrival. 1064 o Information about partial message arrival 1065 Protocols: SCTP 1066 Comments: In SCTP, partial messages are combined with a stream 1067 sequence number so that the application can restore the correct 1068 order of data blocks an entire message consists of. 1070 5.2.3. Errors 1072 This section describes sending failures that are associated with a 1073 specific call to DATA.SEND from pass 2. 1075 o Notification of unsent messages 1076 Protocols: SCTP 1078 o Notification of unacknowledged messages 1079 Protocols: SCTP 1081 6. Acknowledgements 1083 The authors would like to thank (in alphabetical order) Bob Briscoe, 1084 David Hayes, Gorry Fairhurst, Karen Nielsen and Joe Touch for 1085 providing valuable feedback on this document. Special thanks goes 1086 also to Christoph Paasch for providing input related to Multipath 1087 TCP. This work has received funding from the European Union's 1088 Horizon 2020 research and innovation programme under grant agreement 1089 No. 644334 (NEAT). The views expressed are solely those of the 1090 author(s). 1092 7. IANA Considerations 1094 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 1096 This memo includes no request to IANA. 1098 8. Security Considerations 1100 Security will be considered in future versions of this document. 1102 9. References 1104 9.1. Normative References 1106 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1107 RFC 793, DOI 10.17487/RFC0793, September 1981, 1108 . 1110 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1111 Communication Layers", STD 3, RFC 1122, 1112 DOI 10.17487/RFC1122, October 1989, 1113 . 1115 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1116 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1117 . 1119 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 1120 RFC 5482, DOI 10.17487/RFC5482, March 2009, 1121 . 1123 9.2. Informative References 1125 [FA15] Fairhurst, Ed., G., Trammell, Ed., B., and M. Kuehlewind, 1126 Ed., "Services provided by IETF transport protocols and 1127 congestion control mechanisms", Internet-draft draft- 1128 fairhurst-taps-transports-08.txt, December 2015. 1130 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 1131 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 1132 1983, . 1134 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1135 Requirement Levels", BCP 14, RFC 2119, 1136 DOI 10.17487/RFC2119, March 1997, 1137 . 1139 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 1140 of Explicit Congestion Notification (ECN) to IP", 1141 RFC 3168, DOI 10.17487/RFC3168, September 2001, 1142 . 1144 [RFC3260] Grossman, D., "New Terminology and Clarifications for 1145 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 1146 . 1148 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., Ed., 1149 and G. Fairhurst, Ed., "The Lightweight User Datagram 1150 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, July 1151 2004, . 1153 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 1154 DOI 10.17487/RFC5461, February 2009, 1155 . 1157 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 1158 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 1159 January 2011, . 1161 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 1162 Iyengar, "Architectural Guidelines for Multipath TCP 1163 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 1164 . 1166 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1167 Yasevich, "Sockets API Extensions for the Stream Control 1168 Transmission Protocol (SCTP)", RFC 6458, 1169 DOI 10.17487/RFC6458, December 2011, 1170 . 1172 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1173 "TCP Extensions for Multipath Operation with Multiple 1174 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1175 . 1177 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 1178 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 1179 March 2013, . 1181 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 1182 Zimmermann, "A Roadmap for Transmission Control Protocol 1183 (TCP) Specification Documents", RFC 7414, 1184 DOI 10.17487/RFC7414, February 2015, 1185 . 1187 Appendix A. Overview of RFCs used as input for pass 1 1189 TCP: [RFC0793], [RFC1122], [RFC5482] 1190 MPTCP: [RFC6182], [RFC6824], [RFC6897] 1191 SCTP: [RFC4960], planned: [RFC6458] 1193 Appendix B. How to contribute 1195 This document is only concerned with transport service features that 1196 are explicitly exposed to applications via primitives. It also 1197 strictly follows RFC text: if a feature is truly relevant for an 1198 application, the RFCs better say so and in some way describe how to 1199 use and configure it. Thus, the approach to follow for contributing 1200 to this document is to identify the right RFCs, then analyze and 1201 process their text. 1203 Experimental RFCs are excluded, and so are primitives that MAY be 1204 implemented (by the transport protocol). To be included, the minimum 1205 requirement level for a primitive to be implemented by a protocol is 1206 SHOULD. If [RFC2119]-style requirements levels are not used, 1207 primitives should be excluded when they are described in conjunction 1208 with statements like, e.g.: "some implementations also provide" or 1209 "an implementation may also". Briefly describe excluded primitives 1210 in a subsection called "excluded primitives". 1212 Pass 1: Identify text that talks about primitives. An API 1213 specification, abstract or not, obviously describes primitives -- but 1214 note that we are not *only* interested in API specifications. The 1215 text describing the 'send' primitive in the API specified in 1216 [RFC0793], for instance, does not say that data transfer is reliable. 1217 TCP's reliability is clear, however, from this text in Section 1 of 1218 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 1219 use as a highly reliable host-to-host protocol between hosts in 1220 packet-switched computer communication networks, and in 1221 interconnected systems of such networks." 1223 For the new pass 1 subsection about the protocol you're describing, 1224 it is recommendable to begin by copy+pasting all the relevant text 1225 parts from the relevant RFCs, then adjust terminology to match the 1226 terminology in Section 1 and adjust (shorten!) phrasing to match the 1227 general style of the document. Try to formulate everything as a 1228 primitive description to make the primitive description as complete 1229 as possible (e.g., the "SEND.TCP" primitive in pass 2 is explicitly 1230 described as reliably transferring data); if there is text that is 1231 relevant for the primitives presented in this pass but still does not 1232 fit directly under any primitive, use it as an introduction for your 1233 subsection. However, do note that document length is a concern and 1234 all the protocols and their services / features are already described 1235 in [FA15]. 1237 Pass 2: The main goal of this pass is unification of primitives. As 1238 input, use your own text from Pass 1, no exterior sources. If you 1239 find that something is missing there, fix the text in Pass 1. The 1240 list in pass 2 is not done by protocol ("first protocol X, here are 1241 all the primitives; then protocol Y, here are all the primitives, 1242 ..") but by primitive ("primitive A, implemented this way in protocol 1243 X, this way in protocol Y, ..."). We want as many similar pass 2 1244 primitives as possible. This can be achieved, for instance, by not 1245 always maintaining a 1:1 mapping between pass 1 and pass 2 1246 primitives, renaming primitives etc. Please consider the primitives 1247 that are already there and try to make the ones of the protocol you 1248 are describing as much in line with the already existing ones as 1249 possible. In other words, we would rather have a primitive with new 1250 parameters than a new primitive that allows to send in a particular 1251 way. 1253 Please make primitives fit within the already existing categories and 1254 subcategories. For each primitive, please follow the style: 1256 o PRIMITIVENAME.PROTOCOL: 1257 Pass 1 primitive / event: 1258 Parameters: 1259 Returns: 1260 Comments: 1262 The entries "Parameters", "Returns" and "Comments" may be skipped if 1263 a primitive has no parameters, no described return value or no 1264 comments seem necessary, respectively. Optional parameters must be 1265 followed by "(optional)". If a default value is known, provide it 1266 too. 1268 Pass 3: the main point of this pass is to identify features that are 1269 the result of static properties of protocols, for which all protocols 1270 have to be listed together; this is then the final list of all 1271 available features. For this, we need a list of features per 1272 category (similar categories as in pass 2) along with the protocol 1273 supporting it. This should be primarily based on text from pass 2 as 1274 input, but text from pass 1 can also be used. Do not use external 1275 sources. 1277 Appendix C. Revision information 1279 XXX RFC-Ed please remove this section prior to publication. 1281 -00 (from draft-welzl-taps-transports): this now covers TCP based on 1282 all TCP RFCs (this means: if you know of something in any TCP RFC 1283 that you think should be addressed, please speak up!) as well as 1284 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 1285 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 1286 in line with [FA15]. Addressed comments by Karen Nielsen and Gorry 1287 Fairhurst; various other fixes. Appendices (TCP overview and how-to- 1288 contribute) added. 1290 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 1291 [RFC6897]. 1293 Authors' Addresses 1295 Michael Welzl 1296 University of Oslo 1297 PO Box 1080 Blindern 1298 Oslo N-0316 1299 Norway 1301 Phone: +47 22 85 24 20 1302 Email: michawe@ifi.uio.no 1304 Michael Tuexen 1305 Muenster University of Applied Sciences 1306 Stegerwaldstrasse 39 1307 Steinfurt 48565 1308 Germany 1310 Email: tuexen@fh-muenster.de 1312 Naeem Khademi 1313 University of Oslo 1314 PO Box 1080 Blindern 1315 Oslo N-0316 1316 Norway 1318 Email: naeemk@ifi.uio.no