idnits 2.17.1 draft-ietf-taps-transports-usage-00.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 (January 8, 2016) is 3024 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'SUBCATEGORY' is mentioned on line 485, but not defined == Unused Reference: 'RFC2119' is defined on line 1035, 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) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 3 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: July 11, 2016 Muenster Univ. of Appl. Sciences 6 N. Khademi 7 University of Oslo 8 January 8, 2016 10 On the Usage of Transport Service Features Provided by IETF Transport 11 Protocols 12 draft-ietf-taps-transports-usage-00 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 July 11, 2016. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Primitives Provided by TCP . . . . . . . . . . . . . . . . 5 58 3.1.1. Excluded Primitives . . . . . . . . . . . . . . . . . 7 59 3.2. Primitives Provided by SCTP . . . . . . . . . . . . . . . 8 60 3.2.1. Excluded Primitives . . . . . . . . . . . . . . . . . 11 61 4. Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 62 4.1. CONNECTION Related Primitives . . . . . . . . . . . . . . 12 63 4.2. DATA Transfer Related Primitives . . . . . . . . . . . . . 16 64 5. Pass 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 65 5.1. CONNECTION Related Transport Service Features . . . . . . 18 66 5.2. DATA Transfer Related Transport Service Features . . . . . 20 67 5.2.1. Sending Data . . . . . . . . . . . . . . . . . . . . . 20 68 5.2.2. Receiving Data . . . . . . . . . . . . . . . . . . . . 21 69 5.2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . 22 70 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 22 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 73 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 74 9.1. Normative References . . . . . . . . . . . . . . . . . . . 22 75 9.2. Informative References . . . . . . . . . . . . . . . . . . 23 76 Appendix A. Overview of RFCs used as input for pass 1 . . . . . . 24 77 Appendix B. How to contribute . . . . . . . . . . . . . . . . . . 24 78 Appendix C. Revision information . . . . . . . . . . . . . . . . 26 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 81 1. Terminology 83 Transport Service Feature: a specific end-to-end feature that a 84 transport service provides to its clients. Examples include 85 confidentiality, reliable delivery, ordered delivery, message- 86 versus-stream orientation, etc. 87 Transport Service: a set of transport service features, without an 88 association to any given framing protocol, which provides a 89 complete service to an application. 90 Transport Protocol: an implementation that provides one or more 91 different transport services using a specific framing and header 92 format on the wire. 93 Transport Protocol Component: an implementation of a transport 94 service feature within a protocol. 95 Transport Service Instance: an arrangement of transport protocols 96 with a selected set of features and configuration parameters that 97 implements a single transport service, e.g., a protocol stack (RTP 98 over UDP). 99 Application: an entity that uses the transport layer for end-to-end 100 delivery of data across the network (this may also be an upper 101 layer protocol or tunnel encapsulation). 102 Endpoint: an entity that communicates with one or more other 103 endpoints using a transport protocol. 104 Connection: shared state of two or more endpoints that persists 105 across messages that are transmitted between these endpoints. 106 Primitive: a function call that is used to locally communicate 107 between an application and a transport endpoint and is related to 108 one or more Transport Service Features. 109 Parameter: a value passed between an application and a transport 110 protocol by a primitive. 111 Socket: the combination of a destination IP address and a 112 destination port number. 114 2. Introduction 116 This document presents defined interactions between transport 117 protocols and applications in the form of 'primitives' (function 118 calls). Primitives can be invoked by an application or a transport 119 protocol; the latter type is called an "event". The list of 120 transport service features and primitives in this document is 121 strictly based on the parts of protocol specifications that relate to 122 what the protocol provides to an application using it and how the 123 application interacts with it. It does not cover parts of a protocol 124 that are explicitly stated as optional to implement. 126 The document presents a three-pass process to arrive at a list of 127 transport service features. In the first pass, the relevant RFC text 128 is discussed per protocol. In the second pass, this discussion is 129 used to derive a list of primitives that are uniformly categorized 130 across protocols. Here, an attempt is made to present or -- where 131 text describing primitives does not yet exist -- construct primitives 132 in a slightly generalized form to highlight similarities. This is, 133 for example, achieved by renaming primitives of protocols or by 134 avoiding a strict 1:1-mapping between the primitives in the protocol 135 specification and primitives in the list. Finally, the third pass 136 presents transport service features based on pass 2, identifying 137 which protocols implement them. 139 In the list resulting from the second pass, some transport service 140 features are missing because they are implicit in some protocols, and 141 they only become explicit when we consider the superset of all 142 features offered by all protocols. For example, TCP's reliability 143 includes integrity via a checksum, but we have to include a protocol 144 like UDP-Lite as specified in [RFC3828] (which has a configurable 145 checksum) in the list before we can consider an always-on checksum as 146 a transport service feature. Similar arguments apply to other 147 protocol functions (e.g. congestion control). The complete list of 148 features across all protocols is therefore only available after pass 149 3. 151 This document discusses unicast transport protocols. [AUTHOR'S NOTE: 152 we skip "congestion control mechanisms" for now. This simplifies the 153 discussion; the congestion control mechanisms part is about LEDBAT, 154 which should be easy to add later.] Transport protocols provide 155 communication between processes that operate on network endpoints, 156 which means that they allow for multiplexing of communication between 157 the same IP addresses, and normally this multiplexing is achieved 158 using port numbers. Port multiplexing is therefore assumed to be 159 always provided and not discussed in this document. 161 Some protocols are connection-oriented. Connection-oriented 162 protocols often use an initial call to a specific transport primitive 163 to open a connection before communication can progress, and require 164 communication to be explicitly terminated by issuing another call to 165 a transport primitive (usually called "close"). A "connection" is 166 the common state that some transport primitives refer to, e.g., to 167 adjust general configuration settings. Connection establishment, 168 maintenance and termination are therefore used to categorize 169 transport primitives of connection-oriented transport protocols in 170 pass 2 and pass 3. 172 3. Pass 1 174 This first iteration summarizes the relevant text parts of the RFCs 175 describing the protocols, focusing on what each transport protocol 176 provides to the application and how it is used (abstract API 177 descriptions, where they are available). 179 3.1. Primitives Provided by TCP 181 [RFC0793] states: "The Transmission Control Protocol (TCP) is 182 intended for use as a highly reliable host-to-host protocol between 183 hosts in packet-switched computer communication networks, and in 184 interconnected systems of such networks". Section 3.8 in [RFC0793] 185 further specifies the interaction with the application by listing 186 several transport primitives. It is also assumed that an Operating 187 System provides a means for TCP to asynchronously signal the 188 application; the primitives representing such signals are called 189 'events' in this section. This section describes the relevant 190 primitives. 192 open: this is either active or passive, to initiate a connection or 193 listen for incoming connections. All other primitives are 194 associated with a specific connection, which is assumed to first 195 have been opened. An active open call contains a socket. A 196 passive open call with a socket waits for a particular connection; 197 alternatively, a passive open call can leave the socket 198 unspecified to accept any incoming connection. A fully specified 199 passive call can later be made active by calling 'send'. 200 Optionally, a timeout can be specified, after which TCP will abort 201 the connection if data has not been successfully delivered to the 202 destination (else a default timeout value is used). [RFC1122] 203 describes a procedure for aborting the connection that must be 204 used to avoid excessive retransmissions, and states that an 205 application must be able to control the threshold used to 206 determine the condition for aborting -- and that this threshold 207 may be measured in time units or as a count of retransmission. 208 This indicates that the timeout could also be specified as a count 209 of retransmission. 211 Also optional, for multihomed hosts, the local IP address can be 212 provided [RFC1122]. If it is not provided, a default choice will 213 be made in case of active open calls. A passive open call will 214 await incoming connection requests to all local addresses and then 215 maintain usage of the local IP address where the incoming 216 connection request has arrived. Finally, the 'options' parameter 217 is explained in [RFC1122] to allow the application to specify IP 218 options such as source route, record route, or timestamp. It is 219 not stated on which segments of a connection these options should 220 be applied, but probably all segments, as this is also stated in a 221 specification given for the usage of source route (section 4.2.3.8 222 of [RFC1122]). Source route is the only non-optional IP option in 223 this parameter, allowing an application to specify a source route 224 when it actively opens a TCP connection. 226 send: this is the primitive that an application uses to give the 227 local TCP transport endpoint a number of bytes that TCP should 228 reliably send to the other side of the connection. The URGENT 229 flag, if set, states that the data handed over by this send call 230 is urgent and this urgency should be indicated to the receiving 231 process in case the receiving application has not yet consumed all 232 non-urgent data preceding it. An optional timeout parameter can 233 be provided that updates the connection's timeout (see 'open'). 235 receive: This primitive allocates a receiving buffer for a provided 236 number of bytes. It returns the number of received bytes provided 237 in the buffer when these bytes have been received and written into 238 the buffer by TCP. The application is informed of urgent data via 239 an URGENT flag: if it is on, there is urgent data. If it is off, 240 there is no urgent data or this call to 'receive' has returned all 241 the urgent data. 243 close: This primitive closes one side of a connection. It is 244 semantically equivalent to "I have no more data to send" but does 245 not mean "I will not receive any more", as the other side may 246 still have data to send. This call reliably delivers any data 247 that has already been given to TCP (and if that fails, 'close' 248 becomes 'abort'). 250 abort: This primitive causes all pending 'send' and 'receive' calls 251 to be aborted. A TCP RESET message is sent to the TCP endpoint on 252 the other side of the connection [RFC0793]. 254 close event: TCP uses this primitive to inform an application that 255 the application on the other side has called the 'close' 256 primitive, so the local application can also issue a 'close' and 257 terminate the connection gracefully. See [RFC0793], Section 3.5. 259 abort event: When TCP aborts a connection upon receiving a "Reset" 260 from the peer, it "advises the user and goes to the CLOSED state." 261 See [RFC0793], Section 3.4. 263 USER TIMEOUT event: This event, described in Section 3.9 of 264 [RFC0793], is executed when the user timeout expires (see 'open'). 265 All queues are flushed and the application is informed that the 266 connection had to be aborted due to user timeout. 268 ERROR_REPORT event: This event, described in Section 4.2.4.1 of 269 [RFC1122], informs the application of "soft errors" that can be 270 safely ignored [RFC5461], including the arrival of an ICMP error 271 message or excessive retransmissions (reaching a threshold below 272 the threshold where the connection is aborted). 274 Type-of-Service: Section 4.2.4.2 of [RFC1122] states that the 275 application layer MUST be able to specify the Type-of-Service 276 (TOS) for segments that are sent on a connection. The application 277 should be able to change the TOS during the connection lifetime, 278 and the TOS value should be passed to the IP layer unchanged. 279 Since then the TOS field has been redefined. A part of the field 280 has been assigned to ECN [RFC3168] and the six most significant 281 bits have been assigned to carry the DiffServ CodePoint, DSField 282 [RFC3260]. Staying with the intention behind the application's 283 ability to specify the "Type of Service", this should probably be 284 interpreted to mean the value in the DSField, which is the 285 Differentiated Services Codepoint (DSCP). 287 Nagle: The Nagle algorithm, described in Section 4.2.3.4 of 288 [RFC1122], delays sending data for some time to increase the 289 likelihood of sending a full-sized segment. An application can 290 disable the Nagle algorithm for an individual connection. 292 User Timeout Option: The User Timeout Option (UTO) [RFC5482] allows 293 one end of a TCP connection to advertise its current user timeout 294 value so that the other end of the TCP connection can adapt its 295 own user timeout accordingly. In addition to the configurable 296 value of the User Timeout (see 'send'), [RFC5482] introduces three 297 per-connection state variables that an application can adjust to 298 control the operation of the User Timeout Option (UTO): ADV_UTO is 299 the value of the UTO advertised to the remote TCP peer (default: 300 system-wide default user timeout); ENABLED (default false) is a 301 boolean-type flag that controls whether the UTO option is enabled 302 for a connection. This applies to both sending and receiving. 303 CHANGEABLE is a boolean-type flag (default true) that controls 304 whether the user timeout may be changed based on a UTO option 305 received from the other end of the connection. CHANGEABLE becomes 306 false when an application explicitly sets the user timeout (see 307 'send'). 309 3.1.1. Excluded Primitives 311 The 'open' primitive specified in [RFC0793] can be handed optional 312 Precedence or security/compartment information according to 313 [RFC0793], but this was not included here because it is mostly 314 irrelevant today, as explained in [RFC7414]. 316 The 'status' primitive was not included because [RFC0793] describes 317 this primitive as "implementation dependent" and states that it 318 "could be excluded without adverse effect". Moreover, while a data 319 block containing specific information is described, it is also stated 320 that not all of this information may always be available. The 'send' 321 primitive described in [RFC0793] includes an optional PUSH flag 322 which, if set, requires data to be promptly transmitted to the 323 receiver without delay; the 'receive' primitive described in 324 [RFC0793] can (under some conditions) yield the status of the PUSH 325 flag. Because PUSH functionality is made optional to implement for 326 both the 'send' and 'receive' primitives in [RFC1122], this 327 functionality is not included here. [RFC1122] also introduces keep- 328 alives to TCP, but these are optional to implement and hence not 329 considered here. [RFC1122] describes that "some TCP implementations 330 have included a FLUSH call", indicating that this call is also 331 optional to implement. It is therefore not considered here. 333 3.2. Primitives Provided by SCTP 335 Section 1.1 of [RFC4960] lists limitations of TCP that SCTP removes. 336 Three of the four mentioned limitations directly translate into a 337 transport service features that are visible to an application using 338 SCTP: 1) it allows for preservation of message delineations; 2) these 339 messages, while reliably transferred, do not require to be in order 340 unless the application wants it; 3) multi-homing is supported. In 341 SCTP, connections are called "association" and they can be between 342 not only two (as in TCP) but multiple addresses at each endpoint. 344 Section 10 of [RFC4960] further specifies the interaction with the 345 application (which RFC [RFC4960] calls the "Upper Layer Protocol" 346 (ULP)). It is assumed that the Operating System provides a means for 347 SCTP to asynchronously signal the application; the primitives 348 representing such signals are called 'events' in this section. Here, 349 we describe the relevant primitives. 351 Initialize: Initialize creates a local SCTP instance that it binds 352 to a set of local addresses (and, if provided, port number). 353 Initialize needs to be called only once per set of local 354 addresses. 356 Associate: This creates an association (the SCTP equivalent of a 357 connection) between the local SCTP instance and a remote SCTP 358 instance. Most primitives are associated with a specific 359 association, which is assumed to first have been created. 360 Associate can return a list of destination transport addresses so 361 that multiple paths can later be used. One of the returned 362 sockets will be selected by the local endpoint as default primary 363 path for sending SCTP packets to this peer, but this choice can be 364 changed by the application using the list of destination 365 addresses. Associate is also given the number of outgoing streams 366 to request and optionally returns the number of outgoing streams 367 negotiated. 369 Send: This sends a message of a certain length in bytes over an 370 association. A number can be provided to later refer to the 371 correct message when reporting an error, and a stream id is 372 provided to specify the stream to be used inside an association 373 (we consider this as a mandatory parameter here for simplicity: if 374 not provided, the stream id defaults to 0). An optional maximum 375 life time can specify the time after which the message should be 376 discarded rather than sent. A choice (advisory, i.e. not 377 guaranteed) of the preferred path can be made by providing a 378 socket, and the message can be delivered out-of-order if the 379 unordered flag is set. Another advisory flag indicates whether 380 the application prefers to avoid bundling user data with other 381 outbound DATA chunks (i.e., in the same packet). A payload 382 protocol-id can be provided to pass a value that indicates the 383 type of payload protocol data to the peer. 385 Receive: Messages are received from an association, and optionally a 386 stream within the association, with their size returned. The 387 application is notified of the availability of data via a DATA 388 ARRIVE notification. If the sender has included a payload 389 protocol-id, this value is also returned. If the received message 390 is only a partial delivery of a whole message, a partial flag will 391 indicate so, in which case the stream id and a stream sequence 392 number are provided to the application. 394 Shutdown: This primitive gracefully closes an association, reliably 395 delivering any data that has already been handed over to SCTP. A 396 return code informs about success or failure of this procedure. 398 Abort: This ungracefully closes an association, by discarding any 399 locally queued data and informing the peer that the association 400 was aborted. Optionally, an abort reason to be passed to the peer 401 may be provided by the application. A return code informs about 402 success or failure of this procedure. 404 Change Heartbeat / Request Heartbeat: This allows the application to 405 enable/disable heartbeats and optionally specify a heartbeat 406 frequency as well as requesting a single heartbeat to be carried 407 out upon a function call, with a notification about success or 408 failure of transmitting the HEARTBEAT chunk to the destination. 410 Set Protocol Parameters: This allows to set values for protocol 411 parameters per association; for some parameters, a setting can be 412 made per socket. The set listed in [RFC4960] is: RTO.Initial; 413 RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; RTO.Beta; 414 Valid.Cookie.Life; Association.Max.Retrans; Path.Max.Retrans; 415 Max.Init.Retransmits; HB.interval; HB.Max.Burst. 417 Set Primary: This allows to set a new primary default path for an 418 association by providing a socket. Optionally, a default source 419 address to be used in IP datagrams can be provided. 421 Status: The 'Status' primitive returns a data block with information 422 about a specified association, containing: association connection 423 state; socket list; destination transport address reachability 424 states; current receiver window size; current congestion window 425 sizes; number of unacknowledged DATA chunks; number of DATA chunks 426 pending receipt; primary path; most recent SRTT on primary path; 427 RTO on primary path; SRTT and RTO on other destination addresses. 429 COMMUNICATION UP notification: When a lost communication to an 430 endpoint is restored or when SCTP becomes ready to send or receive 431 user messages, this notification informs the application process 432 about the affected association, the type of event that has 433 occurred, the complete set of sockets of the peer, the maximum 434 number of allowed streams and the inbound stream count (the number 435 of streams the peer endpoint has requested). 437 DATA ARRIVE notification: When a message is ready to be retrieved 438 via the Receive primitive, the application is informed by this 439 notification. 441 SEND FAILURE notification / Receive Unsent Message / Receive 442 Unacknowledged Message: When a message cannot be delivered via an 443 association, the sender can be informed about it and learn whether 444 the message has just not been acknowledged or (e.g. in case of 445 lifetime expiry) if it has not even been sent. 447 NETWORK STATUS CHANGE notification: The NETWORK STATUS CHANGE 448 notification informs the application about a socket becoming 449 active/inactive. 451 COMMUNICATION LOST notification: When SCTP loses communication to an 452 endpoint (e.g. via Heartbeats or excessive retransmission) or 453 detects an abort, this notification informs the application 454 process of the affected association and the type of event (failure 455 OR termination in response to a shutdown or abort request). 457 SHUTDOWN COMPLETE notification: When SCTP completes the shutdown 458 procedures, this notification is passed to the upper layer, 459 informing it about the affected assocation. 461 3.2.1. Excluded Primitives 463 The 'Receive' primitive can return certain additional information, 464 but this is optional to implement and therefore not considered. With 465 a COMMUNICATION LOST notification, some more information may 466 optionally be passed to the application (e.g., identification to 467 retrieve unsent and unacknowledged data). SCTP "can invoke" a 468 COMMUNICATION ERROR notification and "may send" a RESTART 469 notification, making these two notifications optional to implement. 470 The list provided under 'Status' includes "etc", indicating that more 471 information could be provided. The primitive 'Get SRTT Report' 472 returns information that is included in the information that 'Status' 473 provides and is therefore not discussed. Similarly, 'Set Failure 474 Threshold' sets only one out of various possible parameters included 475 in 'Set Protocol Parameters'. The 'Destroy SCTP Instance' API 476 function was excluded: it erases the SCTP instance that was created 477 by 'Initialize', but is not a Primitive as defined in this document 478 because it does not relate to a Transport Service Feature. 480 4. Pass 2 482 This pass categorizes the primitives from pass 1 based on whether 483 they relate to a connection or to data transmission. Primitives are 484 presented following the nomenclature: 485 "CATEGORY.[SUBCATEGORY].PRIMITIVENAME.PROTOCOL". A connection is a 486 general protocol-independent concept and refers to, e.g., TCP 487 connections (identifiable by a unique pair of IP addresses and TCP 488 port numbers) as well as SCTP associations (identifiable by multiple 489 IP address and port number pairs). 491 Some minor details are omitted for the sake of generalization -- 492 e.g., SCTP's 'close' [RFC4960] returns success or failure, whereas 493 this is not described in the same way for TCP in [RFC0793], but this 494 detail plays no significant role for the primitives provided by 495 either TCP or SCTP. 497 The TCP 'send' and 'receive' primitives include usage of an "URGENT" 498 mechanism. This mechanism is required to implement the "synch 499 signal" used by telnet [RFC0854], but SHOULD NOT be used by new 500 applications [RFC6093]. Because pass 2 is meant as a basis for the 501 creation of TAPS systems, the "URGENT" mechanism is excluded. This 502 also concerns the notification "Urgent pointer advance" in the 503 ERROR_REPORT described in Section 4.2.4.1 of [RFC1122]. 505 4.1. CONNECTION Related Primitives 507 ESTABLISHMENT: 508 Active creation of a connection from one transport endpoint to one or 509 more transport endpoints. 511 o CONNECT.TCP: 512 Pass 1 primitive / event: 'open' (active) or 'open' (passive) with 513 socket, followed by 'send' 514 Parameters: 1 local IP address (optional); 1 destination transport 515 address (for active open; else the socket and the local IP address 516 of the succeeding incoming connection request will be maintained); 517 timeout (optional); options (optional) 518 Comments: If the local IP address is not provided, a default 519 choice will automatically be made. The timeout can also be a 520 retransmission count. The options are IP options to be used on 521 all segments of the connection. At least the Source Route option 522 is mandatory for TCP to provide. 524 o CONNECT.SCTP: 525 Pass 1 primitive / event: 'initialize', followed by 'associate' 526 Parameters: list of local SCTP port number / IP address pairs 527 (initialize); 1 socket; outbound stream count 528 Returns: socket list 529 Comments: 'initialize' needs to be called only once per list of 530 local SCTP port number / IP address pairs. One socket will 531 automatically be chosen; it can later be changed in MAINTENANCE. 533 AVAILABILITY: 534 Preparing to receive incoming connection requests. 536 o LISTEN.TCP: 537 Pass 1 primitive / event: 'open' (passive) 538 Parameters: 1 local IP address (optional); 1 socket (optional); 539 timeout (optional) 540 Comments: if the socket and/or local IP address is provided, this 541 waits for incoming connections from only and/or to only the 542 provided address. Else this waits for incoming connections 543 without this / these constraint(s). ESTABLISHMENT can later be 544 performed with 'send'. 546 o LISTEN.SCTP: 547 Pass 1 primitive / event: 'initialize', followed by 'COMMUNICATION 548 UP' notification 549 Parameters: list of local SCTP port number / IP address pairs 550 (initialize) 551 Returns: socket list; outbound stream count; inbound stream count 552 Comments: initialize needs to be called only once per list of 553 local SCTP port number / IP address pairs. COMMUNICATION UP can 554 also follow a COMMUNICATION LOST notification, indicating that the 555 lost communication is restored. 557 MAINTENANCE: 558 Adjustments made to an open connection, or notifications about it. 559 These are out-of-band messages to the protocol that can be issued at 560 any time, at least after a connection has been established and before 561 it has been terminated (with one exception: CHANGE-TIMEOUT.TCP can 562 only be issued when DATA.SEND.TCP is called). 564 o CHANGE-TIMEOUT.TCP: 565 Pass 1 primitive / event: 'send' combined with unspecified control 566 of per-connection state variables 567 Parameters: timeout value (optional); ADV_UTO (optional); boolean 568 UTO_ENABLED (optional, default false); boolean CHANGEABLE 569 (optional, default true) 570 Comments: when sending data, an application can adjust the 571 connection's timeout value (time after which the connection will 572 be aborted if data could not be delivered). If UTO_ENABLED is 573 true, the user timeout value (or, if provided, the value ADV_UTO) 574 will be advertised for the TCP on the other side of the connection 575 to adapt its own user timeout accordingly. UTO_ENABLED controls 576 whether the UTO option is enabled for a connection. This applies 577 to both sending and receiving. CHANGEABLE controls whether the 578 user timeout may be changed based on a UTO option received from 579 the other end of the connection; it becomes false when 'timeout 580 value' is used. 582 o CHANGE-TIMEOUT.SCTP: 583 Pass 1 primitive / event: 'Change HeartBeat' combined with 'Set 584 Protocol Parameters' 585 Parameters: 'Change HeartBeat': heartbeat frequency; 'Set Protocol 586 Parameters': Association.Max.Retrans (whole association) or 587 Path.Max.Retrans (per socket) 588 Comments: Change Heartbeat can enable / disable heartbeats in SCTP 589 as well as change their frequency. The parameter 590 Association.Max.Retrans defines after how many unsuccessful 591 heartbeats the connection will be terminated; thus these two 592 primitives / parameters together can yield a similar behavior to 593 CHANGE-TIMEOUT.TCP. 595 o DISABLE-NAGLE.TCP: 596 Pass 1 primitive / event: not specified 597 Parameters: one boolean value 598 Comments: the Nagle algorithm delays data transmission to increase 599 the chance to send a full-sized segment. An application must be 600 able to disable this algorithm for a connection. This is related 601 to the no-bundle flag in DATA.SEND.SCTP. 603 o REQUESTHEARTBEAT.SCTP: 604 Pass 1 primitive / event: 'Request HeartBeat' 605 Parameters: socket 606 Returns: success or failure 607 Comments: requests an immediate heartbeat on a path, returning 608 success or failure. 610 o SETPROTOCOLPARAMETERS.SCTP: 611 Pass 1 primitive / event: 'Set Protocol Parameters' 612 Parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; RTO.Alpha; 613 RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 614 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst 616 o SETPRIMARY.SCTP: 617 Pass 1 primitive / event: 'Set Primary' 618 Parameters: socket 619 Returns: result of attempting this operation 620 Comments: update the current primary address to be used, based on 621 the set of available sockets of the association. 623 o ERROR.TCP: 624 Pass 1 primitive / event: 'ERROR_REPORT' 625 Returns: reason (encoding not specified); subreason (encoding not 626 specified) 627 Comments: soft errors that can be ignored without harm by many 628 applications; an application should be able to disable these 629 notifications. The reported conditions include at least: ICMP 630 error message arrived; Excessive Retransmissions. 632 o STATUS.SCTP: 633 Pass 1 primitive / event: 'Status' and 'NETWORK STATUS CHANGE' 634 notification 635 Returns: data block with information about a specified 636 association, containing: association connection state; socket 637 list; destination transport address reachability states; current 638 receiver window size; current congestion window sizes; number of 639 unacknowledged DATA chunks; number of DATA chunks pending receipt; 640 primary path; most recent SRTT on primary path; RTO on primary 641 path; SRTT and RTO on other destination addresses. The NETWORK 642 STATUS CHANGE notification informs the application about a socket 643 becoming active/inactive. 645 o CHANGE-DSCP.TCP: 646 Pass 1 primitive / event: not specified 647 Parameters: DSCP value 648 Comments: This allows an application to change the DSCP value. 649 For TCP this was originally specified for the TOS field [RFC1122], 650 which is here interpreted to refer to the DSField [RFC3260]. 652 TERMINATION: 653 Gracefully or forcefully closing a connection, or being informed 654 about this event happening. 656 o CLOSE.TCP: 657 Pass 1 primitive / event: 'close' 658 Comments: this terminates the sending side of a connection after 659 reliably delivering all remaining data. 661 o CLOSE.SCTP: 662 Pass 1 primitive / event: 'Shutdown' 663 Comments: this terminates a connection after reliably delivering 664 all remaining data. 666 o ABORT.TCP: 667 Pass 1 primitive / event: 'abort' 668 Comments: this terminates a connection without delivering 669 remaining data and sends an error message to the other side. 671 o ABORT.SCTP: 672 Pass 1 primitive / event: 'abort' 673 Parameters: abort reason to be given to the peer (optional) 674 Comments: this terminates a connection without delivering 675 remaining data and sends an error message to the other side. 677 o TIMEOUT.TCP: 678 Pass 1 primitive / event: 'USER TIMEOUT' event 679 Comments: the application is informed that the connection is 680 aborted. This event is executed on expiration of the timeout set 681 in CONNECTION.ESTABLISHMENT.CONNECT.TCP (possibly adjusted in 682 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 684 o TIMEOUT.SCTP: 685 Pass 1 primitive / event: 'COMMUNICATION LOST' event 686 Comments: the application is informed that the connection is 687 aborted. this event is executed on expiration of the timeout that 688 should be enabled by default (see beginning of section 8.3 in 689 [RFC4960]) and was possibly adjusted in 690 CONNECTION.MAINTENANCE.CHANGE-TIMEOOUT.SCTP. 692 o ABORT-EVENT.TCP: 693 Pass 1 primitive / event: not specified. 695 o ABORT-EVENT.SCTP: 696 Pass 1 primitive / event: 'COMMUNICATION LOST' event 697 Returns: abort reason from the peer (if available) 698 Comments: the application is informed that the other side has 699 aborted the connection using CONNECTION.TERMINATION.ABORT.SCTP. 701 o CLOSE-EVENT.TCP: 702 Pass 1 primitive / event: not specified. 704 o CLOSE-EVENT.SCTP: 705 Pass 1 primitive / event: 'SHUTDOWN COMPLETE' event 706 Comments: the application is informed that 707 CONNECTION.TERMINATION.CLOSE.SCTP was successfully completed. 709 4.2. DATA Transfer Related Primitives 711 All primitives in this section refer to an existing connection, i.e. 712 a connection that was either established or made available for 713 receiving data. In addition to the listed parameters, all sending 714 primitives contain a reference to a data block and all receiving 715 primitives contain a reference to available buffer space for the 716 data. 718 o SEND.TCP: 719 Pass 1 primitive / event: 'send' 720 Parameters: timeout (optional) 721 Comments: this gives TCP a data block for reliable transmission to 722 the TCP on the other side of the connection. The timeout can be 723 configured with this call whenever data are sent (see also 724 CONNECTION.MAINTENANCE.CHANGE-TIMEOUT.TCP). 726 o SEND.SCTP: 727 Pass 1 primitive / event: 'Send' 728 Parameters: stream number; context (optional); life time 729 (optional); socket (optional); unordered flag (optional); no- 730 bundle flag (optional); payload protocol-id (optional) 731 Comments: this gives SCTP a data block for reliable transmission 732 to the SCTP on the other side of the connection (SCTP 733 association). The 'stream number' denotes the stream to be used. 734 The 'context' number can later be used to refer to the correct 735 message when an error is reported. The 'life time' specifies a 736 time after which this data block will not be sent. The 'socket' 737 can be used to state which path should be preferred, if there are 738 multiple paths available (see also 739 CONNECTION.MAINTENANCE.SETPRIMARY.SCTP). The data block can be 740 delivered out-of-order if the 'unordered flag' is set. The 'no- 741 bundle flag' can be set to indicate a preference to avoid 742 bundling. The 'payload protocol-id' is a number that will, if 743 provided, be handed over to the receiving application. 745 o RECEIVE.TCP: 746 Pass 1 primitive / event: 'receive'. 748 o RECEIVE.SCTP: 749 Pass 1 primitive / event: 'DATA ARRIVE' notification, followed by 750 'Receive' 751 Parameters: stream number (optional) 752 Returns: stream sequence number (optional), partial flag 753 (optional) 754 Comments: if the 'stream number' is provided, the call to receive 755 only receives data on one particular stream. If a partial message 756 arrives, this is indicated by the 'partial flag', and then the 757 'stream sequence number' must be provided such that an application 758 can restore the correct order of data blocks that comprise an 759 entire message. 761 o SENDFAILURE-EVENT.SCTP: 762 Pass 1 primitive / event: 'SEND FAILURE' notification, optionally 763 followed by 'Receive Unsent Message' or 'Receive Unacknowledged 764 Message' 765 Returns: cause code; context; unsent or unacknowledged message 766 (optional) 767 Comments: 'cause code' indicates the reason of the failure, and 768 'context' is the context number if such a number has been provided 769 in DATA.SEND.SCTP, for later use with 'Receive Unsent Message' or 770 'Receive Unacknowledged Message', respectively. These primitives 771 can be used to retrieve the complete unsent or unacknowledged 772 message if desired. 774 5. Pass 3 776 This section presents the superset of all transport service features 777 in all protocols that were discussed in the preceding sections, based 778 on the list of primitives in pass 2 but also on text in pass 1 to 779 include features that can be configured in one protocol and are 780 static properties in another. Again, some minor details are omitted 781 for the sake of generalization -- e.g., TCP may provide various 782 different IP options, but only source route is mandatory to 783 implement, and this detail is not visible in the Pass 3 feature 784 "Specify IP Options". 786 [AUTHOR'S NOTE: the list here looks pretty similar to the list in 787 pass 2 for now. This will change as more protocols are added. For 788 example, when we add UDP, we will find that UDP does not do 789 congestion control, which is relevant to the application using it. 790 This will have to be reflected in pass 1 and pass 2, only for UDP. 791 In pass 3, we can then derive "no congestion control" as a transport 792 service feature of UDP; however, since it would be strange to call 793 the lack of congestion control a feature, the natural outcome is then 794 to list "congestion control" as a feature of TCP and SCTP.] 796 5.1. CONNECTION Related Transport Service Features 798 ESTABLISHMENT: 799 Active creation of a connection from one transport endpoint to one or 800 more transport endpoints. 802 o Specify IP Options 803 Protocols: TCP 805 o Request multiple streams 806 Protocols: SCTP 808 o Obtain multiple sockets 809 Protocols: SCTP 811 AVAILABILITY: 812 Preparing to receive incoming connection requests. 814 o Listen, 1 specified local interface 815 Protocols: TCP, SCTP 817 o Listen, N specified local interfaces 818 Protocols: SCTP 820 o Listen, all local interfaces (unspecified) 821 Protocols: TCP, SCTP 823 o Obtain requested number of streams 824 Protocols: SCTP 826 MAINTENANCE: 827 Adjustments made to an open connection, or notifications about it. 828 NOTE: all features except "set primary path" in this category apply 829 to one out of multiple possible paths (identified via sockets) in 830 SCTP, whereas TCP uses only one path (one socket). 832 o Change timeout for aborting connection (using retransmit limit or 833 time value) 834 Protocols: TCP, SCTP 836 o Control advertising timeout for aborting connection to remote 837 endpoint 838 Protocols: TCP 840 o Disable Nagle algorithm 841 Protocols: TCP, SCTP 842 Comments: This is not specified in [RFC4960] but in [RFC6458]. 844 o Request an immediate heartbeat, returning success/failure 845 Protocols: SCTP 847 o Set protocol parameters 848 Protocols: SCTP 849 SCTP parameters: RTO.Initial; RTO.Min; RTO.Max; Max.Burst; 850 RTO.Alpha; RTO.Beta; Valid.Cookie.Life; Association.Max.Retrans; 851 Path.Max.Retrans; Max.Init.Retransmits; HB.interval; HB.Max.Burst 852 Comments: in future versions of this document, it might make sense 853 to split out some of these parameters -- e.g., if a different 854 protocol provides means to adjust the RTO calculation there could 855 be a common feature for them called "adjust RTO calculation". 857 o Notification of Excessive Retransmissions (early warning below 858 abortion threshold) 859 Protocols: TCP 861 o Notification of ICMP error message arrival 862 Protocols: TCP 864 o Status (query or notification) 865 Protocols: SCTP 866 SCTP parameters: association connection state; socket list; socket 867 reachability states; current receiver window size; current 868 congestion window sizes; number of unacknowledged DATA chunks; 869 number of DATA chunks pending receipt; primary path; most recent 870 SRTT on primary path; RTO on primary path; SRTT and RTO on other 871 destination addresses; socket becoming active / inactive 873 o Set primary path 874 Protocols: SCTP 876 o Change DSCP 877 Protocols: TCP 878 Comments: This is described to be changeable for SCTP too in 879 [RFC6458]. 881 TERMINATION: 882 Gracefully or forcefully closing a connection, or being informed 883 about this event happening. 885 o Close after reliably delivering all remaining data, causing an 886 event informing the application on the other side 887 Protocols: TCP, SCTP 888 Comments: A TCP endpoint locally only closes the connection for 889 sending; it may still receive data afterwards. 891 o Abort without delivering remaining data, causing an event 892 informing the application on the other side 893 Protocols: TCP, SCTP 894 Comments: In SCTP a reason can optionally be given by the 895 application on the aborting side, which can then be received by 896 the application on the other side. 898 o Timeout event when data could not be delivered for too long 899 Protocols: TCP, SCTP 900 Comments: the timeout is configured with CONNECTION.MAINTENANCE 901 "Change timeout for aborting connection (using retransmit limit or 902 time value)". 904 5.2. DATA Transfer Related Transport Service Features 906 All features in this section refer to an existing connection, i.e. a 907 connection that was either established or made available for 908 receiving data. Reliable data transfer entails delay -- e.g. for the 909 sender to wait until it can transmit data, or due to retransmission 910 in case of packet loss. 912 5.2.1. Sending Data 914 All features in this section are provided by DATA.SEND from pass 2. 915 DATA.SEND is given a data block from the application, which we here 916 call a "message". 918 o Reliably transfer data 919 Protocols: TCP, SCTP 921 o Notifying the receiver to promptly hand over data to application 922 Protocols: TCP 923 Comments: This seems unnecessary in SCTP, where data arrival 924 causes an event for the application. 926 o Message identification 927 Protocols: SCTP 929 o Choice of stream 930 Protocols: SCTP 932 o Choice of path (destination address) 933 Protocols: SCTP 935 o Message lifetime 936 Protocols: SCTP 938 o Choice between unordered (potentially faster) or ordered delivery 939 Protocols: SCTP 941 o Request not to bundle messages 942 Protocols: SCTP 944 o Specifying a "payload protocol-id" (handed over as such by the 945 receiver) 946 Protocols: SCTP 948 5.2.2. Receiving Data 950 All features in this section are provided by DATA.RECEIVE from pass 951 2. DATA.RECEIVE fills a buffer provided to the application, with 952 what we here call a "message". 954 o Receive data 955 Protocols: TCP, SCTP 957 o Choice of stream to receive from 958 Protocols: SCTP 960 o Message identification 961 Protocols: SCTP 962 Comments: In SCTP, this is optionally achieved with a "stream 963 sequence number". The stream sequence number is always provided 964 in case of partial message arrival. 966 o Information about partial message arrival 967 Protocols: SCTP 968 Comments: In SCTP, partial messages are combined with a stream 969 sequence number so that the application can restore the correct 970 order of data blocks an entire message consists of. 972 5.2.3. Errors 974 This section describes sending failures that are associated with a 975 specific call to DATA.SEND from pass 2. 977 o Notification of unsent messages 978 Protocols: SCTP 980 o Notification of unacknowledged messages 981 Protocols: SCTP 983 6. Acknowledgements 985 The authors would like to thank (in alphabetical order) Bob Briscoe, 986 David Hayes, Gorry Fairhurst, Karen Nielsen and Joe Touch for 987 providing valuable feedback on this document. This work has received 988 funding from the European Union's Horizon 2020 research and 989 innovation programme under grant agreement No. 644334 (NEAT). The 990 views expressed are solely those of the author(s). 992 7. IANA Considerations 994 XX RFC ED - PLEASE REMOVE THIS SECTION XXX 996 This memo includes no request to IANA. 998 8. Security Considerations 1000 Security will be considered in future versions of this document. 1002 9. References 1004 9.1. Normative References 1006 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1007 RFC 793, DOI 10.17487/RFC0793, September 1981, 1008 . 1010 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 1011 Communication Layers", STD 3, RFC 1122, DOI 10.17487/ 1012 RFC1122, October 1989, 1013 . 1015 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1016 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1017 . 1019 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 1020 RFC 5482, DOI 10.17487/RFC5482, March 2009, 1021 . 1023 9.2. Informative References 1025 [FA15] Fairhurst, Ed., G., Trammell, Ed., B., and M. Kuehlewind, 1026 Ed., "Services provided by IETF transport protocols and 1027 congestion control mechanisms", 1028 draft-fairhurst-taps-transports-08.txt (work in progress), 1029 December 2015. 1031 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 1032 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, 1033 May 1983, . 1035 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1036 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1037 RFC2119, March 1997, 1038 . 1040 [RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The Addition 1041 of Explicit Congestion Notification (ECN) to IP", 1042 RFC 3168, DOI 10.17487/RFC3168, September 2001, 1043 . 1045 [RFC3260] Grossman, D., "New Terminology and Clarifications for 1046 Diffserv", RFC 3260, DOI 10.17487/RFC3260, April 2002, 1047 . 1049 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., Ed., 1050 and G. Fairhurst, Ed., "The Lightweight User Datagram 1051 Protocol (UDP-Lite)", RFC 3828, DOI 10.17487/RFC3828, 1052 July 2004, . 1054 [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, 1055 DOI 10.17487/RFC5461, February 2009, 1056 . 1058 [RFC6093] Gont, F. and A. Yourtchenko, "On the Implementation of the 1059 TCP Urgent Mechanism", RFC 6093, DOI 10.17487/RFC6093, 1060 January 2011, . 1062 [RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1063 Yasevich, "Sockets API Extensions for the Stream Control 1064 Transmission Protocol (SCTP)", RFC 6458, DOI 10.17487/ 1065 RFC6458, December 2011, 1066 . 1068 [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. 1069 Zimmermann, "A Roadmap for Transmission Control Protocol 1070 (TCP) Specification Documents", RFC 7414, DOI 10.17487/ 1071 RFC7414, February 2015, 1072 . 1074 Appendix A. Overview of RFCs used as input for pass 1 1076 TCP: [RFC0793], [RFC1122], [RFC5482] 1077 SCTP: [RFC4960], planned: [RFC6458] 1079 Appendix B. How to contribute 1081 This document is only concerned with transport service features that 1082 are explicitly exposed to applications via primitives. It also 1083 strictly follows RFC text: if a feature is truly relevant for an 1084 application, the RFCs better say so and in some way describe how to 1085 use and configure it. Thus, the approach to follow for contributing 1086 to this document is to identify the right RFCs, then analyze and 1087 process their text. 1089 Experimental RFCs are excluded, and so are primitives that MAY be 1090 implemented (by the transport protocol). To be included, the minimum 1091 requirement level for a primitive to be implemented by a protocol is 1092 SHOULD. If [RFC2119]-style requirements levels are not used, 1093 primitives should be excluded when they are described in conjunction 1094 with statements like, e.g.: "some implementations also provide" or 1095 "an implementation may also". Briefly describe excluded primitives 1096 in a subsection called "excluded primitives". 1098 Pass 1: Identify text that talks about primitives. An API 1099 specification, abstract or not, obviously describes primitives -- but 1100 note that we are not *only* interested in API specifications. The 1101 text describing the 'send' primitive in the API specified in 1103 [RFC0793], for instance, does not say that data transfer is reliable. 1104 TCP's reliability is clear, however, from this text in Section 1 of 1105 [RFC0793]: "The Transmission Control Protocol (TCP) is intended for 1106 use as a highly reliable host-to-host protocol between hosts in 1107 packet-switched computer communication networks, and in 1108 interconnected systems of such networks." 1110 For the new pass 1 subsection about the protocol you're describing, 1111 it is recommendable to begin by copy+pasting all the relevant text 1112 parts from the relevant RFCs, then adjust terminology to match the 1113 terminology in Section 1 and adjust (shorten!) phrasing to match the 1114 general style of the document. Try to formulate everything as a 1115 primitive description to make the primitive description as complete 1116 as possible (e.g., the "SEND.TCP" primitive in pass 2 is explicitly 1117 described as reliably transferring data); if there is text that is 1118 relevant for the primitives presented in this pass but still does not 1119 fit directly under any primitive, use it as an introduction for your 1120 subsection. However, do note that document length is a concern and 1121 all the protocols and their services / features are already described 1122 in [FA15]. 1124 Pass 2: The main goal of this pass is unification of primitives. As 1125 input, use your own text from Pass 1, no exterior sources. If you 1126 find that something is missing there, fix the text in Pass 1. The 1127 list in pass 2 is not done by protocol ("first protocol X, here are 1128 all the primitives; then protocol Y, here are all the primitives, 1129 ..") but by primitive ("primitive A, implemented this way in protocol 1130 X, this way in protocol Y, ..."). We want as many similar pass 2 1131 primitives as possible. This can be achieved, for instance, by not 1132 always maintaining a 1:1 mapping between pass 1 and pass 2 1133 primitives, renaming primitives etc. Please consider the primitives 1134 that are already there and try to make the ones of the protocol you 1135 are describing as much in line with the already existing ones as 1136 possible. In other words, we would rather have a primitive with new 1137 parameters than a new primitive that allows to send in a particular 1138 way. 1140 Please make primitives fit within the already existing categories and 1141 subcategories. For each primitive, please follow the style: 1143 o PRIMITIVENAME.PROTOCOL: 1144 Pass 1 primitive / event: 1145 Parameters: 1146 Returns: 1147 Comments: 1149 The entries "Parameters", "Returns" and "Comments" may be skipped if 1150 a primitive has no parameters, no described return value or no 1151 comments seem necessary, respectively. Optional parameters must be 1152 followed by "(optional)". If a default value is known, provide it 1153 too. 1155 Pass 3: the main point of this pass is to identify features that are 1156 the result of static properties of protocols, for which all protocols 1157 have to be listed together; this is then the final list of all 1158 available features. For this, we need a list of features per 1159 category (similar categories as in pass 2) along with the protocol 1160 supporting it. This should be primarily based on text from pass 2 as 1161 input, but text from pass 1 can also be used. Do not use external 1162 sources. 1164 Appendix C. Revision information 1166 XXX RFC-Ed please remove this section prior to publication. 1168 -00 (from draft-welzl-taps-transports): this now covers TCP based on 1169 all TCP RFCs (this means: if you know of something in any TCP RFC 1170 that you think should be addressed, please speak up!) as well as 1171 SCTP, exclusively based on [RFC4960]. We decided to also incorporate 1172 [RFC6458] for SCTP, but this hasn't happened yet. Terminology made 1173 in line with [FA15]. Addressed comments by Karen Nielsen and Gorry 1174 Fairhurst; various other fixes. Appendices (TCP overview and how-to- 1175 contribute) added. 1177 Authors' Addresses 1179 Michael Welzl 1180 University of Oslo 1181 PO Box 1080 Blindern 1182 Oslo, N-0316 1183 Norway 1185 Phone: +47 22 85 24 20 1186 Email: michawe@ifi.uio.no 1188 Michael Tuexen 1189 Muenster University of Applied Sciences 1190 Stegerwaldstrasse 39 1191 Steinfurt 48565 1192 Germany 1194 Email: tuexen@fh-muenster.de 1195 Naeem Khademi 1196 University of Oslo 1197 PO Box 1080 Blindern 1198 Oslo, N-0316 1199 Norway 1201 Email: naeemk@ifi.uio.no