idnits 2.17.1 draft-ietf-taps-transports-usage-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 11 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 31, 2016) is 2734 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 606, but not defined == Unused Reference: 'RFC2119' is defined on line 1510, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-tsvwg-rfc5405bis-07 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) == Outdated reference: A later version (-14) exists of draft-ietf-taps-transports-12 -- Obsolete informational reference (is this intentional?): RFC 6093 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 6824 (Obsoleted by RFC 8684) -- Obsolete informational reference (is this intentional?): RFC 7053 (Obsoleted by RFC 9260) Summary: 2 errors (**), 0 flaws (~~), 7 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: May 4, 2017 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 October 31, 2016 10 On the Usage of Transport Service Features Provided by IETF Transport 11 Protocols 12 draft-ietf-taps-transports-usage-02 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 May 4, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . . 5 58 3.1.1. Excluded Primitives or Parameters . . . . . . . . . . 7 59 3.2. Primitives Provided by MPTCP . . . . . . . . . . . . . . . 8 60 3.3. Primitives Provided by SCTP . . . . . . . . . . . . . . . 9 61 3.3.1. Excluded Primitives or Parameters . . . . . . . . . . 13 62 3.4. Primitives Provided by UDP and UDP-Lite . . . . . . . . . 14 63 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 64 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 14 65 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . . 23 66 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 67 5.1. CONNECTION Related Transport Service Features . . . . . . 25 68 5.2. DATA Transfer Related Transport Service Features . . . . . 30 69 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . . 30 70 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . . 31 71 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . 31 72 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 32 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32 76 9.1. Normative References . . . . . . . . . . . . . . . . . . . 32 77 9.2. Informative References . . . . . . . . . . . . . . . . . . 33 78 Appendix A. Overview of RFCs used as input for pass 1 . . . . . . 35 79 Appendix B. How to contribute . . . . . . . . . . . . . . . . . . 36 80 Appendix C. Revision information . . . . . . . . . . . . . . . . 37 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 83 1. Terminology 85 Transport Service Feature: a specific end-to-end feature that a 86 transport service provides to its clients. Examples include 87 confidentiality, reliable delivery, ordered delivery, message- 88 versus-stream orientation, etc. 89 Transport Service: a set of transport service features, without an 90 association to any given framing protocol, which provides a 91 complete service to an application. 92 Transport Protocol: an implementation that provides one or more 93 different transport services using a specific framing and header 94 format on the wire. 95 Transport Protocol Component: an implementation of a transport 96 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. 115 Transport Address: the combination of an IP address, transport 116 protocol and the port number used by the transport protocol. 118 2. Introduction 120 This document presents defined interactions between transport 121 protocols and applications in the form of 'primitives' (function 122 calls). Primitives can be invoked by an application or a transport 123 protocol; the latter type is called an "event". The list of 124 transport service features and primitives in this document is 125 strictly based on the parts of protocol specifications that relate to 126 what the protocol provides to an application using it and how the 127 application interacts with it. It does not cover parts of a protocol 128 that are explicitly stated as optional to implement. 130 The document presents a three-pass process to arrive at a list of 131 transport service features. In the first pass, the relevant RFC text 132 is discussed per protocol. In the second pass, this discussion is 133 used to derive a list of primitives that are uniformly categorized 134 across protocols. Here, an attempt is made to present or -- where 135 text describing primitives does not yet exist -- construct primitives 136 in a slightly generalized form to highlight similarities. This is, 137 for example, achieved by renaming primitives of protocols or by 138 avoiding a strict 1:1-mapping between the primitives in the protocol 139 specification and primitives in the list. Finally, the third pass 140 presents transport service features based on pass 2, identifying 141 which protocols implement them. 143 In the list resulting from the second pass, some transport service 144 features are missing because they are implicit in some protocols, and 145 they only become explicit when we consider the superset of all 146 features offered by all protocols. For example, TCP's reliability 147 includes integrity via a checksum, but we have to include a protocol 148 like UDP-Lite as specified in [RFC3828] (which has a configurable 149 checksum) in the list before we can consider an always-on checksum as 150 a transport service feature. Similar arguments apply to other 151 protocol functions (e.g. congestion control). The complete list of 152 features across all protocols is therefore only available after pass 153 3. 155 This document discusses unicast transport protocols. [AUTHOR'S NOTE: 156 we skip "congestion control mechanisms" for now. This simplifies the 157 discussion; the congestion control mechanisms part is about LEDBAT, 158 which should be easy to add later.] Transport protocols provide 159 communication between processes that operate on network endpoints, 160 which means that they allow for multiplexing of communication between 161 the same IP addresses, and normally this multiplexing is achieved 162 using port numbers. Port multiplexing is therefore assumed to be 163 always provided and not discussed in this document. 165 Some protocols are connection-oriented. Connection-oriented 166 protocols often use an initial call to a specific transport primitive 167 to open a connection before communication can progress, and require 168 communication to be explicitly terminated by issuing another call to 169 a transport primitive (usually called "close"). A "connection" is 170 the common state that some transport primitives refer to, e.g., to 171 adjust general configuration settings. Connection establishment, 172 maintenance and termination are therefore used to categorize 173 transport primitives of connection-oriented transport protocols in 174 pass 2 and pass 3. 176 3. Pass 1 178 This first iteration summarizes the relevant text parts of the RFCs 179 describing the protocols, focusing on what each transport protocol 180 provides to the application and how it is used (abstract API 181 descriptions, where they are available). 183 3.1. Primitives Provided by TCP 185 [RFC0793] states: "The Transmission Control Protocol (TCP) is 186 intended for use as a highly reliable host-to-host protocol between 187 hosts in packet-switched computer communication networks, and in 188 interconnected systems of such networks". Section 3.8 in [RFC0793] 189 further specifies the interaction with the application by listing 190 several transport primitives. It is also assumed that an Operating 191 System provides a means for TCP to asynchronously signal the 192 application; the primitives representing such signals are called 193 'events' in this section. This section describes the relevant 194 primitives. 196 open: this is either active or passive, to initiate a connection or 197 listen for incoming connections. All other primitives are 198 associated with a specific connection, which is assumed to first 199 have been opened. An active open call contains a socket. A 200 passive open call with a socket waits for a particular connection; 201 alternatively, a passive open call can leave the socket 202 unspecified to accept any incoming connection. A fully specified 203 passive call can later be made active by calling 'send'. 204 Optionally, a timeout can be specified, after which TCP will abort 205 the connection if data has not been successfully delivered to the 206 destination (else a default timeout value is used). [RFC1122] 207 describes a procedure for aborting the connection that must be 208 used to avoid excessive retransmissions, and states that an 209 application must be able to control the threshold used to 210 determine the condition for aborting -- and that this threshold 211 may be measured in time units or as a count of retransmission. 212 This indicates that the timeout could also be specified as a count 213 of retransmission. 215 Also optional, for multihomed hosts, the local IP address can be 216 provided [RFC1122]. If it is not provided, a default choice will 217 be made in case of active open calls. A passive open call will 218 await incoming connection requests to all local addresses and then 219 maintain usage of the local IP address where the incoming 220 connection request has arrived. Finally, the 'options' parameter 221 is explained in [RFC1122] to allow the application to specify IP 222 options such as source route, record route, or timestamp. It is 223 not stated on which segments of a connection these options should 224 be applied, but probably all segments, as this is also stated in a 225 specification given for the usage of source route (section 4.2.3.8 226 of [RFC1122]). Source route is the only non-optional IP option in 227 this parameter, allowing an application to specify a source route 228 when it actively opens a TCP connection. 230 send: this is the primitive that an application uses to give the 231 local TCP transport endpoint a number of bytes that TCP should 232 reliably send to the other side of the connection. The URGENT 233 flag, if set, states that the data handed over by this send call 234 is urgent and this urgency should be indicated to the receiving 235 process in case the receiving application has not yet consumed all 236 non-urgent data preceding it. An optional timeout parameter can 237 be provided that updates the connection's timeout (see 'open'). 239 receive: This primitive allocates a receiving buffer for a provided 240 number of bytes. It returns the number of received bytes provided 241 in the buffer when these bytes have been received and written into 242 the buffer by TCP. The application is informed of urgent data via 243 an URGENT flag: if it is on, there is urgent data. If it is off, 244 there is no urgent data or this call to 'receive' has returned all 245 the urgent data. 247 close: This primitive closes one side of a connection. It is 248 semantically equivalent to "I have no more data to send" but does 249 not mean "I will not receive any more", as the other side may 250 still have data to send. This call reliably delivers any data 251 that has already been given to TCP (and if that fails, 'close' 252 becomes 'abort'). 254 abort: This primitive causes all pending 'send' and 'receive' calls 255 to be aborted. A TCP RESET message is sent to the TCP endpoint on 256 the other side of the connection [RFC0793]. 258 close event: TCP uses this primitive to inform an application that 259 the application on the other side has called the 'close' 260 primitive, so the local application can also issue a 'close' and 261 terminate the connection gracefully. See [RFC0793], Section 3.5. 263 abort event: When TCP aborts a connection upon receiving a "Reset" 264 from the peer, it "advises the user and goes to the CLOSED state." 265 See [RFC0793], Section 3.4. 267 USER TIMEOUT event: This event, described in Section 3.9 of 268 [RFC0793], is executed when the user timeout expires (see 'open'). 269 All queues are flushed and the application is informed that the 270 connection had to be aborted due to user timeout. 272 ERROR_REPORT event: This event, described in Section 4.2.4.1 of 273 [RFC1122], informs the application of "soft errors" that can be 274 safely ignored [RFC5461], including the arrival of an ICMP error 275 message or excessive retransmissions (reaching a threshold below 276 the threshold where the connection is aborted). 278 Type-of-Service: Section 4.2.4.2 of [RFC1122] states that the 279 application layer MUST be able to specify the Type-of-Service 280 (TOS) for segments that are sent on a connection. The application 281 should be able to change the TOS during the connection lifetime, 282 and the TOS value should be passed to the IP layer unchanged. 283 Since then the TOS field has been redefined. A part of the field 284 has been assigned to ECN [RFC3168] and the six most significant 285 bits have been assigned to carry the DiffServ CodePoint, DSField 286 [RFC3260]. Staying with the intention behind the application's 287 ability to specify the "Type of Service", this should probably be 288 interpreted to mean the value in the DSField, which is the 289 Differentiated Services Codepoint (DSCP). 291 Nagle: The Nagle algorithm, described in Section 4.2.3.4 of 292 [RFC1122], delays sending data for some time to increase the 293 likelihood of sending a full-sized segment. An application can 294 disable the Nagle algorithm for an individual connection. 296 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 297 one end of a TCP connection to advertise its current user timeout 298 value so that the other end of the TCP connection can adapt its 299 own user timeout accordingly. In addition to the configurable 300 value of the User Timeout (see 'send'), [RFC5482] introduces three 301 per-connection state variables that an application can adjust to 302 control the operation of the User Timeout Option (UTO): ADV_UTO is 303 the value of the UTO advertised to the remote TCP peer (default: 304 system-wide default user timeout); ENABLED (default false) is a 305 boolean-type flag that controls whether the UTO option is enabled 306 for a connection. This applies to both sending and receiving. 307 CHANGEABLE is a boolean-type flag (default true) that controls 308 whether the user timeout may be changed based on a UTO option 309 received from the other end of the connection. CHANGEABLE becomes 310 false when an application explicitly sets the user timeout (see 311 'send'). 313 3.1.1. Excluded Primitives or Parameters 315 The 'open' primitive specified in [RFC0793] can be handed optional 316 Precedence or security/compartment information according to 317 [RFC0793], but this was not included here because it is mostly 318 irrelevant today, as explained in [RFC7414]. 320 The 'status' primitive was not included because [RFC0793] describes 321 this primitive as "implementation dependent" and states that it 322 "could be excluded without adverse effect". Moreover, while a data 323 block containing specific information is described, it is also stated 324 that not all of this information may always be available. The 'send' 325 primitive described in [RFC0793] includes an optional PUSH flag 326 which, if set, requires data to be promptly transmitted to the 327 receiver without delay; the 'receive' primitive described in 328 [RFC0793] can (under some conditions) yield the status of the PUSH 329 flag. Because PUSH functionality is made optional to implement for 330 both the 'send' and 'receive' primitives in [RFC1122], this 331 functionality is not included here. [RFC1122] also introduces keep- 332 alives to TCP, but these are optional to implement and hence not 333 considered here. [RFC1122] describes that "some TCP implementations 334 have included a FLUSH call", indicating that this call is also 335 optional to implement. It is therefore not considered here. 337 3.2. Primitives Provided by MPTCP 339 Multipath TCP (MPTCP) is an extension to TCP that allows the use of 340 multiple paths for a single data-stream. It achieves this by 341 creating different so-called TCP subflows for each of the interfaces 342 and scheduling the traffic across these TCP subflows. The service 343 provided by MPTCP is described in [RFC6182] "Multipath TCP MUST 344 follow the same service model as TCP [RFC0793]: in- order, reliable, 345 and byte-oriented delivery. Furthermore, a Multipath TCP connection 346 SHOULD provide the application with no worse throughput or resilience 347 than it would expect from running a single TCP connection over any 348 one of its available paths." 350 Further, [RFC6182] states constraints on the API exposed by MPTCP: "A 351 multipath-capable equivalent of TCP MUST retain some level of 352 backward compatibility with existing TCP APIs, so that existing 353 applications can use the newer merely by upgrading the operating 354 systems of the end hosts." As such, the primitives provided by MPTCP 355 are equivalent to the ones provided by TCP. Nevertheless, [RFC6824] 356 and [RFC6897] clarify some parts of TCP's primitives with respect to 357 MPTCP and add some extensions for better control on MPTCP's subflows. 358 Hereafter is a list of the clarifications and extensions the above 359 cited RFCs provide to TCP's primitives. 361 open: [RFC6897] states "An application should be able to request to 362 turn on or turn off the usage of MPTCP.". The RFC states that 363 this functionality can be provided through a socket-option called 364 TCP_MULTIPATH_ENABLE. Further, [RFC6897] says that MPTCP must be 365 disabled in case the application is binding to a specific address. 367 send/receive: [RFC6824] states that the sending and receiving of 368 data does not require any changes to the application when MPTCP is 369 being used. The MPTCP-layer will "take one input data stream from 370 an application, and split it into one or more subflows, with 371 sufficient control information to allow it to be reassembled and 372 delivered reliably and in order to the recipient application." 373 The use of the Urgent-Pointer is special in MPTCP and [RFC6824] 374 says "a TCP subflow MUST NOT use the Urgent Pointer to interrupt 375 an existing mapping." 377 address and subflow management: MPTCP uses different addresses and 378 allows a host to announce these addresses as part of the protocol. 379 [RFC6897] says "An application should be able to restrict MPTCP to 380 binding to a given set of addresses." and thus allows applications 381 to limit the set of addresses that are being used by MPTCP. 382 Further, "An application should be able to obtain information on 383 the pairs of addresses used by the MPTCP subflows.". 385 3.3. Primitives Provided by SCTP 387 Section 1.1 of [RFC4960] lists limitations of TCP that SCTP removes. 388 Three of the four mentioned limitations directly translate into a 389 transport service features that are visible to an application using 390 SCTP: 1) it allows for preservation of message delineations; 2) these 391 messages, while reliably transferred, do not require to be in order 392 unless the application wants it; 3) multi-homing is supported. In 393 SCTP, connections are called "association" and they can be between 394 not only two (as in TCP) but multiple addresses at each endpoint. 396 Section 10 of [RFC4960] further specifies the interaction with the 397 application (which RFC [RFC4960] calls the "Upper Layer Protocol" 398 (ULP)). It is assumed that the Operating System provides a means for 399 SCTP to asynchronously signal the application; the primitives 400 representing such signals are called 'events' in this section. Here, 401 we describe the relevant primitives. In addition to the abstract API 402 described in Section 10 of [RFC4960], an extension to the socket API 403 is described in [RFC6458] covering the functionality of the base 404 protocol specified in [RFC4960] and its extensions specified in 405 [RFC3758], [RFC4895], and [RFC5061]. For the protocol extensions 406 specified in [RFC6525], [RFC6951], [RFC7053], [RFC7496], and 407 [RFC7829] the corresponding extensions of the socket API are 408 specified in these protocol specifications. The functionality 409 exposed to the ULP through this socket API is considered here in 410 addition to the abstract API specified in Section 10 of [RFC4960]. 412 Initialize: Initialize creates a local SCTP instance that it binds 413 to a set of local addresses (and, if provided, port number). 414 Initialize needs to be called only once per set of local 415 addresses. 417 Associate: This creates an association (the SCTP equivalent of a 418 connection) between the local SCTP instance and a remote SCTP 419 instance. Most primitives are associated with a specific 420 association, which is assumed to first have been created. 421 Associate can return a list of destination transport addresses so 422 that multiple paths can later be used. One of the returned 423 sockets will be selected by the local endpoint as default primary 424 path for sending SCTP packets to this peer, but this choice can be 425 changed by the application using the list of destination 426 addresses. Associate is also given the number of outgoing streams 427 to request and optionally returns the number of outgoing streams 428 negotiated. An optional parameter of 32-bits, the adaptation 429 layer indication, can be provided, as specified in [RFC5061]. If 430 the extension specified in [RFC4895] is used, the chunk types 431 required to be sent authenticated by the peer can be provided. 433 Send: This sends a message of a certain length in bytes over an 434 association. A number can be provided to later refer to the 435 correct message when reporting an error, and a stream id is 436 provided to specify the stream to be used inside an association 437 (we consider this as a mandatory parameter here for simplicity: if 438 not provided, the stream id defaults to 0). A condition to 439 abandon the message can be specified (for example limiting the 440 number of retransmissions or the lifetime of the user message). 441 This allows to control the partial reliability extension specified 442 in [RFC3758] and [RFC7496]. An optional maximum life time can 443 specify the time after which the message should be discarded 444 rather than sent. A choice (advisory, i.e. not guaranteed) of the 445 preferred path can be made by providing a socket, and the message 446 can be delivered out-of-order if the unordered flag is set. An 447 advisory flag indicates that the peer should not delay the 448 acknowledgement of the user message provided by making use of the 449 I-bit specified in [RFC7053]. Another advisory flag indicates 450 whether the application prefers to avoid bundling user data with 451 other outbound DATA chunks (i.e., in the same packet). A payload 452 protocol-id can be provided to pass a value that indicates the 453 type of payload protocol data to the peer. If the extension 454 specified in [RFC4895] is used, the key identifier used for 455 authenticating the DATA chunks can be provided. 457 Receive: Messages are received from an association, and optionally a 458 stream within the association, with their size returned. The 459 application is notified of the availability of data via a DATA 460 ARRIVE notification. If the sender has included a payload 461 protocol-id, this value is also returned. If the received message 462 is only a partial delivery of a whole message, a partial flag will 463 indicate so, in which case the stream id and a stream sequence 464 number are provided to the application. A delivery number lets 465 the application detect reordering. 467 Shutdown: This primitive gracefully closes an association, reliably 468 delivering any data that has already been handed over to SCTP. A 469 return code informs about success or failure of this procedure. 471 Abort: This ungracefully closes an association, by discarding any 472 locally queued data and informing the peer that the association 473 was aborted. Optionally, an abort reason to be passed to the peer 474 may be provided by the application. A return code informs about 475 success or failure of this procedure. 477 Change Heartbeat / Request Heartbeat: This allows the application to 478 enable/disable heartbeats and optionally specify a heartbeat 479 frequency as well as requesting a single heartbeat to be carried 480 out upon a function call, with a notification about success or 481 failure of transmitting the HEARTBEAT chunk to the destination. 483 Set Protocol Parameters: This allows to set values for protocol 484 parameters per association; for some parameters, a setting can be 485 made per socket. The set listed in [RFC4960] is: RTO.Initial; 486 RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; RTO.Beta; 487 Valid.Cookie.Life; Association.Max.Retrans; Path.Max.Retrans; 488 Max.Init.Retransmits; HB.interval; HB.Max.Burst. In addition to 489 these, the Quick Failover Algorithm specified in [RFC7829] can be 490 controlled by the PotentiallyFailed.Max.Retrans and 491 Primary.Switchover.Max.Retrans parameter. A remote UDP 492 encapsulation port can be set for using UDP encapsulation as 493 specified in [RFC6951]. 495 Set Primary: This allows to set a new primary default path for an 496 association by providing a socket. Optionally, a default source 497 address to be used in IP datagrams can be provided. 499 Set / Get Authentication Parameters: This allows an endpoint to add/ 500 remove key material to/from an association. In addition, the 501 chunk types being authenticated can be queried. This is provided 502 by the protocol extension defined in [RFC4895]. 504 Change Local Address / Set Peer Primary: This allows an endpoint to 505 add/remove local addresses to/from an association. In addition, 506 the peer can be given a hint which address to use as the primary 507 address. This is provided by the protocol extension defined in 508 [RFC5061]. 510 Add / Reset Streams, Reset Association: This allows an endpoint to 511 add streams to an existing association or or to reset them 512 individually. Additionally, the association can be reset. This 513 is provided by the protocol extension defined in [RFC6525]. 515 Status: The 'Status' primitive returns a data block with information 516 about a specified association, containing: association connection 517 state; socket list; destination transport address reachability 518 states; current receiver window size; current congestion window 519 sizes; number of unacknowledged DATA chunks; number of DATA chunks 520 pending receipt; primary path; most recent SRTT on primary path; 521 RTO on primary path; SRTT and RTO on other destination addresses. 523 COMMUNICATION UP notification: When a lost communication to an 524 endpoint is restored or when SCTP becomes ready to send or receive 525 user messages, this notification informs the application process 526 about the affected association, the type of event that has 527 occurred, the complete set of sockets of the peer, the maximum 528 number of allowed streams and the inbound stream count (the number 529 of streams the peer endpoint has requested). 531 DATA ARRIVE notification: When a message is ready to be retrieved 532 via the Receive primitive, the application is informed by this 533 notification. 535 SEND FAILURE notification / Receive Unsent Message / Receive 536 Unacknowledged Message: When a message cannot be delivered via an 537 association, the sender can be informed about it and learn whether 538 the message has just not been acknowledged or (e.g. in case of 539 lifetime expiry) if it has not even been sent. 541 NETWORK STATUS CHANGE notification: The NETWORK STATUS CHANGE 542 notification informs the application about a socket becoming 543 active/inactive. 545 COMMUNICATION LOST notification: When SCTP loses communication to an 546 endpoint (e.g. via Heartbeats or excessive retransmission) or 547 detects an abort, this notification informs the application 548 process of the affected association and the type of event (failure 549 OR termination in response to a shutdown or abort request). 551 SHUTDOWN COMPLETE notification: When SCTP completes the shutdown 552 procedures, this notification is passed to the upper layer, 553 informing it about the affected assocation. 555 AUTHENICATION notification: When SCTP wants to notify the upper 556 layer regarding the key management related to the extension 557 defined in [RFC4895], this notification is passed to the upper 558 layer. 560 ADAPTATION LAYER INDICATION notification: When SCTP completes the 561 association setup and the peer provided an adaptation layer 562 indication, this is passed to the upper layer. This extension is 563 defined in [RFC5061] and [RFC6458]. 565 STREAM RESET notification: When SCTP completes the procedure for 566 resetting streams as specified in [RFC6525], this notification is 567 passed to the upper layer, informing it about the result. 569 ASSOCIATION RESET notification: When SCTP completes the association 570 reset procedure as specified in [RFC6525], this notification is 571 passed to the upper layer, informing it about the result. 573 STREAM CHANGE notification: When SCTP completes the procedure used 574 to increase the number of streams as specified in [RFC6525], this 575 notification is passed to the upper layer, informing it about the 576 result. 578 3.3.1. Excluded Primitives or Parameters 580 The 'Receive' primitive can return certain additional information, 581 but this is optional to implement and therefore not considered. With 582 a COMMUNICATION LOST notification, some more information may 583 optionally be passed to the application (e.g., identification to 584 retrieve unsent and unacknowledged data). SCTP "can invoke" a 585 COMMUNICATION ERROR notification and "may send" a RESTART 586 notification, making these two notifications optional to implement. 587 The list provided under 'Status' includes "etc", indicating that more 588 information could be provided. The primitive 'Get SRTT Report' 589 returns information that is included in the information that 'Status' 590 provides and is therefore not discussed. Similarly, 'Set Failure 591 Threshold' sets only one out of various possible parameters included 592 in 'Set Protocol Parameters'. The 'Destroy SCTP Instance' API 593 function was excluded: it erases the SCTP instance that was created 594 by 'Initialize', but is not a Primitive as defined in this document 595 because it does not relate to a Transport Service Feature. 597 3.4. Primitives Provided by UDP and UDP-Lite 599 The primitives provided by UDP and UDP-Lite are described in [FJ16]. 601 4. Pass 2 603 This pass categorizes the primitives from pass 1 based on whether 604 they relate to a connection or to data transmission. Primitives are 605 presented following the nomenclature 606 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". The CATEGORY can be 607 CONNECTION or DATA. Within the CONNECTION category, ESTABLISHMENT, 608 AVAILABILITY, MAINTENANCE and TERMINATION subcategories can be 609 considered. The DATA category does not have any SUBCATEGORY (as of 610 now). The PROTOCOL name "UDP(-Lite)" is used when primitives are 611 equivalent for UDP and UDP-Lite; the PROTOCOL name "TCP" refers to 612 both TCP and MPTCP. We present "connection" as a general protocol- 613 independent concept and use it to refer to, e.g., TCP connections 614 (identifiable by a unique pair of IP addresses and TCP port numbers), 615 SCTP associations (identifiable by multiple IP address and port 616 number pairs), as well UDP and UDP-Lite connections (identifiable by 617 a unique socket pair). 619 Some minor details are omitted for the sake of generalization -- 620 e.g., SCTP's 'close' [RFC4960] returns success or failure, whereas 621 this is not described in the same way for TCP in [RFC0793], but this 622 detail plays no significant role for the primitives provided by 623 either TCP or SCTP. 625 The TCP 'send' and 'receive' primitives include usage of an "URGENT" 626 mechanism. This mechanism is required to implement the "synch 627 signal" used by telnet [RFC0854], but SHOULD NOT be used by new 628 applications [RFC6093]. Because pass 2 is meant as a basis for the 629 creation of TAPS systems, the "URGENT" mechanism is excluded. This 630 also concerns the notification "Urgent pointer advance" in the 631 ERROR_REPORT described in Section 4.2.4.1 of [RFC1122]. 633 4.1. CONNECTION Related Primitives 635 ESTABLISHMENT: 636 Active creation of a connection from one transport endpoint to one or 637 more transport endpoints. 638 Interfaces to UDP and UDP-Lite allow both connection-oriented and 639 connection-less usage of the API [I-D.ietf-tsvwg-rfc5405bis] 641 o CONNECT.TCP: 642 Pass 1 primitive / event: 'open' (active) or 'open' (passive) with 643 socket, followed by 'send' 644 Parameters: 1 local IP address (optional); 1 destination transport 645 address (for active open; else the socket and the local IP address 646 of the succeeding incoming connection request will be maintained); 647 timeout (optional); options (optional) 648 Comments: If the local IP address is not provided, a default 649 choice will automatically be made. The timeout can also be a 650 retransmission count. The options are IP options to be used on 651 all segments of the connection. At least the Source Route option 652 is mandatory for TCP to provide. 654 o CONNECT.SCTP: 655 Pass 1 primitive / event: 'initialize', followed by 'associate' 656 Parameters: list of local SCTP port number / IP address pairs 657 (initialize); 1 socket; outbound stream count; adaptation layer 658 indication; chunk types required to be authenticated 659 Returns: socket list 660 Comments: 'initialize' needs to be called only once per list of 661 local SCTP port number / IP address pairs. One socket will 662 automatically be chosen; it can later be changed in MAINTENANCE. 664 o CONNECT.MPTCP: 665 This is similar to CONNECT.TCP except for one additional boolean 666 parameter that allows to enable or disable MPTCP for a particular 667 connection or socket (default: enabled). 669 o CONNECT.UDP(-Lite): 670 Pass 1 primitive / event: 'connect' followed by 'send'. 671 Parameters: 1 local IP address (default (ANY), or specified); 1 672 destination transport address; 1 local port (default (OS chooses), 673 or specified); 1 destination port (default (OS chooses), or 674 specified). 675 Comments: Associates a transport address creating a UDP(-Lite) 676 socket connection. This can be called again with a new transport 677 address to create a new connection. The CONNECT function allows 678 an application to receive errors from messages sent to a transport 679 address. 681 AVAILABILITY: 682 Preparing to receive incoming connection requests. 684 o LISTEN.TCP: 685 Pass 1 primitive / event: 'open' (passive) 686 Parameters: 1 local IP address (optional); 1 socket (optional); 687 timeout (optional) 688 Comments: if the socket and/or local IP address is provided, this 689 waits for incoming connections from only and/or to only the 690 provided address. Else this waits for incoming connections 691 without this / these constraint(s). ESTABLISHMENT can later be 692 performed with 'send'. 694 o LISTEN.SCTP: 695 Pass 1 primitive / event: 'initialize', followed by 'COMMUNICATION 696 UP' notification and possibly 'ADAPTATION LAYER' notification 697 Parameters: list of local SCTP port number / IP address pairs 698 (initialize) 699 Returns: socket list; outbound stream count; inbound stream count; 700 adaptation layer indication; chunks required to be authenticated 701 Comments: initialize needs to be called only once per list of 702 local SCTP port number / IP address pairs. COMMUNICATION UP can 703 also follow a COMMUNICATION LOST notification, indicating that the 704 lost communication is restored. If the peer has provided an 705 adaptation layer indication, an 'ADAPTATION LAYER' notification is 706 issued. 708 o LISTEN.MPTCP: 709 This is similar to LISTEN.TCP except for one additional boolean 710 parameter that allows to enable or disable MPTCP for a particular 711 connection or socket (default: enabled). 713 o LISTEN.UDP(-Lite): 714 Pass 1 primitive / event: 'receive'. 715 Parameters: 1 local IP address (default (ANY), or specified); 1 716 destination transport address; local port (default (OS chooses), 717 or specified); destination port (default (OS chooses), or 718 specified). 719 Comments: The receive function registers the application to listen 720 for incoming UDP(-Lite) datagrams at an endpoint. 722 MAINTENANCE: 723 Adjustments made to an open connection, or notifications about it. 724 These are out-of-band messages to the protocol that can be issued at 725 any time, at least after a connection has been established and before 726 it has been terminated (with one exception: CHANGE-TIMEOUT.TCP can 727 only be issued for an open connection when DATA.SEND.TCP is called). 728 In some cases, these primitives can also be immediately issued during 729 ESTABLISHMENT or AVAILABILITY, without waiting for the connection to 730 be opened (e.g. CHANGE-TIMEOUT.TCP can be done using TCP's 'open' 731 primitive). For UDP and UDP-Lite, these functions may establish a 732 setting per connection, but may also be changed per datagram message. 734 o CHANGE-TIMEOUT.TCP: 735 Pass 1 primitive / event: 'open' or 'send' combined with 736 unspecified control of per-connection state variables 737 Parameters: timeout value (optional); ADV_UTO (optional); boolean 738 UTO_ENABLED (optional, default false); boolean CHANGEABLE 739 (optional, default true) 740 Comments: when sending data, an application can adjust the 741 connection's timeout value (time after which the connection will 742 be aborted if data could not be delivered). If UTO_ENABLED is 743 true, the user timeout value (or, if provided, the value ADV_UTO) 744 will be advertised for the TCP on the other side of the connection 745 to adapt its own user timeout accordingly. UTO_ENABLED controls 746 whether the UTO option is enabled for a connection. This applies 747 to both sending and receiving. CHANGEABLE controls whether the 748 user timeout may be changed based on a UTO option received from 749 the other end of the connection; it becomes false when 'timeout 750 value' is used. 752 o CHANGE-TIMEOUT.SCTP: 753 Pass 1 primitive / event: 'Change HeartBeat' combined with 'Set 754 Protocol Parameters' 755 Parameters: 'Change HeartBeat': heartbeat frequency; 'Set Protocol 756 Parameters': Association.Max.Retrans (whole association) or 757 Path.Max.Retrans (per socket) 758 Comments: Change Heartbeat can enable / disable heartbeats in SCTP 759 as well as change their frequency. The parameter 760 Association.Max.Retrans defines after how many unsuccessful 761 heartbeats the connection will be terminated; thus these two 762 primitives / parameters together can yield a similar behavior to 763 CHANGE-TIMEOUT.TCP. 765 o DISABLE-NAGLE.TCP: 766 Pass 1 primitive / event: not specified 767 Parameters: one boolean value 768 Comments: the Nagle algorithm delays data transmission to increase 769 the chance to send a full-sized segment. An application must be 770 able to disable this algorithm for a connection. 772 o REQUESTHEARTBEAT.SCTP: 773 Pass 1 primitive / event: 'Request HeartBeat' 774 Parameters: socket 775 Returns: success or failure 776 Comments: requests an immediate heartbeat on a path, returning 777 success or failure. 779 o SETPROTOCOLPARAMETERS.SCTP: 780 Pass 1 primitive / event: 'Set Protocol Parameters' 781 Parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; 782 RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 783 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst; 784 PotentiallyFailed.Max.Retrans; Primary.Switchover.Max.Retrans; 785 Remote.UDPEncapsPort. 787 o SETPRIMARY.SCTP: 788 Pass 1 primitive / event: 'Set Primary' 789 Parameters: socket 790 Returns: result of attempting this operation 791 Comments: update the current primary address to be used, based on 792 the set of available sockets of the association. 794 o SETPEERPRIMARY.SCTP: 795 Pass 1 primitive / event: Change Local Address / Set Peer Primary 796 Parameters: local IP address 797 Comments: this is only advisory for the peer. 799 o SETAUTH.SCTP: 800 Pass 1 primitive / event: Set / Get Authentication Parameters 801 Parameters: key_id, key, hmac_id 803 o GETAUTH.SCTP: 804 Pass 1 primitive / event: Set / Get Authentication Parameters 805 Parameters: key_id, chunk_list 807 o RESETSTREAM.SCTP: 808 Pass 1 primitive / event: Add / Reset Streams, Reset Association 809 Parameters: sid, direction 811 o RESETSTREAM-EVENT.SCTP: 812 Pass 1 primitive / event: STREAM RESET notification 813 Parameters: information about the result of RESETSTREAM.SCTP. 814 Comments: This is issued when the procedure for resetting streams 815 has completed. 817 o RESETASSOC.SCTP: 818 Pass 1 primitive / event: Add / Reset Streams, Reset Association 819 Parameters: information related to the extension defined in 820 [RFC3260]. 822 o RESETASSOC-EVENT.SCTP: 823 Pass 1 primitive / event: ASSOCIATION RESET notification 824 Parameters: information about the result of RESETASSOC.SCTP. 825 Comments: This is issued when the procedure for resetting an 826 association has completed. 828 o ADDSTREAM.SCTP: 829 Pass 1 primitive / event: Add / Reset Streams, Reset Association 830 Parameters: number if outgoing and incoming streams to be added 832 o ADDSTREAM-EVENT.SCTP: 833 Pass 1 primitive / event: STREAM CHANGE notification 834 Parameters: information about the result of ADDSTREAM.SCTP. 836 Comments: This is issued when the procedure for adding a stream 837 has completed. 839 o ERROR.TCP: 840 Pass 1 primitive / event: 'ERROR_REPORT' 841 Returns: reason (encoding not specified); subreason (encoding not 842 specified) 843 Comments: soft errors that can be ignored without harm by many 844 applications; an application should be able to disable these 845 notifications. The reported conditions include at least: ICMP 846 error message arrived; Excessive Retransmissions. 848 o ERROR.UDP(-Lite): 849 Pass 1 primitive / event: 'ERROR_REPORT'. 850 Returns: Error report 851 Comments: This returns soft errors that may be ignored without 852 harm by many applications; An application must connect to be able 853 receive these notifications. 855 o STATUS.SCTP: 856 Pass 1 primitive / event: 'Status' and 'NETWORK STATUS CHANGE' 857 notification 858 Returns: data block with information about a specified 859 association, containing: association connection state; socket 860 list; destination transport address reachability states; current 861 receiver window size; current congestion window sizes; number of 862 unacknowledged DATA chunks; number of DATA chunks pending receipt; 863 primary path; most recent SRTT on primary path; RTO on primary 864 path; SRTT and RTO on other destination addresses. The NETWORK 865 STATUS CHANGE notification informs the application about a socket 866 becoming active/inactive. 868 o STATUS.MPTCP: 869 Pass 1 primitive / event: not specified 870 Returns: list of pairs of tuples of IP address and TCP port number 871 of each subflow. The first of the pair is the local IP and port 872 number, while the second is the remote IP and port number. 874 o SET_DSCP.TCP: 875 Pass 1 primitive / event: not specified 876 Parameters: DSCP value 877 Comments: this allows an application to change the DSCP value for 878 outgoing segments. For TCP this was originally specified for the 879 TOS field [RFC1122], which is here interpreted to refer to the 880 DSField [RFC3260]. 882 o SET_DSCP.UDP(-Lite): 883 Pass 1 primitive / event: 'SET_DSCP' 884 Parameter: DSCP value 885 Comments: This allows an application to change the DSCP value for 886 outgoing UDP(-Lite) datagrams. [RFC7657] and 887 [I-D.ietf-tsvwg-rfc5405bis] provide current guidance on using this 888 value with UDP. 890 o ADD_SUBFLOW.MPTCP: 891 Pass 1 primitive / event: not specified 892 Parameters: local IP address and optionally the local port number 893 Comments: the application specifies the local IP address and port 894 number that must be used for a new subflow. 896 o ADD_ADDR.SCTP: 897 Pass 1 primitive / event: Change Local Address / Set Peer Primary 898 Parameters: local IP address 900 o REM_SUBFLOW.MPTCP: 901 Pass 1 primitive / event: not specified 902 Parameters: local IP address, local port number, remote IP 903 address, remote port number 904 Comments: the application removes the subflow specified by the IP/ 905 port-pair. The MPTCP implementation must trigger a removal of the 906 subflow that belongs to this IP/port-pair. 908 o REM_ADDR.SCTP: 909 Pass 1 primitive / event: Change Local Address / Set Peer Primary 910 Parameters: local IP address 912 o CHECKSUM.UDP: 913 Pass 1 primitive / event: 'DISABLE_CHECKSUM'. 914 Parameters: 0 when no checksum is used at sender, 1 for checksum 915 at sender (default). 917 o CHECKSUM_REQUIRED.UDP: 918 Pass 1 primitive / event: 'REQUIRE_CHECKSUM'. 919 Parameter: 0 when checksum is required at receiver, 1 to allow 920 zero checksum at receiver (default). 922 o SET_CHECKSUM_COVERAGE.UDP-Lite: 923 Pass 1 primitive / event: 'SET_CHECKSUM_COVERAGE'. 924 Parameters: Coverage length at sender (default maximum coverage) 926 o SET_MIN_CHECKSUM_COVERAGE.UDP-Lite: 927 Pass 1 primitive / event: 'SET_MIN_COVERAGE'. 928 Parameter: Coverage length at receiver (default minimum coverage) 930 o SET_DF.UDP(-Lite): 931 Pass 1 primitive event: 'SET_DF'. 932 Parameter: 0 when DF is not set (default), 1 when DF is set. 934 o SET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 935 Pass 1 primitive / event: 'SET_TTL' and 'SET_IPV6_UNICAST_HOPS' 936 Parameters: IPv4 TTL value or IPv6 Hop Count value 937 Comments: This allows an application to change the IPv4 TTL of 938 IPv6 Hop count value for outgoing UDP(-Lite) datagrams. 940 o GET_TTL.UDP(-Lite) (IPV6_UNICAST_HOPS): 941 Pass 1 primitive / event: 'GET_TTL' and 'GET_IPV6_UNICAST_HOPS' 942 Returns: IPv4 TTL value or IPv6 Hop Count value 943 Comments: This allows an application to read the the IPv4 TTL of 944 IPv6 Hop count value from a received UDP(-Lite) datagram. 946 o SET_ECN.UDP(-Lite): 947 Pass 1 primitive / event: 'SET_ECN' 948 Parameters: ECN value 949 Comments: This allows a UDP(-Lite) application to set the ECN 950 codepoint field for outgoing UDP(-Lite) datagrams. 952 o GET_ECN.UDP(-Lite): 953 Pass 1 primitive / event: 'GET_ECN' 954 Parameters: ECN value 955 Comments: This allows a UDP(-Lite) application to read the ECN 956 codepoint field from a received UDP(-Lite) datagram. 958 o SET_IP_OPTIONS.UDP(-Lite): 959 Pass 1 primitive / event: 'SET_IP_OPTIONS' 960 Parameters: options 961 Comments: This allows a UDP(-Lite) application to set IP Options 962 for outgoing UDP(-Lite) datagrams. These options can at least be 963 the Source Route, Record Route, and Time Stamp option. 965 o GET_IP_OPTIONS.UDP(-Lite): 966 Pass 1 primitive / event: 'GET_IP_OPTIONS' 967 Returns: options 968 Comments: This allows a UDP(-Lite) application to receive any IP 969 options that are contained in a received UDP(-Lite) datagram. 971 o AUTHENTICATION_NOTIFICATION-EVENT.SCTP: 972 Pass 1 primitive / event: 'AUTHENTICATION notification' 973 Returns: information regarding key management. 975 TERMINATION: 976 Gracefully or forcefully closing a connection, or being informed 977 about this event happening. 979 o CLOSE.TCP: 980 Pass 1 primitive / event: 'close' 981 Comments: this terminates the sending side of a connection after 982 reliably delivering all remaining data. 984 o CLOSE.SCTP: 985 Pass 1 primitive / event: 'Shutdown' 986 Comments: this terminates a connection after reliably delivering 987 all remaining data. 989 o CLOSE.UDP(-Lite): 990 Pass 1 primitive event: 'CLOSE' 991 Comments: No further UDP(-Lite) datagrams are sent/received on 992 this connection. 994 o ABORT.TCP: 995 Pass 1 primitive / event: 'abort' 996 Comments: this terminates a connection without delivering 997 remaining data and sends an error message to the other side. 999 o ABORT.SCTP: 1000 Pass 1 primitive / event: 'abort' 1001 Parameters: abort reason to be given to the peer (optional) 1002 Comments: this terminates a connection without delivering 1003 remaining data and sends an error message to the other side. 1005 o TIMEOUT.TCP: 1006 Pass 1 primitive / event: 'USER TIMEOUT' event 1007 Comments: the application is informed that the connection is 1008 aborted. This event is executed on expiration of the timeout set 1009 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 1010 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 1012 o TIMEOUT.SCTP: 1013 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1014 Comments: the application is informed that the connection is 1015 aborted. this event is executed on expiration of the timeout that 1016 should be enabled by default (see beginning of section 8.3 in 1017 [RFC4960]) and was possibly adjusted in 1018 CONNECTION.MAINTENANCE.CHANGE-TIMEOOUT.SCTP. 1020 o ABORT-EVENT.TCP: 1021 Pass 1 primitive / event: not specified. 1023 o ABORT-EVENT.SCTP: 1024 Pass 1 primitive / event: 'COMMUNICATION LOST' event 1025 Returns: abort reason from the peer (if available) 1026 Comments: the application is informed that the other side has 1027 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 1029 o CLOSE-EVENT.TCP: 1030 Pass 1 primitive / event: not specified. 1032 o CLOSE-EVENT.SCTP: 1033 Pass 1 primitive / event: 'SHUTDOWN COMPLETE' event 1034 Comments: the application is informed that 1035 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 1037 4.2. DATA Transfer Related Primitives 1039 All primitives in this section refer to an existing connection, i.e. 1040 a connection that was either established or made available for 1041 receiving data (although this is optional for the primitives of UDP(- 1042 Lite)). In addition to the listed parameters, all sending primitives 1043 contain a reference to a data block and all receiving primitives 1044 contain a reference to available buffer space for the data. 1046 o SEND.TCP: 1047 Pass 1 primitive / event: 'send' 1048 Parameters: timeout (optional) 1049 Comments: this gives TCP a data block for reliable transmission to 1050 the TCP on the other side of the connection. The timeout can be 1051 configured with this call whenever data are sent (see also 1052 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 1054 o SEND.SCTP: 1055 Pass 1 primitive / event: 'Send' 1056 Parameters: stream number; context (optional); socket (optional); 1057 unordered flag (optional); no-bundle flag (optional); payload 1058 protocol-id (optional); pr-policy (optional) pr-value (optional); 1059 sack-immediately flag (optional); key-id (optional) 1060 Comments: this gives SCTP a data block for transmission to the 1061 SCTP on the other side of the connection (SCTP association). The 1062 'stream number' denotes the stream to be used. The 'context' 1063 number can later be used to refer to the correct message when an 1064 error is reported. The 'socket' can be used to state which path 1065 should be preferred, if there are multiple paths available (see 1066 also CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can 1067 be delivered out-of-order if the 'unordered flag' is set. The 1068 'no-bundle flag' can be set to indicate a preference to avoid 1069 bundling. The 'payload protocol-id' is a number that will, if 1070 provided, be handed over to the receiving application. Using pr- 1071 policy and pr-value the level of reliability can be controlled. 1072 The sack-immediately flag can be used to indicate that the peer 1073 should not delay the sending of a SACK corresponding to the 1074 provided user message. If specified, the provided key-id is used 1075 for authenticating the user message. 1077 o SEND.UDP(-Lite): 1078 Pass 1 primitive / event: 'SEND' 1079 Parameters: IP Address and Port Number of the destination endpoint 1080 (optional if connected). 1081 Comments: This provides a message for unreliable transmission 1082 using UDP(-Lite) to the specified transport address. IP address 1083 and Port may be omitted for connected UDP(-Lite) sockets. All 1084 CONNECTION.MAINTENANCE.SET_*.UDP(-Lite) primitives apply per 1085 message sent. 1087 o RECEIVE.TCP: 1088 Pass 1 primitive / event: 'receive'. 1090 o RECEIVE.SCTP: 1091 Pass 1 primitive / event: 'DATA ARRIVE' notification, followed by 1092 'Receive' 1093 Parameters: stream number (optional) 1094 Returns: stream sequence number (optional), partial flag 1095 (optional) 1096 Comments: if the 'stream number' is provided, the call to receive 1097 only receives data on one particular stream. If a partial message 1098 arrives, this is indicated by the 'partial flag', and then the 1099 'stream sequence number' must be provided such that an application 1100 can restore the correct order of data blocks that comprise an 1101 entire message. Additionally, a delivery number lets the 1102 application detect reordering. 1104 o RECEIVE.UDP(-Lite): 1105 Pass 1 primitive / event: 'RECEIVE', 1106 Parameters: Buffer for received datagram. 1107 Comments: All CONNECTION.MAINTENANCE.GET_*.UDP(-Lite) primitives 1108 apply per message received. 1110 o SENDFAILURE-EVENT.SCTP: 1111 Pass 1 primitive / event: 'SEND FAILURE' notification, optionally 1112 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 1113 Message' 1114 Returns: cause code; context; unsent or unacknowledged message 1115 (optional) 1116 Comments: 'cause code' indicates the reason of the failure, and 1117 'context' is the context number if such a number has been provided 1118 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 1119 'Receive Unacknowledged Message', respectively. These primitives 1120 can be used to retrieve the complete unsent or unacknowledged 1121 message if desired. 1123 o SEND_FAILURE.UDP(-Lite): 1124 Pass 1 primitive / event: 'SEND' 1125 Comment: This may be used to probe for the effective PMTU when 1126 using in combination with the 'MAINTENANCE.SET_DF' primitive. 1128 5. Pass 3 1130 This section presents the superset of all transport service features 1131 in all protocols that were discussed in the preceding sections, based 1132 on the list of primitives in pass 2 but also on text in pass 1 to 1133 include features that can be configured in one protocol and are 1134 static properties in another (congestion control, for example). 1135 Again, some minor details are omitted for the sake of generalization 1136 -- e.g., TCP may provide various different IP options, but only 1137 source route is mandatory to implement, and this detail is not 1138 visible in the Pass 3 feature "Specify IP Options". 1140 5.1. CONNECTION Related Transport Service Features 1142 ESTABLISHMENT: 1143 Active creation of a connection from one transport endpoint to one or 1144 more transport endpoints. 1146 o Connect 1147 Protocols: TCP, SCTP, UDP(-Lite) 1149 o Specify which IP Options must always be used 1150 Protocols: TCP 1152 o Request multiple streams 1153 Protocols: SCTP 1155 o Obtain multiple sockets 1156 Protocols: SCTP 1158 o Disable MPTCP 1159 Protocols: MPTCP 1161 o Specify which chunk types must always be authenticated 1162 Protocols: SCTP 1163 Comments: DATA, ACK etc. are different 'chunks' in SCTP; one or 1164 more chunks may be included in a single packet. 1166 o Indicate an Adaptation Layer (via an adaptation code point) 1167 Protocols: SCTP 1169 AVAILABILITY: 1170 Preparing to receive incoming connection requests. 1172 o Listen, 1 specified local interface 1173 Protocols: TCP, SCTP, UDP(-Lite) 1175 o Listen, N specified local interfaces 1176 Protocols: SCTP, UDP(-Lite) 1178 o Listen, all local interfaces 1179 Protocols: TCP, SCTP, UDP(-Lite) 1181 o Obtain requested number of streams 1182 Protocols: SCTP 1184 o Specify which IP Options must always be used 1185 Protocols: TCP 1187 o Disable MPTCP 1188 Protocols: MPTCP 1190 o Specify which chunk types must always be authenticated 1191 Protocols: SCTP 1192 Comments: DATA, ACK etc. are different 'chunks' in SCTP; one or 1193 more chunks may be included in a single packet. 1195 o Indicate an Adaptation Layer (via an adaptation code point) 1196 Protocols: SCTP 1198 MAINTENANCE: 1199 Adjustments made to an open connection, or notifications about it. 1200 NOTE: all features except "set primary path" in this category apply 1201 to one out of multiple possible paths (identified via sockets) in 1202 SCTP, whereas TCP uses only one path (one socket). 1204 o Change timeout for aborting connection (using retransmit limit or 1205 time value) 1206 Protocols: TCP, SCTP 1208 o Control advertising timeout for aborting connection to remote 1209 endpoint 1210 Protocols: TCP 1212 o Disable Nagle algorithm 1213 Protocols: TCP, SCTP 1214 Comments: This is not specified in [RFC4960] but in [RFC6458]. 1216 o Request an immediate heartbeat, returning success/failure 1217 Protocols: SCTP 1219 o Set protocol parameters 1220 Protocols: SCTP 1221 SCTP parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; 1222 RTO.Alpha; RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 1223 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst; 1224 PotentiallyFailed.Max.Retrans; Primary.Switchover.Max.Retrans; 1225 Remote.UDPEncapsPort 1226 Comments: as transport layer features from other protocols are 1227 added, it might make sense to separate out some of these 1228 parameters -- e.g., if a different protocol provides means to 1229 adjust the RTO calculation there could be a common feature for 1230 them called "adjust RTO calculation". 1232 o Notification of Excessive Retransmissions (early warning below 1233 abortion threshold) 1234 Protocols: TCP 1236 o Notification of ICMP error message arrival 1237 Protocols: TCP, UDP(-Lite) 1239 o Obtain status (query or notification) 1240 Protocols: SCTP, MPTCP 1241 SCTP parameters: association connection state; socket list; socket 1242 reachability states; current receiver window size; current 1243 congestion window sizes; number of unacknowledged DATA chunks; 1244 number of DATA chunks pending receipt; primary path; most recent 1245 SRTT on primary path; RTO on primary path; SRTT and RTO on other 1246 destination addresses; socket becoming active / inactive 1247 MPTCP parameters: subflow-list (identified by source-IP; source- 1248 Port; destination-IP; destination-Port) 1250 o Change authentication parameters 1251 Protocols: SCTP 1253 o Obtain authentication information 1254 Protocols: SCTP 1256 o Set primary path 1257 Protocols: SCTP 1259 o Reset Stream 1260 Protocols: SCTP 1262 o Notification of Stream Reset 1263 Protocols: STCP 1265 o Reset Association 1266 Protocols: SCTP 1268 o Notification of Association Reset 1269 Protocols: STCP 1271 o Add Streams 1272 Protocols: SCTP 1274 o Notification of Added Stream 1275 Protocols: STCP 1277 o Set peer primary path 1278 Protocols: SCTP 1280 o Specify DSCP field 1281 Protocols: TCP, SCTP, UDP(-Lite) 1283 o Add subflow 1284 Protocols: MPTCP 1285 MPTCP Parameters: source-IP; source-Port; destination-IP; 1286 destination-Port 1288 o Remove subflow 1289 Protocols: MPTCP 1290 MPTCP Parameters: source-IP; source-Port; destination-IP; 1291 destination-Port 1293 o Add local address 1294 Protocols: SCTP 1296 o Remove local address 1297 Protocols: SCTP 1299 o Disable checksum when sending 1300 Protocols: UDP 1302 o Disable checksum requirement when receiving 1303 Protocols: UDP 1305 o Specify checksum coverage used by the sender 1306 Protocols: UDP-Lite 1308 o Specify minimum checksum coverage required by receiver 1309 Protocols: UDP-Lite 1311 o Specify DF field 1312 Protocols: UDP(-Lite) 1314 o Specify TTL/Hop count field 1315 Protocols: UDP(-Lite) 1317 o Obtain TTL/Hop count field 1318 Protocols: UDP(-Lite) 1320 o Specify ECN field 1321 Protocols: UDP(-Lite) 1323 o Obtain ECN field 1324 Protocols: UDP(-Lite) 1326 o Specify IP Options 1327 Protocols: UDP(-Lite) 1329 o Obtain IP Options 1330 Protocols: UDP(-Lite) 1332 TERMINATION: 1333 Gracefully or forcefully closing a connection, or being informed 1334 about this event happening. 1336 o Close after reliably delivering all remaining data, causing an 1337 event informing the application on the other side 1338 Protocols: TCP, SCTP 1339 Comments: A TCP endpoint locally only closes the connection for 1340 sending; it may still receive data afterwards. 1342 o Abort without delivering remaining data, causing an event 1343 informing the application on the other side 1344 Protocols: TCP, SCTP 1345 Comments: In SCTP a reason can optionally be given by the 1346 application on the aborting side, which can then be received by 1347 the application on the other side. 1349 o Timeout event when data could not be delivered for too long 1350 Protocols: TCP, SCTP 1351 Comments: the timeout is configured with CONNECTION.MAINTENANCE 1352 "Change timeout for aborting connection (using retransmit limit or 1353 time value)". 1355 5.2. DATA Transfer Related Transport Service Features 1357 All features in this section refer to an existing connection, i.e. a 1358 connection that was either established or made available for 1359 receiving data. Reliable data transfer entails delay -- e.g. for the 1360 sender to wait until it can transmit data, or due to retransmission 1361 in case of packet loss. 1363 5.2.1. Sending Data 1365 All features in this section are provided by DATA.SEND from pass 2. 1366 DATA.SEND is given a data block from the application, which we here 1367 call a "message" if the beginning and end of the data block can be 1368 identified at the receiver, and "data" otherwise. 1370 o Reliably transfer data, with congestion control 1371 Protocols: TCP 1373 o Reliably transfer a message, with congestion control 1374 Protocols: SCTP 1376 o Unreliably transfer a message, with congestion control 1377 Protocols: SCTP 1379 o Unreliably transfer a message, without congestion control 1380 Protocols: UDP(-Lite) 1382 o Configurable Message Reliability 1383 Protocols: SCTP 1385 o Choice of stream 1386 Protocols: SCTP 1388 o Choice of path (destination address) 1389 Protocols: SCTP 1391 o Choice between unordered (potentially faster) or ordered delivery 1392 of messages 1393 Protocols: SCTP 1395 o Request not to bundle messages 1396 Protocols: SCTP 1398 o Specifying a "payload protocol-id" (handed over as such by the 1399 receiver) 1400 Protocols: SCTP 1402 o Specifying a key id to be used to authenticate a message 1403 Protocols: SCTP 1405 o Request not to delay the acknowledgement (SACK) of a message 1406 Protocols: SCTP 1408 5.2.2. Receiving Data 1410 All features in this section are provided by DATA.RECEIVE from pass 1411 2. DATA.RECEIVE fills a buffer provided by the application, with 1412 what we here call a "message" if the beginning and end of the data 1413 block can be identified at the receiver, and "data" otherwise. 1415 o Receive data 1416 Protocols: TCP 1418 o Receive a message 1419 Protocols: SCTP, UDP(-Lite) 1421 o Choice of stream to receive from 1422 Protocols: SCTP 1424 o Information about partial message arrival 1425 Protocols: SCTP 1426 Comments: In SCTP, partial messages are combined with a stream 1427 sequence number so that the application can restore the correct 1428 order of data blocks an entire message consists of. 1430 o Obtain a message delivery number 1431 Protocols: SCTP 1432 Comments: This number can let applications detect and, if desired, 1433 correct reordering. 1435 5.2.3. Errors 1437 This section describes sending failures that are associated with a 1438 specific call to DATA.SEND from pass 2. 1440 o Notification of unsent messages 1441 Protocols: SCTP, UDP(-Lite) 1443 o Notification of unacknowledged messages 1444 Protocols: SCTP 1446 6. Acknowledgements 1448 The authors would like to thank (in alphabetical order) Bob Briscoe, 1449 Gorry Fairhurst, David Hayes, Tom Jones, Karen Nielsen and Joe Touch 1450 for providing valuable feedback on this document. We especially 1451 thank to Christoph Paasch for providing input related to Multipath 1452 TCP. This work has received funding from the European Union's 1453 Horizon 2020 research and innovation programme under grant agreement 1454 No. 644334 (NEAT). The views expressed are solely those of the 1455 author(s). 1457 7. IANA Considerations 1459 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 1461 This memo includes no request to IANA. 1463 8. Security Considerations 1465 Security will be considered in future versions of this document. 1467 9. References 1469 9.1. Normative References 1471 [I-D.ietf-tsvwg-rfc5405bis] 1472 Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 1473 Guidelines", draft-ietf-tsvwg-rfc5405bis-07 (work in 1474 progress), November 2015. 1476 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1477 RFC 793, DOI 10.17487/RFC0793, September 1981, 1478 . 1480 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1481 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 1482 RFC1122, October 1989, 1483 . 1485 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1486 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1487 . 1489 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 1490 RFC 5482, DOI 10.17487/RFC5482, March 2009, 1491 . 1493 9.2. Informative References 1495 [FA16] Fairhurst, Ed., G., Trammell, Ed., B., and M. Kuehlewind, 1496 Ed., "Services provided by IETF transport protocols and 1497 congestion control mechanisms", 1498 draft-ietf-taps-transports-12.txt (work in progress), 1499 October 2016. 1501 [FJ16] Fairhurst, G. and T. Jones, "Features of the User Datagram 1502 Protocol (UDP) and Lightweight UDP (UDP-Lite) Transport 1503 Protocols", draft-fairhurst-taps-transports-usage-udp-03 1504 (work in progress), October 2016. 1506 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 1507 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, 1508 May 1983, . 1510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1511 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1512 RFC2119, March 1997, 1513 . 1515 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 1516 of Explicit Congestion Notification (ECN) to IP", 1517 RFC 3168, DOI 10.17487/RFC3168, September 2001, 1518 . 1520 [RFC3260] Grossman, D., "New Terminology and Clarifications for 1521 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 1522 . 1524 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 1525 Conrad, "Stream Control Transmission Protocol (SCTP) 1526 Partial Reliability Extension", RFC 3758, DOI 10.17487/ 1527 RFC3758, May 2004, 1528 . 1530 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., Ed., 1531 and G. Fairhurst, Ed., "The Lightweight User Datagram 1532 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, 1533 July 2004, . 1535 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 1536 "Authenticated Chunks for the Stream Control Transmission 1537 Protocol (SCTP)", RFC 4895, DOI 10.17487/RFC4895, 1538 August 2007, . 1540 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 1541 Kozuka, "Stream Control Transmission Protocol (SCTP) 1542 Dynamic Address Reconfiguration", RFC 5061, DOI 10.17487/ 1543 RFC5061, September 2007, 1544 . 1546 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 1547 DOI 10.17487/RFC5461, February 2009, 1548 . 1550 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 1551 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 1552 January 2011, . 1554 [RFC6182] Ford, A., Raiciu, C., Handley, M., Barre, S., and J. 1555 Iyengar, "Architectural Guidelines for Multipath TCP 1556 Development", RFC 6182, DOI 10.17487/RFC6182, March 2011, 1557 . 1559 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1560 Yasevich, "Sockets API Extensions for the Stream Control 1561 Transmission Protocol (SCTP)", RFC 6458, DOI 10.17487/ 1562 RFC6458, December 2011, 1563 . 1565 [RFC6525] Stewart, R., Tuexen, M., and P. Lei, "Stream Control 1566 Transmission Protocol (SCTP) Stream Reconfiguration", 1567 RFC 6525, DOI 10.17487/RFC6525, February 2012, 1568 . 1570 [RFC6824] Ford, A., Raiciu, C., Handley, M., and O. Bonaventure, 1571 "TCP Extensions for Multipath Operation with Multiple 1572 Addresses", RFC 6824, DOI 10.17487/RFC6824, January 2013, 1573 . 1575 [RFC6897] Scharf, M. and A. Ford, "Multipath TCP (MPTCP) Application 1576 Interface Considerations", RFC 6897, DOI 10.17487/RFC6897, 1577 March 2013, . 1579 [RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream 1580 Control Transmission Protocol (SCTP) Packets for End-Host 1581 to End-Host Communication", RFC 6951, DOI 10.17487/ 1582 RFC6951, May 2013, 1583 . 1585 [RFC7053] Tuexen, M., Ruengeler, I., and R. Stewart, "SACK- 1586 IMMEDIATELY Extension for the Stream Control Transmission 1587 Protocol", RFC 7053, DOI 10.17487/RFC7053, November 2013, 1588 . 1590 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 1591 Zimmermann, "A Roadmap for Transmission Control Protocol 1592 (TCP) Specification Documents", RFC 7414, DOI 10.17487/ 1593 RFC7414, February 2015, 1594 . 1596 [RFC7496] Tuexen, M., Seggelmann, R., Stewart, R., and S. Loreto, 1597 "Additional Policies for the Partially Reliable Stream 1598 Control Transmission Protocol Extension", RFC 7496, 1599 DOI 10.17487/RFC7496, April 2015, 1600 . 1602 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 1603 (Diffserv) and Real-Time Communication", RFC 7657, 1604 DOI 10.17487/RFC7657, November 2015, 1605 . 1607 [RFC7829] Nishida, Y., Natarajan, P., Caro, A., Amer, P., and K. 1608 Nielsen, "SCTP-PF: A Quick Failover Algorithm for the 1609 Stream Control Transmission Protocol", RFC 7829, 1610 DOI 10.17487/RFC7829, April 2016, 1611 . 1613 Appendix A. Overview of RFCs used as input for pass 1 1615 TCP: [RFC0793], [RFC1122], [RFC5482] 1616 MPTCP: [RFC6182], [RFC6824], [RFC6897] 1617 SCTP: RFCs without a socket API specification: [RFC3758], [RFC4895], 1618 [RFC4960], [RFC5061]. RFCs that include a socket API 1619 specification: [RFC6458], [RFC6525], [RFC6951], [RFC7053], 1620 [RFC7496] [RFC7829]. 1621 UDP(-Lite): See [FJ16] 1623 Appendix B. How to contribute 1625 This document is only concerned with transport service features that 1626 are explicitly exposed to applications via primitives. It also 1627 strictly follows RFC text: if a feature is truly relevant for an 1628 application, the RFCs better say so and in some way describe how to 1629 use and configure it. Thus, the approach to follow for contributing 1630 to this document is to identify the right RFCs, then analyze and 1631 process their text. 1633 Experimental RFCs are excluded, and so are primitives that MAY be 1634 implemented (by the transport protocol). To be included, the minimum 1635 requirement level for a primitive to be implemented by a protocol is 1636 SHOULD. If [RFC2119]-style requirements levels are not used, 1637 primitives should be excluded when they are described in conjunction 1638 with statements like, e.g.: "some implementations also provide" or 1639 "an implementation may also". Briefly describe excluded primitives 1640 in a subsection called "excluded primitives". 1642 Pass 1: Identify text that talks about primitives. An API 1643 specification, abstract or not, obviously describes primitives -- but 1644 note that we are not *only* interested in API specifications. The 1645 text describing the 'send' primitive in the API specified in 1646 [RFC0793], for instance, does not say that data transfer is reliable. 1647 TCP's reliability is clear, however, from this text in Section 1 of 1648 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 1649 use as a highly reliable host-to-host protocol between hosts in 1650 packet-switched computer communication networks, and in 1651 interconnected systems of such networks." 1653 For the new pass 1 subsection about the protocol you're describing, 1654 it is recommendable to begin by copy+pasting all the relevant text 1655 parts from the relevant RFCs, then adjust terminology to match the 1656 terminology in Section 1 and adjust (shorten!) phrasing to match the 1657 general style of the document. Try to formulate everything as a 1658 primitive description to make the primitive description as complete 1659 as possible (e.g., the "SEND.TCP" primitive in pass 2 is explicitly 1660 described as reliably transferring data); if there is text that is 1661 relevant for the primitives presented in this pass but still does not 1662 fit directly under any primitive, use it as an introduction for your 1663 subsection. However, do note that document length is a concern and 1664 all the protocols and their services / features are already described 1665 in [FA16]. 1667 Pass 2: The main goal of this pass is unification of primitives. As 1668 input, use your own text from Pass 1, no exterior sources. If you 1669 find that something is missing there, fix the text in Pass 1. The 1670 list in pass 2 is not done by protocol ("first protocol X, here are 1671 all the primitives; then protocol Y, here are all the primitives, 1672 ..") but by primitive ("primitive A, implemented this way in protocol 1673 X, this way in protocol Y, ..."). We want as many similar pass 2 1674 primitives as possible. This can be achieved, for instance, by not 1675 always maintaining a 1:1 mapping between pass 1 and pass 2 1676 primitives, renaming primitives etc. Please consider the primitives 1677 that are already there and try to make the ones of the protocol you 1678 are describing as much in line with the already existing ones as 1679 possible. In other words, we would rather have a primitive with new 1680 parameters than a new primitive that allows to send in a particular 1681 way. 1683 Please make primitives fit within the already existing categories and 1684 subcategories. For each primitive, please follow the style: 1686 o PRIMITIVENAME.PROTOCOL: 1687 Pass 1 primitive / event: 1688 Parameters: 1689 Returns: 1690 Comments: 1692 The entries "Parameters", "Returns" and "Comments" may be skipped if 1693 a primitive has no parameters, no described return value or no 1694 comments seem necessary, respectively. Optional parameters must be 1695 followed by "(optional)". If a default value is known, provide it 1696 too. 1698 Pass 3: the main point of this pass is to identify features that are 1699 the result of static properties of protocols, for which all protocols 1700 have to be listed together; this is then the final list of all 1701 available features. For this, we need a list of features per 1702 category (similar categories as in pass 2) along with the protocol 1703 supporting it. This should be primarily based on text from pass 2 as 1704 input, but text from pass 1 can also be used. Do not use external 1705 sources. 1707 Appendix C. Revision information 1709 XXX RFC-Ed please remove this section prior to publication. 1711 -00 (from draft-welzl-taps-transports): this now covers TCP based on 1712 all TCP RFCs (this means: if you know of something in any TCP RFC 1713 that you think should be addressed, please speak up!) as well as 1714 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 1715 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 1716 in line with [FA16]. Addressed comments by Karen Nielsen and Gorry 1717 Fairhurst; various other fixes. Appendices (TCP overview and how-to- 1718 contribute) added. 1720 -01: this now also covers MPTCP based on [RFC6182], [RFC6824] and 1721 [RFC6897]. 1723 -02: included UDP, UDP-Lite, and all extensions of SCTPs. This 1724 includes fixing the [RFC6458] omission from -00. 1726 TODO: security considerations (see review in ML); the "how to 1727 contribute" section (which, at some point, should be updated to 1728 reflect how the document WAS created, not how it SHOULD BE created) 1729 still says "Experimental RFCs are excluded". This is wrong, and 1730 accordingly, Experimental RFCs must also be considered - thus, TFO 1731 (are there more Experimental ones for TCP?). Also, include LEDBAT. 1732 SCTP: DSCP and SCTP_NODELAY (equivalent to Nagle) are missing in pass 1733 1 and 2. Are we missing more (DF, TTL, ..)? What about e.g. 1734 "notification of ICMP error message arrival"? Also consider 1735 draft-ietf-tsvwg-sctp-ndata. 1737 Authors' Addresses 1739 Michael Welzl 1740 University of Oslo 1741 PO Box 1080 Blindern 1742 Oslo, N-0316 1743 Norway 1745 Phone: +47 22 85 24 20 1746 Email: michawe@ifi.uio.no 1748 Michael Tuexen 1749 Muenster University of Applied Sciences 1750 Stegerwaldstrasse 39 1751 Steinfurt 48565 1752 Germany 1754 Email: tuexen@fh-muenster.de 1755 Naeem Khademi 1756 University of Oslo 1757 PO Box 1080 Blindern 1758 Oslo, N-0316 1759 Norway 1761 Email: naeemk@ifi.uio.no