idnits 2.17.00 (12 Aug 2021) /tmp/idnits42753/draft-ietf-taps-interface-15.txt: -(3710): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** There are 4 instances of too long lines in the document, the longest one being 12 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (7 March 2022) is 68 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'HostCandidate' is mentioned on line 513, but not defined == Missing Reference: 'StunCandidate' is mentioned on line 513, but not defined ** Downref: Normative reference to an Informational RFC: RFC 8303 == Outdated reference: A later version (-12) exists of draft-ietf-taps-impl-11 -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft Google Switzerland GmbH 4 Intended status: Standards Track M. Welzl, Ed. 5 Expires: 8 September 2022 University of Oslo 6 T. Enghardt 7 Netflix 8 G. Fairhurst 9 University of Aberdeen 10 M. Kuehlewind 11 Ericsson 12 C. Perkins 13 University of Glasgow 14 P. Tiesel 15 SAP SE 16 T. Pauly 17 Apple Inc. 18 7 March 2022 20 An Abstract Application Layer Interface to Transport Services 21 draft-ietf-taps-interface-15 23 Abstract 25 This document describes an abstract application programming 26 interface, API, to the transport layer that enables the selection of 27 transport protocols and network paths dynamically at runtime. This 28 API enables faster deployment of new protocols and protocol features 29 without requiring changes to the applications. The specified API 30 follows the Transport Services architecture by providing 31 asynchronous, atomic transmission of messages. It is intended to 32 replace the BSD sockets API as the common interface to the transport 33 layer, in an environment where endpoints could select from multiple 34 interfaces and potential transport protocols. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on 8 September 2022. 53 Copyright Notice 55 Copyright (c) 2022 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 60 license-info) in effect on the date of publication of this document. 61 Please review these documents carefully, as they describe your rights 62 and restrictions with respect to this document. Code Components 63 extracted from this document must include Revised BSD License text as 64 described in Section 4.e of the Trust Legal Provisions and are 65 provided without warranty as described in the Revised BSD License. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 70 1.1. Terminology and Notation . . . . . . . . . . . . . . . . 5 71 1.2. Specification of Requirements . . . . . . . . . . . . . . 7 72 2. Overview of the API Design . . . . . . . . . . . . . . . . . 7 73 3. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 3.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 9 75 3.1.1. Server Example . . . . . . . . . . . . . . . . . . . 9 76 3.1.2. Client Example . . . . . . . . . . . . . . . . . . . 10 77 3.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 12 78 4. Transport Properties . . . . . . . . . . . . . . . . . . . . 13 79 4.1. Transport Property Names . . . . . . . . . . . . . . . . 14 80 4.2. Transport Property Types . . . . . . . . . . . . . . . . 15 81 5. Scope of the API Definition . . . . . . . . . . . . . . . . . 15 82 6. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 16 83 6.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 17 84 6.1.1. Using Multicast Endpoints . . . . . . . . . . . . . . 19 85 6.1.2. Constraining Interfaces for Endpoints . . . . . . . . 19 86 6.1.3. Endpoint Aliases . . . . . . . . . . . . . . . . . . 20 87 6.1.4. Endpoint Examples . . . . . . . . . . . . . . . . . . 20 88 6.1.5. Multicast Examples . . . . . . . . . . . . . . . . . 21 89 6.2. Specifying Transport Properties . . . . . . . . . . . . . 23 90 6.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 26 91 6.2.2. Preservation of Message Boundaries . . . . . . . . . 27 92 6.2.3. Configure Per-Message Reliability . . . . . . . . . . 27 93 6.2.4. Preservation of Data Ordering . . . . . . . . . . . . 27 94 6.2.5. Use 0-RTT Session Establishment with a Safely 95 Replayable Message . . . . . . . . . . . . . . . . . 27 96 6.2.6. Multistream Connections in Group . . . . . . . . . . 28 97 6.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 28 98 6.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 28 99 6.2.9. Congestion control . . . . . . . . . . . . . . . . . 29 100 6.2.10. Keep alive . . . . . . . . . . . . . . . . . . . . . 29 101 6.2.11. Interface Instance or Type . . . . . . . . . . . . . 29 102 6.2.12. Provisioning Domain Instance or Type . . . . . . . . 30 103 6.2.13. Use Temporary Local Address . . . . . . . . . . . . . 31 104 6.2.14. Multipath Transport . . . . . . . . . . . . . . . . . 32 105 6.2.15. Advertisement of Alternative Addresses . . . . . . . 33 106 6.2.16. Direction of communication . . . . . . . . . . . . . 33 107 6.2.17. Notification of ICMP soft error message arrival . . . 34 108 6.2.18. Initiating side is not the first to write . . . . . . 34 109 6.3. Specifying Security Parameters and Callbacks . . . . . . 35 110 6.3.1. Specifying Security Parameters on a Pre-Connection . 35 111 6.3.2. Connection Establishment Callbacks . . . . . . . . . 37 112 7. Establishing Connections . . . . . . . . . . . . . . . . . . 37 113 7.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 38 114 7.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 39 115 7.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 40 116 7.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 42 117 7.5. Adding and Removing Endpoints on a Connection . . . . . . 44 118 8. Managing Connections . . . . . . . . . . . . . . . . . . . . 44 119 8.1. Generic Connection Properties . . . . . . . . . . . . . . 46 120 8.1.1. Required Minimum Corruption Protection Coverage for 121 Receiving . . . . . . . . . . . . . . . . . . . . . . 46 122 8.1.2. Connection Priority . . . . . . . . . . . . . . . . . 47 123 8.1.3. Timeout for Aborting Connection . . . . . . . . . . . 47 124 8.1.4. Timeout for keep alive packets . . . . . . . . . . . 47 125 8.1.5. Connection Group Transmission Scheduler . . . . . . . 48 126 8.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 48 127 8.1.7. Policy for using Multipath Transports . . . . . . . . 50 128 8.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 51 129 8.1.9. Group Connection Limit . . . . . . . . . . . . . . . 51 130 8.1.10. Isolate Session . . . . . . . . . . . . . . . . . . . 51 131 8.1.11. Read-only Connection Properties . . . . . . . . . . . 52 132 8.2. TCP-specific Properties: User Timeout Option (UTO) . . . 53 133 8.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 53 134 8.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 53 135 8.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 54 136 8.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 54 137 8.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 54 138 8.3.2. Path change . . . . . . . . . . . . . . . . . . . . . 54 139 9. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 54 140 9.1. Messages and Framers . . . . . . . . . . . . . . . . . . 55 141 9.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 55 142 9.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 55 143 9.1.3. Message Properties . . . . . . . . . . . . . . . . . 58 144 9.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 64 145 9.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 64 146 9.2.2. Send Events . . . . . . . . . . . . . . . . . . . . . 65 147 9.2.3. Partial Sends . . . . . . . . . . . . . . . . . . . . 66 148 9.2.4. Batching Sends . . . . . . . . . . . . . . . . . . . 66 149 9.2.5. Send on Active Open: InitiateWithSend . . . . . . . . 67 150 9.2.6. Priority and the Transport Services API . . . . . . . 67 151 9.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 68 152 9.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 68 153 9.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 69 154 9.3.3. Receive Message Properties . . . . . . . . . . . . . 71 155 10. Connection Termination . . . . . . . . . . . . . . . . . . . 73 156 11. Connection State and Ordering of Operations and Events . . . 74 157 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76 158 13. Privacy and Security Considerations . . . . . . . . . . . . . 76 159 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 78 160 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 161 15.1. Normative References . . . . . . . . . . . . . . . . . . 78 162 15.2. Informative References . . . . . . . . . . . . . . . . . 79 163 Appendix A. Implementation Mapping . . . . . . . . . . . . . . . 83 164 A.1. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 83 165 A.2. Events and Errors . . . . . . . . . . . . . . . . . . . . 84 166 A.3. Time Duration . . . . . . . . . . . . . . . . . . . . . . 84 167 Appendix B. Convenience Functions . . . . . . . . . . . . . . . 84 168 B.1. Adding Preference Properties . . . . . . . . . . . . . . 84 169 B.2. Transport Property Profiles . . . . . . . . . . . . . . . 84 170 B.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 84 171 B.2.2. reliable-message . . . . . . . . . . . . . . . . . . 85 172 B.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 85 173 Appendix C. Relationship to the Minimal Set of Transport Services 174 for End Systems . . . . . . . . . . . . . . . . . . . . . 86 175 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 89 177 1. Introduction 179 This document specifies an abstract application programming interface 180 (API) that specifies the interface component of the high-level 181 Transport Services architecture defined in [I-D.ietf-taps-arch]. A 182 Transport Services system supports asynchronous, atomic transmission 183 of messages over transport protocols and network paths dynamically 184 selected at runtime, in environments where an endpoint selects from 185 multiple interfaces and potential transport protocols. 187 Applications that adopt this API will benefit from a wide set of 188 transport features that can evolve over time. This protocol- 189 independent API ensures that the system providing the API can 190 optimize its behavior based on the application requirements and 191 network conditions, without requiring changes to the applications. 192 This flexibility enables faster deployment of new features and 193 protocols, and can support applications by offering racing and 194 fallback mechanisms, which otherwise need to be separately 195 implemented in each application. 197 The Transport Services system derives specific path and protocol 198 selection properties and supported transport features from the 199 analysis provided in [RFC8095], [RFC8923], and [RFC8922]. The 200 Transport Services API enables an implementation to dynamically 201 choose a transport protocol rather than statically binding 202 applications to a protocol at compile time. The Transport Services 203 API also provides applications with a way to override transport 204 selection and instantiate a specific stack, e.g., to support servers 205 wishing to listen to a specific protocol. However, forcing a choice 206 to use a specific transport stack is discouraged for general use, 207 because it can reduce portability. 209 1.1. Terminology and Notation 211 The Transport Services API is described in terms of 213 * Objects with which an application can interact; 215 * Actions the application can perform on these Objects; 217 * Events, which an Object can send to an application to be processed 218 aynchronously; and 220 * Parameters associated with these Actions and Events. 222 The following notations, which can be combined, are used in this 223 document: 225 * An Action that creates an Object: 227 Object := Action() 229 * An Action that creates an array of Objects: 231 []Object := Action() 233 * An Action that is performed on an Object: 235 Object.Action() 237 * An Object sends an Event: 239 Object -> Event<> 241 * An Action takes a set of Parameters; an Event contains a set of 242 Parameters. Action and Event parameters whose names are suffixed 243 with a question mark are optional. 245 Action(param0, param1?, ...) / Event 247 Objects that are passed as parameters to Actions use call-by-value 248 behavior. Actions associated with no Object are Actions on the API; 249 they are equivalent to Actions on a per-application global context. 251 Events are sent to the application or application-supplied code (e.g. 252 framers, see Section 9.1.2) for processing; the details of event 253 processing are platform- and implementation-specific. 255 We also make use of the following basic types: 257 * Boolean: Instances take the value true or false. 259 * Integer: Instances take positive or negative integer values. 261 * Numeric: Instances take positive or negative real number values. 263 * Enumeration: A family of types in which each instance takes one of 264 a fixed, predefined set of values specific to a given enumerated 265 type. 267 * Tuple: An ordered grouping of multiple value types, represented as 268 a comma-separated list in parentheses, e.g., (Enumeration, 269 Preference). Instances take a sequence of values each valid for 270 the corresponding value type. 272 * Array: Denoted []Type, an instance takes a value for each of zero 273 or more elements in a sequence of the given Type. An array may be 274 of fixed or variable length. 276 * Collection: An unordered grouping of one or more values of the 277 same type. 279 For guidance on how these abstract concepts may be implemented in 280 languages in accordance with native design patterns and language and 281 platform features, see Appendix A. 283 1.2. Specification of Requirements 285 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 286 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 287 "OPTIONAL" in this document are to be interpreted as described in BCP 288 14 [RFC2119] [RFC8174] when, and only when, they appear in all 289 capitals, as shown here. 291 2. Overview of the API Design 293 The design of the API specified in this document is based on a set of 294 principles, themselves an elaboration on the architectural design 295 principles defined in [I-D.ietf-taps-arch]. The API defined in this 296 document provides: 298 * A Transport Services system can offer a variety of transport 299 protocols, independent of the Protocol Stacks that will be used at 300 runtime. All common features of these protocol stacks are made 301 available to the application in a transport-independent way to the 302 degree possible. This enables applications written to a single 303 API to make use of transport protocols in terms of the features 304 they provide. 306 * A unified API to datagram and stream-oriented transports, allowing 307 use of a common API for connection establishment and closing. 309 * Message-orientation, as opposed to stream-orientation, using 310 application-assisted framing and deframing where the underlying 311 transport does not provide these. 313 * Asynchronous Connection establishment, transmission, and 314 reception. This allows concurrent operations during establishment 315 and event-driven application interactions with the transport 316 layer; 318 * Selection between alternate network paths, using additional 319 information about the networks over which a connection can operate 320 (e.g. Provisioning Domain (PvD) information [RFC7556]) where 321 available. 323 * Explicit support for transport-specific features to be applied, 324 should that particular transport be part of a chosen Protocol 325 Stack. 327 * Explicit support for security properties as first-order transport 328 features. 330 * Explicit support for configuration of cryptographic identities and 331 transport security parameters persistent across multiple 332 Connections. 334 * Explicit support for multistreaming and multipath transport 335 protocols, and the grouping of related Connections into Connection 336 Groups through "cloning" of Connections (see Section 7.4). This 337 function allows applications to take full advantage of new 338 transport protocols supporting these features. 340 3. API Summary 342 An application primarily interacts with this API through two Objects: 343 Preconnections and Connections. A Preconnection object (Section 6) 344 represents a set of properties and constraints on the selection and 345 configuration of paths and protocols to establish a Connection with 346 an Endpoint. A Connection object represents an instance of a 347 transport Protocol Stack on which data can be sent to and/or received 348 from a Remote Endpoint (i.e., a logical connection that, depending on 349 the kind of transport, can be bi-directional or unidirectional, and 350 that can use a stream protocol or a datagram protocol). Connections 351 are presented consistently to the application, irrespective of 352 whether the underlying transport is connection-less or connection- 353 oriented. Connections can be created from Preconnections in three 354 ways: 356 * by initiating the Preconnection (i.e., actively opening, as in a 357 client; Section 7.1), 359 * through listening on the Preconnection (i.e., passively opening, 360 as in a server Section 7.2), 362 * or rendezvousing on the Preconnection (i.e., peer to peer 363 establishment; Section 7.3). 365 Once a Connection is established, data can be sent and received on it 366 in the form of Messages. The API supports the preservation of 367 message boundaries both via explicit Protocol Stack support, and via 368 application support through a Message Framer that finds message 369 boundaries in a stream. Messages are received asynchronously through 370 event handlers registered by the application. Errors and other 371 notifications also happen asynchronously on the Connection. It is 372 not necessary for an application to handle all Events; some Events 373 may have implementation-specific default handlers. The application 374 should not assume that ignoring Events (e.g., Errors) is always safe. 376 3.1. Usage Examples 378 The following usage examples illustrate how an application might use 379 the Transport Services API to: 381 * Act as a server, by listening for incoming connections, receiving 382 requests, and sending responses, see Section 3.1.1. 384 * Act as a client, by connecting to a Remote Endpoint using 385 Initiate, sending requests, and receiving responses, see 386 Section 3.1.2. 388 * Act as a peer, by connecting to a Remote Endpoint using Rendezvous 389 while simultaneously waiting for incoming Connections, sending 390 Messages, and receiving Messages, see Section 3.1.3. 392 The examples in this section presume that a transport protocol is 393 available between the Local and Remote Endpoints that provides 394 Reliable Data Transfer, Preservation of Data Ordering, and 395 Preservation of Message Boundaries. In this case, the application 396 can choose to receive only complete messages. 398 If none of the available transport protocols provides Preservation of 399 Message Boundaries, but there is a transport protocol that provides a 400 reliable ordered byte stream, an application could receive this byte 401 stream as partial Messages and transform it into application-layer 402 Messages. Alternatively, an application might provide a Message 403 Framer, which can transform a sequence of Messages into a byte stream 404 and vice versa (Section 9.1.2). 406 3.1.1. Server Example 408 This is an example of how an application might listen for incoming 409 Connections using the Transport Services API, and receive a request, 410 and send a response. 412 LocalSpecifier := NewLocalEndpoint() 413 LocalSpecifier.WithInterface("any") 414 LocalSpecifier.WithService("https") 416 TransportProperties := NewTransportProperties() 417 TransportProperties.Require(preserve-msg-boundaries) 418 // Reliable Data Transfer and Preserve Order are Required by default 420 SecurityParameters := NewSecurityParameters() 421 SecurityParameters.Set(identity, myIdentity) 422 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 424 // Specifying a Remote Endpoint is optional when using Listen() 425 Preconnection := NewPreconnection(LocalSpecifier, 426 TransportProperties, 427 SecurityParameters) 429 Listener := Preconnection.Listen() 431 Listener -> ConnectionReceived 433 // Only receive complete messages in a Conn.Received handler 434 Connection.Receive() 436 Connection -> Received 438 //---- Receive event handler begin ---- 439 Connection.Send(messageDataResponse) 440 Connection.Close() 442 // Stop listening for incoming Connections 443 // (this example supports only one Connection) 444 Listener.Stop() 445 //---- Receive event handler end ---- 447 3.1.2. Client Example 449 This is an example of how an application might open two Connections 450 to a remote application using the Transport Services API, and send a 451 request as well as receive a response on each of them. 453 RemoteSpecifier := NewRemoteEndpoint() 454 RemoteSpecifier.WithHostname("example.com") 455 RemoteSpecifier.WithService("https") 457 TransportProperties := NewTransportProperties() 458 TransportProperties.Require(preserve-msg-boundaries) 459 // Reliable Data Transfer and Preserve Order are Required by default 461 SecurityParameters := NewSecurityParameters() 462 TrustCallback := NewCallback({ 463 // Verify identity of the Remote Endpoint, return the result 464 }) 465 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 467 // Specifying a local endpoint is optional when using Initiate() 468 Preconnection := NewPreconnection(RemoteSpecifier, 469 TransportProperties, 470 SecurityParameters) 472 Connection := Preconnection.Initiate() 473 Connection2 := Connection.Clone() 475 Connection -> Ready<> 476 Connection2 -> Ready<> 478 //---- Ready event handler for any Connection C begin ---- 479 C.Send(messageDataRequest) 481 // Only receive complete messages 482 C.Receive() 483 //---- Ready event handler for any Connection C end ---- 485 Connection -> Received 486 Connection2 -> Received 488 // Close the Connection in a Receive event handler 489 Connection.Close() 490 Connection2.Close() 492 Preconnections are reusable after being used to initiate a 493 Connection. Hence, for example, after the Connections were closed, 494 the following would be correct: 496 //.. carry out adjustments to the Preconnection, if desire 497 Connection := Preconnection.Initiate() 499 3.1.3. Peer Example 501 This is an example of how an application might establish a connection 502 with a peer using Rendezvous(), send a Message, and receive a 503 Message. 505 // Configure local candidates: a port on the Local Endpoint 506 // and via a STUN server 507 HostCandidate := NewLocalEndpoint() 508 HostCandidate.WithPort(9876) 510 StunCandidate := NewLocalEndpoint() 511 StunCandidate.WithStunServer(address, port, credentials) 513 LocalCandidates = [HostCandidate, StunCandidate] 515 // Configure transport and security properties 516 TransportProperties := ... 517 SecurityParameters := ... 519 Preconnection := NewPreconnection(LocalCandidates, 520 [], // No remote candidates yet 521 TransportProperties, 522 SecurityParameters) 524 // Resolve the LocalCandidates. The Preconnection.Resolve() call 525 // resolves both local and remote candidates but, since the remote 526 // candidates have not yet been specified, the ResolvedRemote list 527 // returned will be empty and is not used. 528 ResolvedLocal, ResolvedRemote = Preconnection.Resolve() 530 // ...Send the ResolvedLocal list to peer via signalling channel 531 // ...Receive a list of RemoteCandidates from peer via 532 // signalling channel 534 Preconnection.AddRemote(RemoteCandidates) 535 Preconnection.Rendezvous() 537 Preconnection -> RendezvousDone 539 //---- RendezvousDone event handler begin ---- 540 Connection.Send(messageDataRequest) 541 Connection.Receive() 542 //---- RendezvousDone event handler end ---- 544 Connection -> Received 546 // If new remote endpoint candidates are received from the peer over 547 // the signalling channel, for example if using Trickle ICE, then add 548 // them to the Connection: 549 Connection.AddRemote(NewRemoteCandidates) 551 // On a PathChange<> events, resolve the local endpoints to see if a 552 // new local endpoint has become available and, if so, send to the peer 553 // as a new candidate and add to the connection: 554 Connection -> PathChange<> 556 //---- PathChange event handler begin ---- 557 ResolvedLocal, ResolvedRemote = Preconnection.Resolve() 558 if ResolvedLocal has changed: 559 // ...Send the ResolvedLocal list to peer via signalling channel 560 // Add the new local endpoints to the connection: 561 Connection.AddLocal(ResolvedLocal) 562 //---- PathChange event handler end ---- 564 // Close the Connection in a Receive event handler 565 Connection.Close() 567 4. Transport Properties 569 Each application using the Transport Services API declares its 570 preferences for how the Transport Services system should operate. 571 This is done by using Transport Properties, as defined in 572 [I-D.ietf-taps-arch], at each stage of the lifetime of a connection. 574 Transport Properties are divided into Selection, Connection, and 575 Message Properties. Selection Properties (see Section 6.2) can only 576 be set during pre-establishment. They are only used to specify which 577 paths and protocol stacks can be used and are preferred by the 578 application. Although Connection Properties (see Section 8.1) can be 579 set during pre-establishment, they may be changed later. They are 580 used to inform decisions made during establishment and to fine-tune 581 the established connection. Calling Initiate on a Preconnection 582 creates an outbound Connection or a Listener, and the Selection 583 Properties remain readable from the Connection or Listener, but 584 become immutable. 586 The behavior of the selected protocol stack(s) when sending Messages 587 is controlled by Message Properties (see Section 9.1.3). 589 Selection Properties can be set on Preconnections, and the effect of 590 Selection Properties can be queried on Connections and Messages. 591 Connection Properties can be set on Connections and Preconnections; 592 when set on Preconnections, they act as an initial default for the 593 resulting Connections. Message Properties can be set on Messages, 594 Connections, and Preconnections; when set on the latter two, they act 595 as an initial default for the Messages sent over those Connections, 597 Note that configuring Connection Properties and Message Properties on 598 Preconnections is preferred over setting them later. Early 599 specification of Connection Properties allows their use as additional 600 input to the selection process. Protocol Specific Properties, which 601 enable configuration of specialized features of a specific protocol, 602 see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to 603 the selection process, but only support configuration if the 604 respective protocol has been selected. 606 4.1. Transport Property Names 608 Transport Properties are referred to by property names. For the 609 purposes of this document, these names are alphanumeric strings in 610 which words may be separated by hyphens. Specifically, the following 611 characters are allowed: lowercase letters a-z, uppercase letters A-Z, 612 digits 0-9, the hyphen -, and the underscore _. These names serve two 613 purposes: 615 * Allowing different components of a Transport Services 616 implementation to pass Transport Properties, e.g., between a 617 language frontend and a policy manager, or as a representation of 618 properties retrieved from a file or other storage. 620 * Making the code of different Transport Services implementations 621 look similar. While individual programming languages may preclude 622 strict adherence to the aforementioned naming convention (for 623 instance, by prohibiting the use of hyphens in symbols), users 624 interacting with multiple implementations will still benefit from 625 the consistency resulting from the use of visually similar 626 symbols. 628 Transport Property Names are hierarchically organized in the form 629 [.]. 631 * The Namespace component MUST be empty for well-known, generic 632 properties, i.e., for properties that are not specific to a 633 protocol and are defined in an RFC. 635 * Protocol Specific Properties MUST use the protocol acronym as the 636 Namespace, e.g., tcp for TCP specific Transport Properties. For 637 IETF protocols, property names under these namespaces SHOULD be 638 defined in an RFC. 640 * Vendor or implementation specific properties MUST use a string 641 identifying the vendor or implementation as the Namespace. 643 Namespaces for each of the keywords provided in the IANA protocol 644 numbers registry (see https://www.iana.org/assignments/protocol- 645 numbers/protocol-numbers.xhtml) are reserved for Protocol Specific 646 Properties and MUST NOT be used for vendor or implementation-specific 647 properties. Avoid using any of the terms listed as keywords in the 648 protocol numbers registry as any part of a vendor- or implementation- 649 specific property name. 651 4.2. Transport Property Types 653 Each Transport Property has a one of the basic types described in 654 Section 1.1. 656 Most Selection Properties (see Section 6.2) are of the Enumeration 657 type, and use the Preference Enumeration, which takes one of five 658 possible values (Prohibit, Avoid, Ignore, Prefer, or Require) 659 denoting the level of preference for a given property during protocol 660 selection. 662 5. Scope of the API Definition 664 This document defines a language- and platform-independent API of a 665 Transport Services system. Given the wide variety of languages and 666 language conventions used to write applications that use the 667 transport layer to connect to other applications over the Internet, 668 this independence makes this API necessarily abstract. 670 There is no interoperability benefit in tightly defining how the API 671 is presented to application programmers across diverse platforms. 672 However, maintaining the "shape" of the abstract API across different 673 platforms reduces the effort for programmers who learn to use the 674 Transport Services API to then apply their knowledge to another 675 platform. 677 We therefore make the following recommendations: 679 * Actions, Events, and Errors in implementations of the Transport 680 Services API SHOULD use the names given for them in the document, 681 subject to capitalization, punctuation, and other typographic 682 conventions in the language of the implementation, unless the 683 implementation itself uses different names for substantially 684 equivalent objects for networking by convention. 686 * Transport Services systems SHOULD implement each Selection 687 Property, Connection Property, and Message Context Property 688 specified in this document. The Transport Services API SHOULD be 689 implemented even when in a specific implementation/platform it 690 will always result in no operation, e.g. there is no action when 691 the API specifies a Property that is not available in a transport 692 protocol implemented on a specific platform. For example, if TCP 693 is the only underlying transport protocol, the Message Property 694 msgOrdered can be implemented (trivially, as a no-op) as disabling 695 the requirement for ordering will not have any effect on delivery 696 order for Connections over TCP. Similarly, the msg-lifetime 697 Message Property can be implemented but ignored, as the 698 description of this Property states that "it is not guaranteed 699 that a Message will not be sent when its Lifetime has expired". 701 * Implementations may use other representations for Transport 702 Property Names, e.g., by providing constants, but should provide a 703 straight-forward mapping between their representation and the 704 property names specified here. 706 6. Pre-Establishment Phase 708 The Pre-Establishment phase allows applications to specify properties 709 for the Connections that they are about to make, or to query the API 710 about potential Connections they could make. 712 A Preconnection Object represents a potential Connection. It is a 713 passive Object (a data structure) that merely maintains the state 714 that describes the properties of a Connection that might exist in the 715 future. This state comprises Local Endpoint and Remote Endpoint 716 Objects that denote the endpoints of the potential Connection (see 717 Section 6.1), the Selection Properties (see Section 6.2), any 718 preconfigured Connection Properties (Section 8.1), and the security 719 parameters (see Section 6.3): 721 Preconnection := NewPreconnection([]LocalEndpoint, 722 []RemoteEndpoint, 723 TransportProperties, 724 SecurityParameters) 726 At least one Local Endpoint MUST be specified if the Preconnection is 727 used to Listen() for incoming Connections, but the list of Local 728 Endpoints MAY be empty if the Preconnection is used to Initiate() 729 connections. If no Local Endpoint is specified, the Transport 730 Services system will assign an ephemeral local port to the Connection 731 on the appropriate interface(s). At least one Remote Endpoint MUST 732 be specified if the Preconnection is used to Initiate() Connections, 733 but the list of Remote Endpoints MAY be empty if the Preconnection is 734 used to Listen() for incoming Connections. At least one Local 735 Endpoint and one Remote Endpoint MUST be specified if a peer-to-peer 736 Rendezvous() is to occur based on the Preconnection. 738 If more than one Local Endpoint is specified on a Preconnection, then 739 all the Local Endpoints on the Preconnection MUST represent the same 740 host. For example, they might correspond to different interfaces on 741 a multi-homed host, of they might correspond to local interfaces and 742 a STUN server that can be resolved to a server reflexive address for 743 a Preconnection used to make a peer-to-peer Rendezvous(). 745 If more than one Remote Endpoint is specified on the Preconnection, 746 then all the Remote Endpoints on the Preconnection SHOULD represent 747 the same service. For example, the Remote Endpoints might represent 748 various network interfaces of a host, or a server reflexive address 749 that can be used to reach a host, or a set of hosts that provide 750 equivalent local balanced service. 752 In most cases, it is expected that a single Remote Endpoint will be 753 specified by name, and a later call to Initiate() on the 754 Preconnection (see Section 7.1) will internally resolve that name to 755 a list of concrete endpoints. Specifying multiple Remote Endpoints 756 on a Preconnection allows applications to override this for more 757 detailed control. 759 If Message Framers are used (see Section 9.1.2), they MUST be added 760 to the Preconnection during pre-establishment. 762 6.1. Specifying Endpoints 764 The transport services API uses the Local Endpoint and Remote 765 Endpoint Objects to refer to the endpoints of a transport connection. 766 Endpoints can be created as either Remote or Local: 768 RemoteSpecifier := NewRemoteEndpoint() 769 LocalSpecifier := NewLocalEndpoint() 770 A single Endpoint Object represents the identity of a network host. 771 That endpoint can be more or less specific depending on which 772 identifiers are set. For example, an Endpoint that only specifies a 773 hostname may in fact end up corresponding to several different IP 774 addresses on different hosts. 776 An Endpoint Object can be configured with the following identifiers: 778 * Hostname (string): 780 RemoteSpecifier.WithHostname("example.com") 782 * Port (a 16-bit integer): 784 RemoteSpecifier.WithPort(443) 786 * Service (an identifier that maps to a port; either a the name of a 787 well-known service, or a DNS SRV service name to be resolved): 789 RemoteSpecifier.WithService("https") 791 * IP address (IPv4 or IPv6 address): 793 RemoteSpecifier.WithIPv4Address(192.0.2.21) 795 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 797 * Interface name (string), e.g., to qualify link-local or multicast 798 addresses (see Section 6.1.2 for details): 800 LocalSpecifier.WithInterface("en0") 802 Note that an IPv6 address specified with a scope (e.g. 803 2001:db8:4920:e29d:a420:7461:7073:0a%en0) is equivalent to 804 WithIPv6Address with an unscoped address and WithInterface together. 806 An Endpoint cannot have multiple identifiers of a same type set. 807 That is, an endpoint cannot have two IP addresses specified. Two 808 separate IP addresses are represented as two Endpoint Objects. If a 809 Preconnection specifies a Remote Endpoint with a specific IP address 810 set, it will only establish Connections to that IP address. If, on 811 the other hand, the Remote Endpoint specifies a hostname but no 812 addresses, the Connection can perform name resolution and attempt 813 using any address derived from the original hostname of the Remote 814 Endpoint. Note that multiple Remote Endpoints can be added to a 815 Preconnection, as discussed in Section 7.5. 817 The Transport Services system resolves names internally, when the 818 Initiate(), Listen(), or Rendezvous() method is called to establish a 819 Connection. Privacy considerations for the timing of this resolution 820 are given in Section 13. 822 The Resolve() action on a Preconnection can be used by the 823 application to force early binding when required, for example with 824 some Network Address Translator (NAT) traversal protocols (see 825 Section 7.3). 827 6.1.1. Using Multicast Endpoints 829 Specifying a multicast group address on a Local Endpoint will 830 indicate to the Transport Services system that the resulting 831 connection will be used to receive multicast messages. The Remote 832 Endpoint can be used to filter incoming multicast from specific 833 senders. Such a Preconnection will only support calling Listen(), 834 not Initiate(). Calling Listen() will cause the Transport Services 835 system to register for receiving multicast, such as issuing an IGMP 836 join [RFC3376] or using MLD for IPV6 [RFC4604]. Any Connections that 837 are accepted from this Listener are receive-only. 839 Similarly, specifying a multicast group address on the Remote 840 Endpoint will indicate that the resulting connection will be used to 841 send multicast messages, and that the Preconnection will support 842 Initiate() but not Listen(). Any Connections created this way are 843 send-only. 845 A Rendezvous() call on Preconnections containing group addresses 846 results in an EstablishmentError as described in Section 7.3. 848 See Section 6.1.5 for more examples. 850 6.1.2. Constraining Interfaces for Endpoints 852 Note that this API has multiple ways to constrain and prioritize 853 endpoint candidates based on the network interface: 855 * Specifying an interface on a RemoteEndpoint qualifies the scope of 856 the remote endpoint, e.g., for link-local addresses. 858 * Specifying an interface on a LocalEndpoint explicitly binds all 859 candidates derived from this endpoint to use the specified 860 interface. 862 * Specifying an interface using the interface Selection Property 863 (Section 6.2.11) or indirectly via the pvd Selection Property 864 (Section 6.2.12) influences the selection among the available 865 candidates. 867 While specifying an interface on an endpoint restricts the candidates 868 available for connection establishment in the Pre-Establishment 869 Phase, the Selection Properties prioritize and constrain the 870 connection establishment. 872 6.1.3. Endpoint Aliases 874 An Endpoint can have an alternative definition when using different 875 protocols. For example, a server that supports both TLS/TCP and QUIC 876 may be accessible on two different port numbers depending on which 877 protocol is used. 879 To support this, Endpoint Objects can specify "aliases". An Endpoint 880 can have multiple aliases set. 882 RemoteSpecifier.AddAlias(AlternateRemoteSpecifier) 884 In order to scope an alias to a specific transport protocol, an 885 Endpoint can specify a protocol identifier. 887 RemoteSpecifier.WithProtocol(QUIC) 889 The following example shows a case where "example.com" has a server 890 running on port 443, with an alternate port of 8443 for QUIC. 892 RemoteSpecifier := NewRemoteEndpoint() 893 RemoteSpecifier.WithHostname("example.com") 894 RemoteSpecifier.WithPort(443) 896 QUICRemoteSpecifier := NewRemoteEndpoint() 897 QUICRemoteSpecifier.WithHostname("example.com") 898 QUICRemoteSpecifier.WithPort(8443) 899 QUICRemoteSpecifier.WithProtocol(QUIC) 901 RemoteSpecifier.AddAlias(QUICRemoteSpecifier) 903 6.1.4. Endpoint Examples 905 The following examples of Endpoints show common usage patterns. 907 Specify a Remote Endpoint using a hostname and service name: 909 RemoteSpecifier := NewRemoteEndpoint() 910 RemoteSpecifier.WithHostname("example.com") 911 RemoteSpecifier.WithService("https") 913 Specify a Remote Endpoint using an IPv6 address and remote port: 915 RemoteSpecifier := NewRemoteEndpoint() 916 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 917 RemoteSpecifier.WithPort(443) 919 Specify a Remote Endpoint using an IPv4 address and remote port: 921 RemoteSpecifier := NewRemoteEndpoint() 922 RemoteSpecifier.WithIPv4Address(192.0.2.21) 923 RemoteSpecifier.WithPort(443) 925 Specify a Local Endpoint using a local interface name and local port: 927 LocalSpecifier := NewLocalEndpoint() 928 LocalSpecifier.WithInterface("en0") 929 LocalSpecifier.WithPort(443) 931 As an alternative to specifying an interface name for the Local 932 Endpoint, an application can express more fine-grained preferences 933 using the Interface Instance or Type Selection Property, see 934 Section 6.2.11. However, if the application specifies Selection 935 Properties that are inconsistent with the Local Endpoint, this will 936 result in an Error once the application attempts to open a 937 Connection. 939 Specify a Local Endpoint using a STUN server: 941 LocalSpecifier := NewLocalEndpoint() 942 LocalSpecifier.WithStunServer(address, port, credentials) 944 6.1.5. Multicast Examples 946 Specify a Local Endpoint using an Any-Source Multicast group to join 947 on a named local interface: 949 LocalSpecifier := NewLocalEndpoint() 950 LocalSpecifier.WithIPv4Address(233.252.0.0) 951 LocalSpecifier.WithInterface("en0") 953 Source-Specific Multicast requires setting both a Local and Remote 954 Endpoint: 956 LocalSpecifier := NewLocalEndpoint() 957 LocalSpecifier.WithIPv4Address(232.1.1.1) 958 LocalSpecifier.WithInterface("en0") 960 RemoteSpecifier := NewRemoteEndpoint() 961 RemoteSpecifier.WithIPv4Address(192.0.2.22) 963 One common pattern for multicast is to both send and receive 964 multicast. For such cases, an application can set up both a Listener 965 and a Connection. The Listener is only used to accept Connections 966 that receive inbound multicast. The initiated Connection is only 967 used to send multicast. 969 // Prepare multicast Listener 970 LocalMulticastSpecifier := NewLocalEndpoint() 971 LocalMulticastSpecifier.WithIPv4Address(233.252.0.0) 972 LocalMulticastSpecifier.WithPort(5353) 973 LocalMulticastSpecifier.WithInterface("en0") 975 TransportProperties := NewTransportProperties() 976 TransportProperties.Require(preserve-msg-boundaries) 977 // Reliable Data Transfer and Preserve Order are Required by default 979 // Specifying a Remote Endpoint is optional when using Listen() 980 Preconnection := NewPreconnection(LocalMulticastSpecifier, 981 TransportProperties, 982 SecurityParameters) 984 MulticastListener := Preconnection.Listen() 986 // Handle inbound messages sent to the multicast group 987 MulticastListener -> ConnectionReceived 988 MulticastReceiverConnection.Receive() 989 MulticastReceiverConnection -> Received 991 // Prepare Connection to send multicast 992 LocalSpecifier := NewLocalEndpoint() 993 LocalSpecifier.WithPort(5353) 994 LocalSpecifier.WithInterface("en0") 995 RemoteMulticastSpecifier := NewRemoteEndpoint() 996 RemoteMulticastSpecifier.WithIPv4Address(233.252.0.0) 997 RemoteMulticastSpecifier.WithPort(5353) 998 RemoteMulticastSpecifier.WithInterface("en0") 1000 Preconnection2 := NewPreconnection(LocalSpecifier, 1001 RemoteMulticastSpecifier, 1002 TransportProperties, 1003 SecurityParameters) 1005 // Send outbound messages to the multicast group 1006 MulticastSenderConnection := Preconnection.Initiate() 1007 MulticastSenderConnection.Send(messageData) 1009 6.2. Specifying Transport Properties 1011 A Preconnection Object holds properties reflecting the application's 1012 requirements and preferences for the transport. These include 1013 Selection Properties for selecting protocol stacks and paths, as well 1014 as Connection Properties and Message Properties for configuration of 1015 the detailed operation of the selected Protocol Stacks on a per- 1016 Connection and Message level. 1018 The protocol(s) and path(s) selected as candidates during 1019 establishment are determined and configured using these properties. 1020 Since there could be paths over which some transport protocols are 1021 unable to operate, or remote endpoints that support only specific 1022 network addresses or transports, transport protocol selection is 1023 necessarily tied to path selection. This may involve choosing 1024 between multiple local interfaces that are connected to different 1025 access networks. 1027 When additional information (such as Provisioning Domain (PvD) 1028 information Path information can include network segment PMTU, set of 1029 supported DSCPs, expected usage, cost, etc. The usage of this 1030 information by the Transport Services System is generally independent 1031 of the specific mechanism/protocol used to receive the information 1032 (e.g. zero-conf, DHCP, or IPv6 RA).[RFC7556]) is available about the 1033 networks over which an endpoint can operate, this can inform the 1034 selection between alternate network paths. 1036 Most Selection Properties are represented as Preferences, which can 1037 take one of five values: 1039 +============+========================================+ 1040 | Preference | Effect | 1041 +============+========================================+ 1042 | Require | Select only protocols/paths providing | 1043 | | the property, fail otherwise | 1044 +------------+----------------------------------------+ 1045 | Prefer | Prefer protocols/paths providing the | 1046 | | property, proceed otherwise | 1047 +------------+----------------------------------------+ 1048 | Ignore | No preference | 1049 +------------+----------------------------------------+ 1050 | Avoid | Prefer protocols/paths not providing | 1051 | | the property, proceed otherwise | 1052 +------------+----------------------------------------+ 1053 | Prohibit | Select only protocols/paths not | 1054 | | providing the property, fail otherwise | 1055 +------------+----------------------------------------+ 1057 Table 1: Selection Property Preference Levels 1059 The implementation MUST ensure an outcome that is consistent with all 1060 application requirements expressed using Require and Prohibit. While 1061 preferences expressed using Prefer and Avoid influence protocol and 1062 path selection as well, outcomes can vary given the same Selection 1063 Properties, because the available protocols and paths can differ 1064 across systems and contexts. However, implementations are 1065 RECOMMENDED to seek to provide a consistent outcome to an 1066 application, given the same set of Selection Properties. 1068 Note that application preferences can conflict with each other. For 1069 example, if an application indicates a preference for a specific path 1070 by specifying an interface, but also a preference for a protocol, a 1071 situation might occur in which the preferred protocol is not 1072 available on the preferred path. In such cases, applications can 1073 expect properties that determine path selection to be prioritized 1074 over properties that determine protocol selection. The transport 1075 system SHOULD determine the preferred path first, regardless of 1076 protocol preferences. This ordering is chosen to provide consistency 1077 across implementations, based on the fact that it is more common for 1078 the use of a given network path to determine cost to the user (i.e., 1079 an interface type preference might be based on a user's preference to 1080 avoid being charged more for a cellular data plan). 1082 Selection and Connection Properties, as well as defaults for Message 1083 Properties, can be added to a Preconnection to configure the 1084 selection process and to further configure the eventually selected 1085 protocol stack(s). They are collected into a TransportProperties 1086 object to be passed into a Preconnection object: 1088 TransportProperties := NewTransportProperties() 1090 Individual properties are then set on the TransportProperties Object. 1091 Setting a Transport Property to a value overrides the previous value 1092 of this Transport Property. 1094 TransportProperties.Set(property, value) 1096 To aid readability, implementations MAY provide additional 1097 convenience functions to simplify use of Selection Properties: see 1098 Appendix B.1 for examples. In addition, implementations MAY provide 1099 a mechanism to create TransportProperties objects that are 1100 preconfigured for common use cases as outlined in Appendix B.2. 1102 Transport Properties for an established connection can be queried via 1103 the Connection object, as outlined in Section 8. 1105 A Connection gets its Transport Properties either by being explicitly 1106 configured via a Preconnection, by configuration after establishment, 1107 or by inheriting them from an antecedent via cloning; see Section 7.4 1108 for more. 1110 Section 8.1 provides a list of Connection Properties, while Selection 1111 Properties are listed in the subsections below. Many properties are 1112 only considered during establishment, and can not be changed after a 1113 Connection is established; however, they can still be queried. The 1114 return type of a queried Selection Property is Boolean, where true 1115 means that the Selection Property has been applied and false means 1116 that the Selection Property has not been applied. Note that true 1117 does not mean that a request has been honored. For example, if 1118 Congestion control was requested with preference level Prefer, but 1119 congestion control could not be supported, querying the 1120 congestionControl property yields the value false. If the preference 1121 level Avoid was used for Congestion control, and, as requested, the 1122 Connection is not congestion controlled, querying the 1123 congestionControl property also yields the value false. 1125 An implementation of the Transport Services API must provide sensible 1126 defaults for Selection Properties. The default values for each 1127 property below represent a configuration that can be implemented over 1128 TCP. If these default values are used and TCP is not supported by a 1129 Transport Services system, then an application using the default set 1130 of Properties might not succeed in establishing a connection. Using 1131 the same default values for independent Transport Services 1132 implementations can be beneficial when applications are ported 1133 between different implementations/platforms, even if this default 1134 could lead to a connection failure when TCP is not available. If 1135 default values other than those suggested below are used, it is 1136 RECOMMENDED to clearly document any differences. 1138 6.2.1. Reliable Data Transfer (Connection) 1140 Name: reliability 1142 Type: Preference 1144 Default: Require 1146 This property specifies whether the application needs to use a 1147 transport protocol that ensures that all data is received at the 1148 Remote Endpoint without corruption. When reliable data transfer is 1149 enabled, this also entails being notified when a Connection is closed 1150 or aborted. 1152 6.2.2. Preservation of Message Boundaries 1154 Name: preserveMsgBoundaries 1156 Type: Preference 1158 Default: Ignore 1160 This property specifies whether the application needs or prefers to 1161 use a transport protocol that preserves message boundaries. 1163 6.2.3. Configure Per-Message Reliability 1165 Name: perMsgReliability 1167 Type: Preference 1169 Default: Ignore 1171 This property specifies whether an application considers it useful to 1172 specify different reliability requirements for individual Messages in 1173 a Connection. 1175 6.2.4. Preservation of Data Ordering 1177 Name: preserveOrder 1179 Type: Preference 1181 Default: Require 1183 This property specifies whether the application wishes to use a 1184 transport protocol that can ensure that data is received by the 1185 application on the other end in the same order as it was sent. 1187 6.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message 1189 Name: zeroRttMsg 1191 Type: Preference 1193 Default: Ignore 1194 This property specifies whether an application would like to supply a 1195 Message to the transport protocol before Connection establishment 1196 that will then be reliably transferred to the other side before or 1197 during Connection establishment. This Message can potentially be 1198 received multiple times (i.e., multiple copies of the message data 1199 may be passed to the Remote Endpoint). See also Section 9.1.3.4. 1201 6.2.6. Multistream Connections in Group 1203 Name: multistreaming 1205 Type: Preference 1207 Default: Prefer 1209 This property specifies that the application would prefer multiple 1210 Connections within a Connection Group to be provided by streams of a 1211 single underlying transport connection where possible. 1213 6.2.7. Full Checksum Coverage on Sending 1215 Name: fullChecksumSend 1217 Type: Preference 1219 Default: Require 1221 This property specifies the application's need for protection against 1222 corruption for all data transmitted on this Connection. Disabling 1223 this property could enable later control of the sender checksum 1224 coverage (see Section 9.1.3.6). 1226 6.2.8. Full Checksum Coverage on Receiving 1228 Name: fullChecksumRecv 1230 Type: Preference 1232 Default: Require 1234 This property specifies the application's need for protection against 1235 corruption for all data received on this Connection. Disabling this 1236 property could enable later control of the required minimum receiver 1237 checksum coverage (see Section 8.1.1). 1239 6.2.9. Congestion control 1241 Name: congestionControl 1243 Type: Preference 1245 Default: Require 1247 This property specifies whether the application would like the 1248 Connection to be congestion controlled or not. Note that if a 1249 Connection is not congestion controlled, an application using such a 1250 Connection SHOULD itself perform congestion control in accordance 1251 with [RFC2914] or use a circuit breaker in accordance with [RFC8084], 1252 whichever is appropriate. Also note that reliability is usually 1253 combined with congestion control in protocol implementations, 1254 rendering "reliable but not congestion controlled" a request that is 1255 unlikely to succeed. If the Connection is congestion controlled, 1256 performing additional congestion control in the application can have 1257 negative performance implications. 1259 6.2.10. Keep alive 1261 Name: keepAlive 1263 Type: Preference 1265 Default: Ignore 1267 This property specifies whether the application would like the 1268 Connection to send keep-alive packets or not. Note that if a 1269 Connection determines that keep-alive packets are being sent, the 1270 applicaton should itself avoid generating additional keep alive 1271 messages. Note that when supported, the system will use the default 1272 period for generation of the keep alive-packets. (See also 1273 Section 8.1.4). 1275 6.2.11. Interface Instance or Type 1277 Name: interface 1279 Type: Collection of (Preference, Enumeration) 1281 Default: Empty (not setting a preference for any interface) 1282 This property allows the application to select any specific network 1283 interfaces or categories of interfaces it wants to Require, Prohibit, 1284 Prefer, or Avoid. Note that marking a specific interface as Require 1285 strictly limits path selection to that single interface, and often 1286 leads to less flexible and resilient connection establishment. 1288 In contrast to other Selection Properties, this property is a tuple 1289 of an (Enumerated) interface identifier and a preference, and can 1290 either be implemented directly as such, or for making one preference 1291 available for each interface and interface type available on the 1292 system. 1294 The set of valid interface types is implementation- and system- 1295 specific. For example, on a mobile device, there may be Wi-Fi and 1296 Cellular interface types available; whereas on a desktop computer, 1297 Wi-Fi and Wired Ethernet interface types might be available. An 1298 implementation should provide all types that are supported on the 1299 local system, to allow applications to be written generically. For 1300 example, if a single implementation is used on both mobile devices 1301 and desktop devices, it should define the Cellular interface type for 1302 both systems, since an application might wish to always prohibit 1303 cellular. 1305 The set of interface types is expected to change over time as new 1306 access technologies become available. The taxonomy of interface 1307 types on a given Transport Services system is implementation- 1308 specific. 1310 Interface types should not be treated as a proxy for properties of 1311 interfaces such as metered or unmetered network access. If an 1312 application needs to prohibit metered interfaces, this should be 1313 specified via Provisioning Domain attributes (see Section 6.2.12) or 1314 another specific property. 1316 Note that this property is not used to specify an interface scope for 1317 a particular endpoint. Section 6.1.2 provides details about how to 1318 qualify endpoint candidates on a per-interface basis. 1320 6.2.12. Provisioning Domain Instance or Type 1322 Name: pvd 1324 Type: Collection of (Preference, Enumeration) 1326 Default: Empty (not setting a preference for any PvD) 1327 Similar to interface instances and types (see Section 6.2.11), this 1328 property allows the application to control path selection by 1329 selecting which specific Provisioning Domain (PvD) or categories of 1330 PVDs it wants to Require, Prohibit, Prefer, or Avoid. Provisioning 1331 Domains define consistent sets of network properties that may be more 1332 specific than network interfaces [RFC7556]. 1334 As with interface instances and types, this property is a tuple of an 1335 (Enumerated) PvD identifier and a preference, and can either be 1336 implemented directly as such, or for making one preference available 1337 for each interface and interface type available on the system. 1339 The identification of a specific PvD is implementation- and system- 1340 specific, because there is currently no portable standard format for 1341 a PvD identifier. For example, this identifier might be a string 1342 name or an integer. As with requiring specific interfaces, requiring 1343 a specific PvD strictly limits the path selection. 1345 Categories or types of PvDs are also defined to be implementation- 1346 and system-specific. These can be useful to identify a service that 1347 is provided by a PvD. For example, if an application wants to use a 1348 PvD that provides a Voice-Over-IP service on a Cellular network, it 1349 can use the relevant PvD type to require a PvD that provides this 1350 service, without needing to look up a particular instance. While 1351 this does restrict path selection, it is broader than requiring 1352 specific PvD instances or interface instances, and should be 1353 preferred over these options. 1355 6.2.13. Use Temporary Local Address 1357 Name: useTemporaryLocalAddress 1359 Type: Preference 1361 Default: Avoid for Listeners and Rendezvous Connections. Prefer for 1362 other Connections. 1364 This property allows the application to express a preference for the 1365 use of temporary local addresses, sometimes called "privacy" 1366 addresses [RFC8981]. Temporary addresses are generally used to 1367 prevent linking connections over time when a stable address, 1368 sometimes called "permanent" address, is not needed. There are some 1369 caveats to note when specifying this property. First, if an 1370 application Requires the use of temporary addresses, the resulting 1371 Connection cannot use IPv4, because temporary addresses do not exist 1372 in IPv4. Second, temporary local addresses might involve trading off 1373 privacy for performance. For instance, temporary addresses can 1374 interfere with resumption mechanisms that some protocols rely on to 1375 reduce initial latency. 1377 6.2.14. Multipath Transport 1379 Name: multipath 1381 Type: Enumeration 1383 Default: Disabled for connections created through initiate and 1384 rendezvous, Passive for listeners 1386 This property specifies whether and how applications want to take 1387 advantage of transferring data across multiple paths between the same 1388 end hosts. Using multiple paths allows connections to migrate 1389 between interfaces or aggregate bandwidth as availability and 1390 performance properties change. Possible values are: 1392 Disabled: The connection will not use multiple paths once 1393 established, even if the chosen transport supports using multiple 1394 paths. 1396 Active: The connection will negotiate the use of multiple paths if 1397 the chosen transport supports this. 1399 Passive: The connection will support the use of multiple paths if 1400 the Remote Endpoint requests it. 1402 The policy for using multiple paths is specified using the separate 1403 multipath-policy property, see Section 8.1.7 below. To enable the 1404 peer endpoint to initiate additional paths towards a local address 1405 other than the one initially used, it is necessary to set the 1406 Alternative Addresses property (see Section 6.2.15 below). 1408 Setting this property to "Active", can have privacy implications: It 1409 enables the transport to establish connectivity using alternate paths 1410 that might result in users being linkable across the multiple paths, 1411 even if the Advertisement of Alternative Addresses property (see 1412 Section 6.2.15 below) is set to false. 1414 Note that Multipath Transport has no corresponding Selection Property 1415 of type Preference. Enumeration values other than "Disabled" are 1416 interpreted as a preference for choosing protocols that can make use 1417 of multiple paths. The "Disabled" value implies a requirement not to 1418 use multiple paths in parallel but does not prevent choosing a 1419 protocol that is capable of using multiple paths, e.g., it does not 1420 prevent choosing TCP, but prevents sending the MP_CAPABLE option in 1421 the TCP handshake. 1423 6.2.15. Advertisement of Alternative Addresses 1425 Name: advertises-altaddr 1427 Type: Boolean 1429 Default: False 1431 This property specifies whether alternative addresses, e.g., of other 1432 interfaces, should be advertised to the peer endpoint by the protocol 1433 stack. Advertising these addresses enables the peer-endpoint to 1434 establish additional connectivity, e.g., for connection migration or 1435 using multiple paths. 1437 Note that this can have privacy implications because it might result 1438 in users being linkable across the multiple paths. Also, note that 1439 setting this to false does not prevent the local Transport Services 1440 system from _establishing_ connectivity using alternate paths (see 1441 Section 6.2.14 above); it only prevents _proactive advertisement_ of 1442 addresses. 1444 6.2.16. Direction of communication 1446 Name: direction 1448 Type: Enumeration 1450 Default: Bidirectional 1452 This property specifies whether an application wants to use the 1453 connection for sending and/or receiving data. Possible values are: 1455 Bidirectional: The connection must support sending and receiving 1456 data 1458 Unidirectional send: The connection must support sending data, and 1459 the application cannot use the connection to receive any data 1461 Unidirectional receive: The connection must support receiving data, 1462 and the application cannot use the connection to send any data 1464 Since unidirectional communication can be supported by transports 1465 offering bidirectional communication, specifying unidirectional 1466 communication may cause a transport stack that supports bidirectional 1467 communication to be selected. 1469 6.2.17. Notification of ICMP soft error message arrival 1471 Name: softErrorNotify 1473 Type: Preference 1475 Default: Ignore 1477 This property specifies whether an application considers it useful to 1478 be informed when an ICMP error message arrives that does not force 1479 termination of a connection. When set to true, received ICMP errors 1480 are available as SoftErrors, see Section 8.3.1. Note that even if a 1481 protocol supporting this property is selected, not all ICMP errors 1482 will necessarily be delivered, so applications cannot rely upon 1483 receiving them [RFC8085]. 1485 6.2.18. Initiating side is not the first to write 1487 Name: activeReadBeforeSend 1489 Type: Preference 1491 Default: Ignore 1492 The most common client-server communication pattern involves the 1493 client actively opening a connection, then sending data to the 1494 server. The server listens (passive open), reads, and then answers. 1495 This property specifies whether an application wants to diverge from 1496 this pattern - either by actively opening with Initiate(), 1497 immediately followed by reading, or passively opening with Listen(), 1498 immediately followed by writing. This property is ignored when 1499 establishing connections using Rendezvous(). Requiring this property 1500 limits the choice of mappings to underlying protocols, which can 1501 reduce efficiency. For example, it prevents the Transport Services 1502 system from mapping Connections to SCTP streams, where the first 1503 transmitted data takes the role of an active open signal 1504 [I-D.ietf-taps-impl]. 1506 6.3. Specifying Security Parameters and Callbacks 1508 Most security parameters, e.g., TLS ciphersuites, local identity and 1509 private key, etc., may be configured statically. Others are 1510 dynamically configured during connection establishment. Security 1511 parameters and callbacks are partitioned based on their place in the 1512 lifetime of connection establishment. Similar to Transport 1513 Properties, both parameters and callbacks are inherited during 1514 cloning (see Section 7.4). 1516 6.3.1. Specifying Security Parameters on a Pre-Connection 1518 Common security parameters such as TLS ciphersuites are known to 1519 implementations. Clients should use common safe defaults for these 1520 values whenever possible. However, as discussed in [RFC8922], many 1521 transport security protocols require specific security parameters and 1522 constraints from the client at the time of configuration and actively 1523 during a handshake. These configuration parameters need to be 1524 specified in the pre-connection phase and are created as follows: 1526 SecurityParameters := NewSecurityParameters() 1528 Security configuration parameters and sample usage follow: 1530 * Local identity and private keys: Used to perform private key 1531 operations and prove one's identity to the Remote Endpoint. 1532 (Note, if private keys are not available, e.g., since they are 1533 stored in hardware security modules (HSMs), handshake callbacks 1534 must be used. See below for details.) 1536 SecurityParameters.Set(identity, myIdentity) 1537 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 1538 * Supported algorithms: Used to restrict what parameters are used by 1539 underlying transport security protocols. When not specified, 1540 these algorithms should use known and safe defaults for the 1541 system. Parameters include: ciphersuites, supported groups, and 1542 signature algorithms. These parameters take a collection of 1543 supported algorithms as parameter. 1545 SecurityParameters.Set(supported-group, "secp256r1") 1546 SecurityParameters.Set(ciphersuite, "TLS_AES_128_GCM_SHA256") 1547 SecurityParameters.Set(signature-algorithm, "ecdsa_secp256r1_sha256") 1549 * Pre-Shared Key import: Used to install pre-shared keying material 1550 established out-of-band. Each pre-shared keying material is 1551 associated with some identity that typically identifies its use or 1552 has some protocol-specific meaning to the Remote Endpoint. 1554 SecurityParameters.Set(pre-shared-key, key, identity) 1556 * Session cache management: Used to tune session cache capacity, 1557 lifetime, and other policies. 1559 SecurityParameters.Set(max-cached-sessions, 16) 1560 SecurityParameters.Set(cached-session-lifetime-seconds, 3600) 1562 Connections that use Transport Services SHOULD use security in 1563 general. However, for compatibility with endpoints that do not 1564 support transport security protocols (such as a TCP endpoint that 1565 does not support TLS), applications can initialize their security 1566 parameters to indicate that security can be disabled, or can be 1567 opportunistic. If security is disabled, the Transport Services 1568 system will not attempt to add transport security automatically. If 1569 security is opportunistic, it will allow Connections without 1570 transport security, but will still attempt to use security if 1571 available. 1573 SecurityParameters := NewDisabledSecurityParameters() 1575 SecurityParameters := NewOpportunisticSecurityParameters() 1577 Representation of Security Parameters in implementations should 1578 parallel that chosen for Transport Property names as sugggested in 1579 Section 5. 1581 6.3.2. Connection Establishment Callbacks 1583 Security decisions, especially pertaining to trust, are not static. 1584 Once configured, parameters may also be supplied during connection 1585 establishment. These are best handled as client-provided callbacks. 1586 Callbacks block the progress of the connection establishment, which 1587 distinguishes them from other Events in the transport system. How 1588 callbacks and events are implemented is specific to each 1589 implementation. Security handshake callbacks that may be invoked 1590 during connection establishment include: 1592 * Trust verification callback: Invoked when a Remote Endpoint's 1593 trust must be verified before the handshake protocol can continue. 1594 For example, the application could verify an X.509 certificate as 1595 described in [RFC5280]. 1597 TrustCallback := NewCallback({ 1598 // Handle trust, return the result 1599 }) 1600 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1602 * Identity challenge callback: Invoked when a private key operation 1603 is required, e.g., when local authentication is requested by a 1604 Remote Endpoint. 1606 ChallengeCallback := NewCallback({ 1607 // Handle challenge 1608 }) 1609 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1611 7. Establishing Connections 1613 Before a Connection can be used for data transfer, it needs to be 1614 established. Establishment ends the pre-establishment phase; all 1615 transport properties and cryptographic parameter specification must 1616 be complete before establishment, as these will be used to select 1617 candidate Paths and Protocol Stacks for the Connection. 1618 Establishment may be active, using the Initiate() Action; passive, 1619 using the Listen() Action; or simultaneous for peer-to-peer, using 1620 the Rendezvous() Action. These Actions are described in the 1621 subsections below. 1623 7.1. Active Open: Initiate 1625 Active open is the Action of establishing a Connection to a Remote 1626 Endpoint presumed to be listening for incoming Connection requests. 1627 Active open is used by clients in client-server interactions. Active 1628 open is supported by the Transport Services API through the Initiate 1629 Action: 1631 Connection := Preconnection.Initiate(timeout?) 1633 The timeout parameter specifies how long to wait before aborting 1634 Active open. Before calling Initiate, the caller must have populated 1635 a Preconnection Object with a Remote Endpoint specifier, optionally a 1636 Local Endpoint specifier (if not specified, the system will attempt 1637 to determine a suitable Local Endpoint), as well as all properties 1638 necessary for candidate selection. 1640 The Initiate() Action returns a Connection object. Once Initiate() 1641 has been called, any changes to the Preconnection MUST NOT have any 1642 effect on the Connection. However, the Preconnection can be reused, 1643 e.g., to Initiate another Connection. 1645 Once Initiate is called, the candidate Protocol Stack(s) may cause 1646 one or more candidate transport-layer connections to be created to 1647 the specified Remote Endpoint. The caller may immediately begin 1648 sending Messages on the Connection (see Section 9.2) after calling 1649 Initiate(); note that any data marked Safely Replayable that is sent 1650 while the Connection is being established may be sent multiple times 1651 or on multiple candidates. 1653 The following Events may be sent by the Connection after Initiate() 1654 is called: 1656 Connection -> Ready<> 1658 The Ready Event occurs after Initiate has established a transport- 1659 layer connection on at least one usable candidate Protocol Stack over 1660 at least one candidate Path. No Receive Events (see Section 9.3) 1661 will occur before the Ready Event for Connections established using 1662 Initiate. 1664 Connection -> EstablishmentError 1666 An EstablishmentError occurs either when the set of transport 1667 properties and security parameters cannot be fulfilled on a 1668 Connection for initiation (e.g., the set of available Paths and/or 1669 Protocol Stacks meeting the constraints is empty) or reconciled with 1670 the Local and/or Remote Endpoints; when the remote specifier cannot 1671 be resolved; or when no transport-layer connection can be established 1672 to the Remote Endpoint (e.g., because the Remote Endpoint is not 1673 accepting connections, the application is prohibited from opening a 1674 Connection by the operating system, or the establishment attempt has 1675 timed out for any other reason). 1677 Connection establishment and transmission of the first message can be 1678 combined in a single action Section 9.2.5. 1680 7.2. Passive Open: Listen 1682 Passive open is the Action of waiting for Connections from Remote 1683 Endpoints, commonly used by servers in client-server interactions. 1684 Passive open is supported by the Transport Services API through the 1685 Listen Action and returns a Listener object: 1687 Listener := Preconnection.Listen() 1689 Before calling Listen, the caller must have initialized the 1690 Preconnection during the pre-establishment phase with a Local 1691 Endpoint specifier, as well as all properties necessary for Protocol 1692 Stack selection. A Remote Endpoint may optionally be specified, to 1693 constrain what Connections are accepted. 1695 The Listen() Action returns a Listener object. Once Listen() has 1696 been called, any changes to the Preconnection MUST NOT have any 1697 effect on the Listener. The Preconnection can be disposed of or 1698 reused, e.g., to create another Listener. 1700 Listener.Stop() 1702 Listening continues until the global context shuts down, or until the 1703 Stop action is performed on the Listener object. 1705 Listener -> ConnectionReceived 1707 The ConnectionReceived Event occurs when a Remote Endpoint has 1708 established a transport-layer connection to this Listener (for 1709 Connection-oriented transport protocols), or when the first Message 1710 has been received from the Remote Endpoint (for Connectionless 1711 protocols), causing a new Connection to be created. The resulting 1712 Connection is contained within the ConnectionReceived Event, and is 1713 ready to use as soon as it is passed to the application via the 1714 event. 1716 Listener.SetNewConnectionLimit(value) 1717 If the caller wants to rate-limit the number of inbound Connections 1718 that will be delivered, it can set a cap using 1719 SetNewConnectionLimit(). This mechanism allows a server to protect 1720 itself from being drained of resources. Each time a new Connection 1721 is delivered by the ConnectionReceived Event, the value is 1722 automatically decremented. Once the value reaches zero, no further 1723 Connections will be delivered until the caller sets the limit to a 1724 higher value. By default, this value is Infinite. The caller is 1725 also able to reset the value to Infinite at any point. 1727 Listener -> EstablishmentError 1729 An EstablishmentError occurs either when the Properties and Security 1730 Parameters of the Preconnection cannot be fulfilled for listening or 1731 cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, 1732 if specified), when the Local Endpoint (or Remote Endpoint, if 1733 specified) cannot be resolved, or when the application is prohibited 1734 from listening by policy. 1736 Listener -> Stopped<> 1738 A Stopped Event occurs after the Listener has stopped listening. 1740 7.3. Peer-to-Peer Establishment: Rendezvous 1742 Simultaneous peer-to-peer Connection establishment is supported by 1743 the Rendezvous() Action: 1745 Preconnection.Rendezvous() 1747 A Preconnection Object used in a Rendezvous() MUST have both the 1748 Local Endpoint candidates and the Remote Endpoint candidates 1749 specified, along with the transport properties and security 1750 parameters needed for Protocol Stack selection, before the 1751 Rendezvous() Action is initiated. 1753 The Rendezvous() Action listens on the Local Endpoint candidates for 1754 an incoming Connection from the Remote Endpoint candidates, while 1755 also simultaneously trying to establish a Connection from the Local 1756 Endpoint candidates to the Remote Endpoint candidates. 1758 If there are multiple Local Endpoints or Remote Endpoints configured, 1759 then initiating a Rendezvous() action will systematically probe the 1760 reachability of those endpoint candidates following an approach such 1761 as that used in Interactive Connectivity Establishment (ICE) 1762 [RFC8445]. 1764 If the endpoints are suspected to be behind a NAT, Rendezvous() can 1765 be initiated using Local Endpoints that support a method of 1766 discovering NAT bindings such as Session Traversal Utilities for NAT 1767 (STUN) [RFC8489] or Traversal Using Relays around NAT (TURN) 1768 [RFC8656]. In this case, the Local Endpoint will resolve to a 1769 mixture of local and server reflexive addresses. The Resolve() 1770 action on the Preconnection can be used to discover these bindings: 1772 []LocalEndpoint, []RemoteEndpoint := Preconnection.Resolve() 1774 The Resolve() call returns lists of Local Endpoints and Remote 1775 Endpoints, that represent the concrete addresses, local and server 1776 reflexive, on which a Rendezvous() for the Preconnection will listen 1777 for incoming Connections, and to which it will attempt to establish 1778 connections. 1780 Note that the set of LocalEndpoints returned by Resolve() might or 1781 might not contain information about all possible local interfaces; it 1782 is valid only for a Rendezvous happening at the same time as the 1783 resolution. Care should be taken in using these values in any other 1784 context. 1786 An application that uses Rendezvous() to establish a peer-to-peer 1787 connection in the presence of NATs will configure the Preconnection 1788 object with at least one a Local Endpoint that supports NAT binding 1789 discovery. It will then Resolve() the Preconnection, and pass the 1790 resulting list of Local Endpoint candidates to the peer via a 1791 signalling protocol, for example as part of an ICE [RFC5245] exchange 1792 within SIP [RFC3261] or WebRTC [RFC7478]. The peer will then, via 1793 the same signalling channel, return the Remote Endpoint candidates. 1794 The set of Remote Endpoint candidates are then configured onto the 1795 Preconnection: 1797 Preconnection.AddRemote([]RemoteEndpoint) 1799 The Rendezvous() Action can be initiated once both the Local Endpoint 1800 candidates and the Remote Endpoint candidates retrieved from the peer 1801 via the signalling channel have been added to the Preconnection. 1803 If successful, the Rendezvous() Action returns a Connection object 1804 via a RendezvousDone<> Event: 1806 Preconnection -> RendezvousDone 1808 The RendezvousDone<> Event occurs when a Connection is established 1809 with the Remote Endpoint. For Connection-oriented transports, this 1810 occurs when the transport-layer connection is established; for 1811 Connectionless transports, it occurs when the first Message is 1812 received from the Remote Endpoint. The resulting Connection is 1813 contained within the RendezvousDone<> Event, and is ready to use as 1814 soon as it is passed to the application via the Event. Changes made 1815 to a Preconnection after Rendezvous() has been called do not have any 1816 effect on existing Connections. 1818 An EstablishmentError occurs either when the Properties and Security 1819 Parameters of the Preconnection cannot be fulfilled for rendezvous or 1820 cannot be reconciled with the Local and/or Remote Endpoints, when the 1821 Local Endpoint or Remote Endpoint cannot be resolved, when no 1822 transport-layer connection can be established to the Remote Endpoint, 1823 or when the application is prohibited from rendezvous by policy: 1825 Preconnection -> EstablishmentError 1827 7.4. Connection Groups 1829 Connection Groups can be created using the Clone Action: 1831 Connection := Connection.Clone(framer?) 1833 Calling Clone on a Connection yields a Connection Group containing 1834 two Connections: the parent Connection on which Clone was called, and 1835 a resulting cloned Connection. The new Connection is actively 1836 openend, and it will send a Ready Event or an EstablishmentError 1837 Event. Calling Clone on any of these Connections adds another 1838 Connection to the Connection Group. Connections in a Connection 1839 Group share all Connection Properties except Connection Priority (see 1840 Section 8.1.2), and these Connection Properties are entangled: 1841 Changing one of the Connection Properties on one Connection in the 1842 Connection Group automatically changes the Connection Property for 1843 all others. For example, changing Timeout for aborting Connection 1844 (see Section 8.1.3) on one Connection in a Connection Group will 1845 automatically make the same change to this Connection Property for 1846 all other Connections in the Connection Group. Like all other 1847 Properties, Connection Priority is copied to the new Connection when 1848 calling Clone(), but in this case, a later change to the Connection 1849 Priority on one Connection does not change it on the other 1850 Connections in the same Connection Group. 1852 Message Properties set on a Connection also apply only to that 1853 Connection. 1855 A new Connection created by Clone can have a Message Framer assigned 1856 via the optional framer parameter of the Clone Action. If this 1857 parameter is not supplied, the stack of Message Framers associated 1858 with a Connection is copied to the cloned Connection when calling 1859 Clone. Then, a cloned Connection has the same stack of Message 1860 Framers as the Connection from which they are Cloned, but these 1861 Framers may internally maintain per-Connection state. 1863 It is also possible to check which Connections belong to the same 1864 Connection Group. Calling GroupedConnections() on a specific 1865 Connection returns a set of all Connections in the same group. 1867 []Connection := Connection.GroupedConnections() 1869 Connections will belong to the same group if the application 1870 previously called Clone. Passive Connections can also be added to 1871 the same group - e.g., when a Listener receives a new Connection that 1872 is just a new stream of an already active multi-streaming protocol 1873 instance. 1875 If the underlying protocol supports multi-streaming, it is natural to 1876 use this functionality to implement Clone. In that case, Connections 1877 in a Connection Group are multiplexed together, giving them similar 1878 treatment not only inside endpoints, but also across the end-to-end 1879 Internet path. 1881 Note that calling Clone() can result in on-the-wire signaling, e.g., 1882 to open a new transport connection, depending on the underlying 1883 Protocol Stack. When Clone() leads to the opening of multiple such 1884 connections, the Transport Services system will ensure consistency of 1885 Connection Properties by uniformly applying them to all underlying 1886 connections in a group. Even in such a case, there are possibilities 1887 for a Transport Services system to implement prioritization within a 1888 Connection Group [TCP-COUPLING] [RFC8699]. 1890 Attempts to clone a Connection can result in a CloneError: 1892 Connection -> CloneError 1894 The Connection Priority Connection Property operates on Connections 1895 in a Connection Group using the same approach as in Section 9.1.3.2: 1896 when allocating available network capacity among Connections in a 1897 Connection Group, sends on Connections with higher Priority values 1898 will be prioritized over sends on Connections that have lower 1899 Priority values. Capacity will be shared among these Connections 1900 according to the Connection Group Transmission Scheduler property 1901 (Section 8.1.5). See Section 9.2.6 for more. 1903 7.5. Adding and Removing Endpoints on a Connection 1905 Transport protocols that are explicitly multipath aware are expected 1906 to automatically manage the set of Remote Endpoints that they are 1907 communicating with, and the paths to those endpoints. A PathChange<> 1908 event, described in Section 8.3.2, will be generated when the path 1909 changes. 1911 In some cases, however, it is necessary to explicitly indicate to a 1912 Connection that a new remote endpoint has become available for use, 1913 or to indicate that some remote endpoint is no longer available. 1914 This is most common in the case of peer to peer connections using 1915 Trickle ICE [RFC8838]. 1917 The AddRemote() action can be used to add one or more new remote 1918 endpoints to a Connection: 1920 Connection.AddRemote([]RemoteEndpoint) 1922 Endpoints that are already known to the Connection are ignored. A 1923 call to AddRemote() makes the new remote endpoints available to the 1924 connection, but whether the Connection makes use of those endpoints 1925 will depend on the underlying transport protocol. 1927 Similarly, the RemoveRemote() action can be used to tell a connection 1928 to stop using one or more remote endpoints: 1930 Connection.RemoveRemote([]RemoteEndpoint) 1932 Removing all known remote endpoints can have the effect of aborting 1933 the connection. The effect of removing the active remote endpoint(s) 1934 depends on the underlying transport: multipath aware transports might 1935 be able to switch to a new path if other reachable remote endpoints 1936 exist, or the connection might abort. 1938 Similarly, the AddLocal() and RemoveLocal() actions can be used to 1939 add and remove local endpoints to/from a Connection. 1941 8. Managing Connections 1943 During pre-establishment and after establishment, connections can be 1944 configured and queried using Connection Properties, and asynchronous 1945 information may be available about the state of the connection via 1946 Soft Errors. 1948 Connection Properties represent the configuration and state of the 1949 selected Protocol Stack(s) backing a Connection. These Connection 1950 Properties may be Generic, applying regardless of transport protocol, 1951 or Specific, applicable to a single implementation of a single 1952 transport protocol stack. Generic Connection Properties are defined 1953 in Section 8.1 below. 1955 Protocol Specific Properties are defined in a transport- and 1956 implementation-specific way to permit more specialized protocol 1957 features to be used. Too much reliance by an application on Protocol 1958 Specific Properties can significantly reduce the flexibility of a 1959 transport services implementation to make appropriate selection and 1960 configuration choices. Therefore, it is RECOMMENDED that Protocol 1961 Properties are used for properties common across different protocols 1962 and that Protocol Specific Properties are only used where specific 1963 protocols or properties are necessary. 1965 The application can set and query Connection Properties on a per- 1966 Connection basis. Connection Properties that are not read-only can 1967 be set during pre-establishment (see Section 6.2), as well as on 1968 connections directly using the SetProperty action: 1970 Connection.SetProperty(property, value) 1972 Note that changing one of the Connection Properties on one Connection 1973 in a Connection Group will also change it for all other Connections 1974 of that group; see further Section 7.4. 1976 At any point, the application can query Connection Properties. 1978 ConnectionProperties := Connection.GetProperties() 1979 value := ConnectionProperties.Get(property) 1980 if ConnectionProperties.Has(boolean_or_preference_property) then ... 1982 Depending on the status of the connection, the queried Connection 1983 Properties will include different information: 1985 * The connection state, which can be one of the following: 1986 Establishing, Established, Closing, or Closed. 1988 * Whether the connection can be used to send data. A connection can 1989 not be used for sending if the connection was created with the 1990 Selection Property Direction of Communication set to 1991 unidirectional receive or if a Message marked as Final was sent 1992 over this connection. See also Section 9.1.3.5. 1994 * Whether the connection can be used to receive data. A connection 1995 cannot be used for reading if the connection was created with the 1996 Selection Property Direction of Communication set to 1997 unidirectional send or if a Message marked as Final was received. 1998 See Section 9.3.3.3. The latter is only supported by certain 1999 transport protocols, e.g., by TCP as half-closed connection. 2001 * For Connections that are Established, Closing, or Closed: 2002 Connection Properties (Section 8.1) of the actual protocols that 2003 were selected and instantiated, and Selection Properties that the 2004 application specified on the Preconnection. Selection Properties 2005 of type Preference will be exposed as boolean values indicating 2006 whether or not the property applies to the selected transport. 2007 Note that the instantiated protocol stack might not match all 2008 Protocol Selection Properties that the application specified on 2009 the Preconnection. 2011 * For Connections that are Established: information concerning the 2012 path(s) used by the Protocol Stack. This can be derived from 2013 local PVD information, measurements by the Protocol Stack, or 2014 other sources. For example, a TAPS system that is configured to 2015 receive and process PVD information [RFC7556] could also provide 2016 network configuration information for the chosen path(s). 2018 8.1. Generic Connection Properties 2020 Generic Connection Properties are defined independent of the chosen 2021 protocol stack and therefore available on all Connections. 2023 Many Connection Properties have a corresponding Selection Property 2024 that enables applications to express their preference for protocols 2025 providing a supporting transport feature. 2027 8.1.1. Required Minimum Corruption Protection Coverage for Receiving 2029 Name: recvChecksumLen 2031 Type: Integer or Full Coverage 2033 Default: Full Coverage 2035 If this property is an Integer, it specifies the minimum number of 2036 bytes in a received message that need to be covered by a checksum. A 2037 receiving endpoint will not forward messages that have less coverage 2038 to the application. The application is responsible for handling any 2039 corruption within the non-protected part of the message [RFC8085]. A 2040 special value of 0 means that a received packet may also have a zero 2041 checksum field. 2043 8.1.2. Connection Priority 2045 Name: connPriority 2047 Type: Integer (non-negative) 2049 Default: 100 2051 This Property is a non-negative integer representing the priority of 2052 this Connection relative to other Connections in the same Connection 2053 Group. A higher value reflects a higher priority. It has no effect 2054 on Connections not part of a Connection Group. As noted in 2055 Section 7.4, this property is not entangled when Connections are 2056 cloned, i.e., changing the Priority on one Connection in a Connection 2057 Group does not change it on the other Connections in the same 2058 Connection Group. No guarantees of a specific behavior regarding 2059 Connection Priority are given; a Transport Services system may ignore 2060 this property. See Section 9.2.6 for more details. 2062 8.1.3. Timeout for Aborting Connection 2064 Name: connTimeout 2066 Type: Numeric or Disabled 2068 Default: Disabled 2070 If this property is Numeric, it specifies how long to wait before 2071 deciding that an active Connection has failed when trying to reliably 2072 deliver data to the Remote Endpoint. Adjusting this Property will 2073 only take effect when the underlying stack supports reliability. If 2074 this property has the enumerated value Disabled, it means that no 2075 timeout is scheduled. 2077 8.1.4. Timeout for keep alive packets 2079 Name: keepAliveTimeout 2081 Type: Numeric or Disabled 2083 Default: Implementation-defined 2085 A Transport Services API can request a protocol that supports sending 2086 keep alive packets Section 6.2.10. If this property is an Integer, 2087 it specifies the maximum length of time an idle connection (one for 2088 which no transport packets have been sent) should wait before the 2089 Local Endpoint sends a keep-alive packet to the Remote Endpoint. 2090 Adjusting this Property will only take effect when the underlying 2091 stack supports sending keep-alive packets. Guidance on setting this 2092 value for datagram transports is provided in [RFC8085]. A value 2093 greater than the connection timeout (Section 8.1.3) or the enumerated 2094 value Disabled will disable the sending of keep-alive packets. 2096 8.1.5. Connection Group Transmission Scheduler 2098 Name: connScheduler 2100 Type: Enumeration 2102 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 2104 This property specifies which scheduler should be used among 2105 Connections within a Connection Group, see Section 7.4. The set of 2106 schedulers can be taken from [RFC8260]. 2108 8.1.6. Capacity Profile 2110 Name: connCapacityProfile 2112 Type: Enumeration 2114 Default: Default Profile (Best Effort) 2116 This property specifies the desired network treatment for traffic 2117 sent by the application and the tradeoffs the application is prepared 2118 to make in path and protocol selection to receive that desired 2119 treatment. When the capacity profile is set to a value other than 2120 Default, z Transport Services system SHOULD select paths and 2121 configure protocols to optimize the tradeoff between delay, delay 2122 variation, and efficient use of the available capacity based on the 2123 capacity profile specified. How this is realized is implementation- 2124 specific. The Capacity Profile MAY also be used to set markings on 2125 the wire for Protocol Stacks supporting this. Recommendations for 2126 use with DSCP are provided below for each profile; note that when a 2127 Connection is multiplexed, the guidelines in Section 6 of [RFC7657] 2128 apply. 2130 The following values are valid for the Capacity Profile: 2132 Default: The application provides no information about its expected 2133 capacity profile. Transport Services implementations that map the 2134 requested capacity profile onto per-connection DSCP signaling 2135 SHOULD assign the DSCP Default Forwarding [RFC2474] Per Hop 2136 Behaviour (PHB). 2138 Scavenger: The application is not interactive. It expects to send 2139 and/or receive data without any urgency. This can, for example, 2140 be used to select protocol stacks with scavenger transmission 2141 control and/or to assign the traffic to a lower-effort service. 2142 Transport Services implementations that map the requested capacity 2143 profile onto per-connection DSCP signaling SHOULD assign the DSCP 2144 Less than Best Effort [RFC8622] PHB. 2146 Low Latency/Interactive: The application is interactive, and prefers 2147 loss to latency. Response time should be optimized at the expense 2148 of delay variation and efficient use of the available capacity 2149 when sending on this connection. This can be used by the system 2150 to disable the coalescing of multiple small Messages into larger 2151 packets (Nagle's algorithm); to prefer immediate acknowledgment 2152 from the peer endpoint when supported by the underlying transport; 2153 and so on. Transport Services implementations that map the 2154 requested capacity profile onto per-connection DSCP signaling 2155 without multiplexing SHOULD assign a DSCP Assured Forwarding 2156 (AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is 2157 expected to conform to the configured network service rate could 2158 be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] 2159 PHBs. 2161 Low Latency/Non-Interactive: The application prefers loss to 2162 latency, but is not interactive. Response time should be 2163 optimized at the expense of delay variation and efficient use of 2164 the available capacity when sending on this connection. Transport 2165 system implementations that map the requested capacity profile 2166 onto per-connection DSCP signaling without multiplexing SHOULD 2167 assign a DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] 2168 PHB. 2170 Constant-Rate Streaming: The application expects to send/receive 2171 data at a constant rate after Connection establishment. Delay and 2172 delay variation should be minimized at the expense of efficient 2173 use of the available capacity. This implies that the Connection 2174 might fail if the Path is unable to maintain the desired rate. A 2175 transport can interpret this capacity profile as preferring a 2176 circuit breaker [RFC8084] to a rate-adaptive congestion 2177 controller. Transport system implementations that map the 2178 requested capacity profile onto per-connection DSCP signaling 2179 without multiplexing SHOULD assign a DSCP Assured Forwarding 2180 (AF31,AF32,AF33,AF34) [RFC2597] PHB. 2182 Capacity-Seeking: The application expects to send/receive data at 2183 the maximum rate allowed by its congestion controller over a 2184 relatively long period of time. Transport Services 2185 implementations that map the requested capacity profile onto per- 2186 connection DSCP signaling without multiplexing SHOULD assign a 2187 DSCP Assured Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per 2188 Section 4.8 of [RFC4594]. 2190 The Capacity Profile for a selected protocol stack may be modified on 2191 a per-Message basis using the Transmission Profile Message Property; 2192 see Section 9.1.3.8. 2194 8.1.7. Policy for using Multipath Transports 2196 Name: multipath-policy 2198 Type: Enumeration 2200 Default: Handover 2202 This property specifies the local policy for transferring data across 2203 multiple paths between the same end hosts if Multipath Transport is 2204 not set to Disabled (see Section 6.2.14). Possible values are: 2206 Handover: The connection ought only to attempt to migrate between 2207 different paths when the original path is lost or becomes 2208 unusable. The thresholds used to declare a path unusable are 2209 implementation specific. 2211 Interactive: The connection ought only to attempt to minimize the 2212 latency for interactive traffic patterns by transmitting data 2213 across multiple paths when this is beneficial. The goal of 2214 minimizing the latency will be balanced against the cost of each 2215 of these paths. Depending on the cost of the lower-latency path, 2216 the scheduling might choose to use a higher-latency path. Traffic 2217 can be scheduled such that data may be transmitted on multiple 2218 paths in parallel to achieve a lower latency. The specific 2219 scheduling algorithm is implementation-specific. 2221 Aggregate: The connection ought to attempt to use multiple paths in 2222 parallel to maximize available capacity and possibly overcome the 2223 capacity limitations of the individual paths. The actual strategy 2224 is implementation specific. 2226 Note that this is a local choice - the Remote Endpoint can choose a 2227 different policy. 2229 8.1.8. Bounds on Send or Receive Rate 2231 Name: minSendRate / minRecvRate / maxSendRate / maxRecvRate 2233 Type: Numeric or Unlimited / Numeric or Unlimited / Numeric or 2234 Unlimited / Numeric or Unlimited 2236 Default: Unlimited / Unlimited / Unlimited / Unlimited 2238 Integer values of this property specify an upper-bound rate that a 2239 transfer is not expected to exceed (even if flow control and 2240 congestion control allow higher rates), and/or a lower-bound rate 2241 below which the application does not deem it will be useful. These 2242 are specified in bits per second. The enumerated value Unlimited 2243 indicates that no bound is specified. 2245 8.1.9. Group Connection Limit 2247 Name: groupConnLimit 2249 Type: Numeric or Unlimited 2251 Default: Unlimited 2253 If this property is an Integer, it controls the number of Connections 2254 that can be accepted from a peer as new members of the Connection's 2255 group. Similar to SetNewConnectionLimit(), this limits the number of 2256 ConnectionReceived Events that will occur, but constrained to the 2257 group of the Connection associated with this property. For a multi- 2258 streaming transport, this limits the number of allowed streams. 2260 8.1.10. Isolate Session 2262 Name: isolateSession 2264 Type: Boolean 2266 Default: false 2268 When set to true, this property will initiate new Connections using 2269 as little cached information (such as session tickets or cookies) as 2270 possible from previous connections that are not in the same 2271 Connection Group. Any state generated by this Connection will only 2272 be shared with Connections in the same Connection Group. Cloned 2273 Connections will use saved state from within the Connection Group. 2274 This is used for separating Connection Contexts as specified in 2275 [I-D.ietf-taps-arch]. 2277 Note that this does not guarantee no leakage of information, as 2278 implementations may not be able to fully isolate all caches (e.g. 2279 RTT estimates). Note that this property may degrade connection 2280 performance. 2282 8.1.11. Read-only Connection Properties 2284 The following generic Connection Properties are read-only, i.e. they 2285 cannot be changed by an application. 2287 8.1.11.1. Maximum Message Size Concurrent with Connection Establishment 2289 Name: zeroRttMsgMaxLen 2291 Type: Integer 2293 This property represents the maximum Message size that can be sent 2294 before or during Connection establishment, see also Section 9.1.3.4. 2295 It is specified as the number of bytes. 2297 8.1.11.2. Maximum Message Size Before Fragmentation or Segmentation 2299 Name: singularTransmissionMsgMaxLen 2301 Type: Integer 2303 This property, if applicable, represents the maximum Message size 2304 that can be sent without incurring network-layer fragmentation at the 2305 sender. It is specified as the number of bytes. It exposes a value 2306 to the application based on the Maximum Packet Size (MPS) as 2307 described in Datagram PLPMTUD [RFC8899]. This can allow a sending 2308 stack to avoid unwanted fragmentation at the network-layer or 2309 segmentation by the transport layer. 2311 8.1.11.3. Maximum Message Size on Send 2313 Name: sendMsgMaxLen 2315 Type: Integer 2317 This property represents the maximum Message size that an application 2318 can send. It is specified as the nummber of bytes. 2320 8.1.11.4. Maximum Message Size on Receive 2322 Name: recvMsgMaxLen 2324 Type: Integer 2325 This numeric property represents the maximum Message size that an 2326 application can receive. It specified as the number of bytes. 2328 8.2. TCP-specific Properties: User Timeout Option (UTO) 2330 These properties specify configurations for the User Timeout Option 2331 (UTO), in the case that TCP becomes the chosen transport protocol. 2332 Implementation is optional and useful only if TCP is implemented in 2333 the Transport Services system. 2335 These TCP-specific properties are included here because the feature 2336 Suggest timeout to the peer is part of the minimal set of transport 2337 services [RFC8923], where this feature was categorized as 2338 "functional". This means that when an Transport Services 2339 implementation offers this feature, the Transport Services API has to 2340 expose an interface to the application. Otherwise, the 2341 implementation might violate assumptions by the application, which 2342 could cause the application to fail. 2344 All of the below properties are optional (e.g., it is possible to 2345 specify User Timeout Enabled as true, but not specify an Advertised 2346 User Timeout value; in this case, the TCP default will be used). 2347 These properties reflect the API extension specified in Section 3 of 2348 [RFC5482]. 2350 8.2.1. Advertised User Timeout 2352 Name: tcp.userTimeoutValue 2354 Type: Integer 2356 Default: the TCP default 2358 This time value is advertised via the TCP User Timeout Option (UTO) 2359 [RFC5482] at the Remote Endpoint to adapt its own Timeout for 2360 aborting Connection (see Section 8.1.3) value. 2362 8.2.2. User Timeout Enabled 2364 Name: tcp.userTimeoutEnabled 2366 Type: Boolean 2368 Default: false 2370 This property controls whether the UTO option is enabled for a 2371 connection. This applies to both sending and receiving. 2373 8.2.3. Timeout Changeable 2375 Name: tcp.userTimeoutChangeable 2377 Type: Boolean 2379 Default: true 2381 This property controls whether the Timeout for aborting Connection 2382 (see Section 8.1.3) may be changed based on a UTO option received 2383 from the remote peer. This boolean becomes false when Timeout for 2384 aborting Connection (see Section 8.1.3) is used. 2386 8.3. Connection Lifecycle Events 2388 During the lifetime of a connection there are events that can occur 2389 when configured. 2391 8.3.1. Soft Errors 2393 Asynchronous introspection is also possible, via the SoftError Event. 2394 This event informs the application about the receipt and contents of 2395 an ICMP error message related to the Connection. This will only 2396 happen if the underlying protocol stack supports access to soft 2397 errors; however, even if the underlying stack supports it, there is 2398 no guarantee that a soft error will be signaled. 2400 Connection -> SoftError<> 2402 8.3.2. Path change 2404 This event notifies the application when at least one of the paths 2405 underlying a Connection has changed. Changes occur on a single path 2406 when the PMTU changes as well as when multiple paths are used and 2407 paths are added or removed, the set of local endpoints changes, or a 2408 handover has been performed. 2410 Connection -> PathChange<> 2412 9. Data Transfer 2414 Data is sent and received as Messages, which allows the application 2415 to communicate the boundaries of the data being transferred. 2417 9.1. Messages and Framers 2419 Each Message has an optional Message Context, which allows to add 2420 Message Properties, identify Send Events related to a specific 2421 Message or to inspect meta-data related to the Message sent. Framers 2422 can be used to extend or modify the message data with additional 2423 information that can be processed at the receiver to detect message 2424 boundaries. 2426 9.1.1. Message Contexts 2428 Using the MessageContext object, the application can set and retrieve 2429 meta-data of the message, including Message Properties (see 2430 Section 9.1.3) and framing meta-data (see Section 9.1.2.2). 2431 Therefore, a MessageContext object can be passed to the Send action 2432 and is returned by each Send and Receive related event. 2434 Message Properties can be set and queried using the Message Context: 2436 MessageContext.add(property, value) 2437 PropertyValue := MessageContext.get(property) 2439 These Message Properties may be generic properties or Protocol 2440 Specific Properties. 2442 For MessageContexts returned by send Events (see Section 9.2.2) and 2443 receive Events (see Section 9.3.2), the application can query 2444 information about the Local and Remote Endpoint: 2446 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 2447 LocalEndpoint := MessageContext.GetLocalEndpoint() 2449 9.1.2. Message Framers 2451 Although most applications communicate over a network using well- 2452 formed Messages, the boundaries and metadata of the Messages are 2453 often not directly communicated by the transport protocol itself. 2454 For example, HTTP applications send and receive HTTP messages over a 2455 byte-stream transport, requiring that the boundaries of HTTP messages 2456 be parsed from the stream of bytes. 2458 Message Framers allow extending a Connection's Protocol Stack to 2459 define how to encapsulate or encode outbound Messages, and how to 2460 decapsulate or decode inbound data into Messages. Message Framers 2461 allow message boundaries to be preserved when using a Connection 2462 object, even when using byte-stream transports. This is designed 2463 based on the fact that many of the current application protocols 2464 evolved over TCP, which does not provide message boundary 2465 preservation, and since many of these protocols require message 2466 boundaries to function, each application layer protocol has defined 2467 its own framing. 2469 To use a Message Framer, the application adds it to its Preconnection 2470 object. Then, the Message Framer can intercept all calls to Send() 2471 or Receive() on a Connection to add Message semantics, in addition to 2472 interacting with the setup and teardown of the Connection. A Framer 2473 can start sending data before the application sends data if the 2474 framing protocol requires a prefix or handshake (see [RFC8229] for an 2475 example of such a framing protocol). 2477 Initiate() Send() Receive() Close() 2478 | | ^ | 2479 | | | | 2480 +----v----------v---------+----------v-----+ 2481 | Connection | 2482 +----+----------+---------^----------+-----+ 2483 | | | | 2484 | +-----------------+ | 2485 | | Messages | | 2486 | +-----------------+ | 2487 | | | | 2488 +----v----------v---------+----------v-----+ 2489 | Framer(s) | 2490 +----+----------+---------^----------+-----+ 2491 | | | | 2492 | +-----------------+ | 2493 | | Byte-stream | | 2494 | +-----------------+ | 2495 | | | | 2496 +----v----------v---------+----------v-----+ 2497 | Transport Protocol Stack | 2498 +------------------------------------------+ 2500 Figure 1: Protocol Stack showing a Message Framer 2502 Note that while Message Framers add the most value when placed above 2503 a protocol that otherwise does not preserve message boundaries, they 2504 can also be used with datagram- or message-based protocols. In these 2505 cases, they add an additional transformation to further encode or 2506 encapsulate, and can potentially support packing multiple 2507 application-layer Messages into individual transport datagrams. 2509 The API to implement a Message Framer can vary depending on the 2510 implementation; guidance on implementing Message Framers can be found 2511 in [I-D.ietf-taps-impl]. 2513 9.1.2.1. Adding Message Framers to Pre-Connections 2515 The Message Framer object can be added to one or more Preconnections 2516 to run on top of transport protocols. Multiple Framers may be added 2517 to a Preconnection; in this case, the Framers operate as a framing 2518 stack, i.e. the last one added runs first when framing outbound 2519 messages, and last when parsing inbound data. 2521 The following example adds a basic HTTP Message Framer to a 2522 Preconnection: 2524 framer := NewHTTPMessageFramer() 2525 Preconnection.AddFramer(framer) 2527 Since Message Framers pass from Preconnection to Listener or 2528 Connection, addition of Framers must happen before any operation that 2529 may result in the creation of a Connection. 2531 9.1.2.2. Framing Meta-Data 2533 When sending Messages, applications can add Framer-specific 2534 properties to a MessageContext (Section 9.1.1). In order to set 2535 these properties, the add and get actions on the MessageContext. To 2536 avoid naming conflicts, the property names SHOULD be prefixed with a 2537 namespace referencing the framer implementation or the protocol it 2538 implements as described in Section 4.1. 2540 This mechanism can be used, for example, to set the type of a Message 2541 for a TLV format. The namespace of values is custom for each unique 2542 Message Framer. 2544 messageContext := NewMessageContext() 2545 messageContext.add(framer, key, value) 2546 Connection.Send(messageData, messageContext) 2548 When an application receives a MessageContext in a Receive event, it 2549 can also look to see if a value was set by a specific Message Framer. 2551 messageContext.get(framer, key) -> value 2553 For example, if an HTTP Message Framer is used, the values could 2554 correspond to HTTP headers: 2556 httpFramer := NewHTTPMessageFramer() 2557 ... 2558 messageContext := NewMessageContext() 2559 messageContext.add(httpFramer, "accept", "text/html") 2561 9.1.3. Message Properties 2563 Applications needing to annotate the Messages they send with extra 2564 information (for example, to control how data is scheduled and 2565 processed by the transport protocols supporting the Connection) can 2566 include this information in the Message Context passed to the Send 2567 Action. For other uses of the message context, see Section 9.1.1. 2569 Message Properties are per-Message, not per-Send if partial Messages 2570 are sent (Section 9.2.3). All data blocks associated with a single 2571 Message share properties specified in the Message Contexts. For 2572 example, it would not make sense to have the beginning of a Message 2573 expire, but allow the end of a Message to still be sent. 2575 A MessageContext object contains metadata for the Messages to be sent 2576 or received. 2578 messageData := "hello" 2579 messageContext := NewMessageContext() 2580 messageContext.add(parameter, value) 2581 Connection.Send(messageData, messageContext) 2583 The simpler form of Send, which does not take any messageContext, is 2584 equivalent to passing a default MessageContext without adding any 2585 Message Properties. 2587 If an application wants to override Message Properties for a specific 2588 message, it can acquire an empty MessageContext Object and add all 2589 desired Message Properties to that Object. It can then reuse the 2590 same messageContext Object for sending multiple Messages with the 2591 same properties. 2593 Properties can be added to a MessageContext object only before the 2594 context is used for sending. Once a MessageContext has been used 2595 with a Send call, further modifications to the MessageContext object 2596 do not have any effect on this Send call. Message Properties that 2597 are not added to a MessageContext object before using the context for 2598 sending will either take a specific default value or be configured 2599 based on Selection or Connection Properties of the Connection that is 2600 associated with the Send call. This initialization behavior is 2601 defined per Message Property below. 2603 The Message Properties could be inconsistent with the properties of 2604 the Protocol Stacks underlying the Connection on which a given 2605 Message is sent. For example, a Protocol Stack must be able to 2606 provide ordering if the msgOrdered property of a Message is enabled. 2607 Sending a Message with Message Properties inconsistent with the 2608 Selection Properties of the Connection yields an error. 2610 If a Message Property contradicts a Connection Property, and if this 2611 per-Message behavior can be supported, it overrides the Connection 2612 Property for the specific Message. For example, if Reliable Data 2613 Transfer (Connection) is set to Require and a protocol with 2614 configurable per-Message reliability is used, setting Reliable Data 2615 Transfer (Message) to false for a particular Message will allow this 2616 Message to be sent without any reliability guarantees. Changing the 2617 Reliable Data Transfer property on Messages is only possible for 2618 Connections that were established enabling the Selection Property 2619 Configure Per-Message Reliability. 2621 The following Message Properties are supported: 2623 9.1.3.1. Lifetime 2625 Name: msgLifetime 2627 Type: Numeric 2629 Default: infinite 2631 The Lifetime specifies how long a particular Message can wait to be 2632 sent to the Remote Endpoint before it is irrelevant and no longer 2633 needs to be (re-)transmitted. This is a hint to the Transport 2634 Services implementation - it is not guaranteed that a Message will 2635 not be sent when its Lifetime has expired. 2637 Setting a Message's Lifetime to infinite indicates that the 2638 application does not wish to apply a time constraint on the 2639 transmission of the Message, but it does not express a need for 2640 reliable delivery; reliability is adjustable per Message via the 2641 Reliable Data Transfer (Message) property (see Section 9.1.3.7). The 2642 type and units of Lifetime are implementation-specific. 2644 9.1.3.2. Priority 2646 Name: msgPriority 2648 Type: Integer (non-negative) 2650 Default: 100 2652 This property specifies the priority of a Message, relative to other 2653 Messages sent over the same Connection. 2655 A Message with Priority 0 will yield to a Message with Priority 1, 2656 which will yield to a Message with Priority 2, and so on. Priorities 2657 may be used as a sender-side scheduling construct only, or be used to 2658 specify priorities on the wire for Protocol Stacks supporting 2659 prioritization. 2661 Note that this property is not a per-message override of the 2662 Connection Priority - see Section 8.1.2. The Priority properties may 2663 interact, but can be used independently and be realized by different 2664 mechanisms; see Section 9.2.6. 2666 9.1.3.3. Ordered 2668 Name: msgOrdered 2670 Type: Boolean 2672 Default: the queried Boolean value of the Selection Property 2673 preserveOrder (Section 6.2.4) 2675 The order in which Messages were submitted for transmission via the 2676 Send Action will be preserved on delivery via Receive<> events for 2677 all Messages on a Connection that have this Message Property set to 2678 true. 2680 If false, the Message is delivered to the receiving application 2681 without preserving the ordering. This property is used for protocols 2682 that support preservation of data ordering, see Section 6.2.4, but 2683 allow out-of-order delivery for certain messages, e.g., by 2684 multiplexing independent messages onto different streams. 2686 If it is not configured by the application before sending, this 2687 property's default value will be based on the Selection Property 2688 preserveOrder of the Connection associated with the Send Action. 2690 9.1.3.4. Safely Replayable 2692 Name: safelyReplayable 2694 Type: Boolean 2696 Default: false 2698 If true, Safely Replayable specifies that a Message is safe to send 2699 to the Remote Endpoint more than once for a single Send Action. It 2700 marks the data as safe for certain 0-RTT establishment techniques, 2701 where retransmission of the 0-RTT data may cause the remote 2702 application to receive the Message multiple times. 2704 For protocols that do not protect against duplicated messages, e.g., 2705 UDP, all messages need to be marked as Safely Replayable. To enable 2706 protocol selection to choose such a protocol, Safely Replayable needs 2707 to be added to the TransportProperties passed to the Preconnection. 2708 If such a protocol was chosen, disabling Safely Replayable on 2709 individual messages MUST result in a SendError. 2711 9.1.3.5. Final 2713 Name: final 2715 Type: Boolean 2717 Default: false 2719 If true, this indicates a Message is the last that the application 2720 will send on a Connection. This allows underlying protocols to 2721 indicate to the Remote Endpoint that the Connection has been 2722 effectively closed in the sending direction. For example, TCP-based 2723 Connections can send a FIN once a Message marked as Final has been 2724 completely sent, indicated by marking endOfMessage. Protocols that 2725 do not support signalling the end of a Connection in a given 2726 direction will ignore this property. 2728 A Final Message must always be sorted to the end of a list of 2729 Messages. The Final property overrides Priority and any other 2730 property that would re-order Messages. If another Message is sent 2731 after a Message marked as Final has already been sent on a 2732 Connection, the Send Action for the new Message will cause a 2733 SendError Event. 2735 9.1.3.6. Sending Corruption Protection Length 2737 Name: msgChecksumLen 2739 Type: Integer or Full Coverage 2741 Default: Full Coverage 2743 If this property is an Integer, it specifies the minimum length of 2744 the section of a sent Message, starting from byte 0, that the 2745 application requires to be delivered without corruption due to lower 2746 layer errors. It is used to specify options for simple integrity 2747 protection via checksums. A value of 0 means that no checksum needs 2748 to be calculated, and the enumerated value Full Coverage means that 2749 the entire Message needs to be protected by a checksum. Only Full 2750 Coverage is guaranteed, any other requests are advisory, which may 2751 result in Full Coverage being applied. 2753 9.1.3.7. Reliable Data Transfer (Message) 2755 Name: msgReliable 2757 Type: Boolean 2759 Default: the queried Boolean value of the Selection Property 2760 reliability (Section 6.2.1) 2762 When true, this property specifies that a Message should be sent in 2763 such a way that the transport protocol ensures all data is received 2764 on the other side without corruption. Changing the Reliable Data 2765 Transfer property on Messages is only possible for Connections that 2766 were established enabling the Selection Property Configure Per- 2767 Message Reliability. When this is not the case, changing msgReliable 2768 will generate an error. 2770 Disabling this property indicates that the Transport Services system 2771 may disable retransmissions or other reliability mechanisms for this 2772 particular Message, but such disabling is not guaranteed. 2774 If it is not configured by the application before sending, this 2775 property's default value will be based on the Selection Property 2776 reliability of the Connection associated with the Send Action. 2778 9.1.3.8. Message Capacity Profile Override 2780 Name: msgCapacityProfile 2782 Type: Enumeration 2784 Default: inherited from the Connection Property connCapacityProfile 2785 (Section 8.1.6) 2787 This enumerated property specifies the application's preferred 2788 tradeoffs for sending this Message; it is a per-Message override of 2789 the Capacity Profile connection property (see Section 8.1.6). If it 2790 is not configured by the application before sending, this property's 2791 default value will be based on the Connection Property 2792 connCapacityProfile of the Connection associated with the Send 2793 Action. 2795 9.1.3.9. No Network-Layer Fragmentation 2797 Name: noFragmentation 2799 Type: Boolean 2800 Default: false 2802 This property specifies that a message should be sent and received 2803 without network-layer fragmentation, if possible. It can be used to 2804 avoid network layer fragmentation when transport segmentation is 2805 prefered. 2807 This only takes effect when the transport uses a network layer that 2808 supports this functionality. When it does take effect, setting this 2809 property to true will cause the sender to avoid network-layer source 2810 frgementation. When using IPv4, this will result in the Don't 2811 Fragment bit being set in the IP header. 2813 Attempts to send a message with this property that result in a size 2814 greater than the transport's current estimate of its maximum packet 2815 size (singularTransmissionMsgMaxLen) can result in transport 2816 segmentation when permitted, or in a SendError. 2818 Note: noSegmentation should be used when it is desired to only send a 2819 message within a single network packet. 2821 9.1.3.10. No Segmentation 2823 Name: noSegmentation 2825 Type: Boolean 2827 Default: false 2829 When set to true, this property requests the transport layer to not 2830 provide segmentation of messages larger than the maximum size 2831 permitted by the network layer, and also to avoid network-layer 2832 source fragmentation of messages. When running over IPv4, setting 2833 this property to true can result in a sending endpount setting the 2834 Don't Fragment bit in the IPv4 header of packets generated by the 2835 transport layer. An attempt to send a message that results in a size 2836 greater than the transport's current estimate of its maximum packet 2837 size (singularTransmissionMsgMaxLen) will result in a SendError. 2838 This only takes effect when the transport and network layer support 2839 this functionality. 2841 9.2. Sending Data 2843 Once a Connection has been established, it can be used for sending 2844 Messages. By default, Send enqueues a complete Message, and takes 2845 optional per-Message properties (see Section 9.2.1). All Send 2846 actions are asynchronous, and deliver Events (see Section 9.2.2). 2847 Sending partial Messages for streaming large data is also supported 2848 (see Section 9.2.3). 2850 Messages are sent on a Connection using the Send action: 2852 Connection.Send(messageData, messageContext?, endOfMessage?) 2854 where messageData is the data object to send, and messageContext 2855 allows adding Message Properties, identifying Send Events related to 2856 a specific Message or inspecting meta-data related to the Message 2857 sent (see Section 9.1.1). 2859 The optional endOfMessage parameter supports partial sending and is 2860 described in Section 9.2.3. 2862 9.2.1. Basic Sending 2864 The most basic form of sending on a connection involves enqueuing a 2865 single Data block as a complete Message with default Message 2866 Properties. 2868 messageData := "hello" 2869 Connection.Send(messageData) 2871 The interpretation of a Message to be sent is dependent on the 2872 implementation, and on the constraints on the Protocol Stacks implied 2873 by the Connection's transport properties. For example, a Message may 2874 be a single datagram for UDP Connections; or an HTTP Request for HTTP 2875 Connections. 2877 Some transport protocols can deliver arbitrarily sized Messages, but 2878 other protocols constrain the maximum Message size. Applications can 2879 query the Connection Property "Maximum Message size on send" 2880 (Section 8.1.11.3) to determine the maximum size allowed for a single 2881 Message. If a Message is too large to fit in the Maximum Message 2882 Size for the Connection, the Send will fail with a SendError event 2883 (Section 9.2.2.3). For example, it is invalid to send a Message over 2884 a UDP connection that is larger than the available datagram sending 2885 size. 2887 9.2.2. Send Events 2889 Like all Actions in Transport Services API, the Send Action is 2890 asynchronous. There are several Events that can be delivered in 2891 response to Sending a Message. Exactly one Event (Sent, Expired, or 2892 SendError) will be delivered in response to each call to Send. 2894 Note that if partial Sends are used (Section 9.2.3), there will still 2895 be exactly one Send Event delivered for each call to Send. For 2896 example, if a Message expired while two requests to Send data for 2897 that Message are outstanding, there will be two Expired events 2898 delivered. 2900 The Transport Services API should allow the application to correlate 2901 which Send Action resulted in a particular Send Event. The manner in 2902 which this correlation is indicated is implementation-specific. 2904 9.2.2.1. Sent 2906 Connection -> Sent 2908 The Sent Event occurs when a previous Send Action has completed, 2909 i.e., when the data derived from the Message has been passed down or 2910 through the underlying Protocol Stack and is no longer the 2911 responsibility of the Transport Services API. The exact disposition 2912 of the Message (i.e., whether it has actually been transmitted, moved 2913 into a buffer on the network interface, moved into a kernel buffer, 2914 and so on) when the Sent Event occurs is implementation-specific. 2915 The Sent Event contains a reference to the Message Context of the 2916 Message to which it applies. 2918 Sent Events allow an application to obtain an understanding of the 2919 amount of buffering it creates. That is, if an application calls the 2920 Send Action multiple times without waiting for a Sent Event, it has 2921 created more buffer inside the Transport Services system than an 2922 application that always waits for the Sent Event before calling the 2923 next Send Action. 2925 9.2.2.2. Expired 2927 Connection -> Expired 2929 The Expired Event occurs when a previous Send Action expired before 2930 completion; i.e. when the Message was not sent before its Lifetime 2931 (see Section 9.1.3.1) expired. This is separate from SendError, as 2932 it is an expected behavior for partially reliable transports. The 2933 Expired Event contains a reference to the Message Context of the 2934 Message to which it applies. 2936 9.2.2.3. SendError 2938 Connection -> SendError 2940 A SendError occurs when a Message was not sent due to an error 2941 condition: an attempt to send a Message which is too large for the 2942 system and Protocol Stack to handle, some failure of the underlying 2943 Protocol Stack, or a set of Message Properties not consistent with 2944 the Connection's transport properties. The SendError contains a 2945 reference to the Message Context of the Message to which it applies. 2947 9.2.3. Partial Sends 2949 It is not always possible for an application to send all data 2950 associated with a Message in a single Send Action. The Message data 2951 may be too large for the application to hold in memory at one time, 2952 or the length of the Message may be unknown or unbounded. 2954 Partial Message sending is supported by passing an endOfMessage 2955 boolean parameter to the Send Action. This value is always true by 2956 default, and the simpler forms of Send are equivalent to passing true 2957 for endOfMessage. 2959 The following example sends a Message in two separate calls to Send. 2961 messageContext := NewMessageContext() 2962 messageContext.add(parameter, value) 2964 messageData := "hel" 2965 endOfMessage := false 2966 Connection.Send(messageData, messageContext, endOfMessage) 2968 messageData := "lo" 2969 endOfMessage := true 2970 Connection.Send(messageData, messageContext, endOfMessage) 2972 All data sent with the same MessageContext object will be treated as 2973 belonging to the same Message, and will constitute an in-order series 2974 until the endOfMessage is marked. 2976 9.2.4. Batching Sends 2978 To reduce the overhead of sending multiple small Messages on a 2979 Connection, the application could batch several Send Actions 2980 together. This provides a hint to the system that the sending of 2981 these Messages ought to be coalesced when possible, and that sending 2982 any of the batched Messages can be delayed until the last Message in 2983 the batch is enqueued. 2985 The semantics for starting and ending a batch can be implementation- 2986 specific, but need to allow multiple Send Actions to be enqueued. 2988 Connection.StartBatch() 2989 Connection.Send(messageData) 2990 Connection.Send(messageData) 2991 Connection.EndBatch() 2993 9.2.5. Send on Active Open: InitiateWithSend 2995 For application-layer protocols where the Connection initiator also 2996 sends the first message, the InitiateWithSend() action combines 2997 Connection initiation with a first Message sent: 2999 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 3001 Whenever possible, a messageContext should be provided to declare the 3002 Message passed to InitiateWithSend as Safely Replayable. This allows 3003 the Transport Services system to make use of 0-RTT establishment in 3004 case this is supported by the available protocol stacks. When the 3005 selected stack(s) do not support transmitting data upon connection 3006 establishment, InitiateWithSend is identical to Initiate() followed 3007 by Send(). 3009 Neither partial sends nor send batching are supported by 3010 InitiateWithSend(). 3012 The Events that may be sent after InitiateWithSend() are equivalent 3013 to those that would be sent by an invocation of Initiate() followed 3014 immediately by an invocation of Send(), with the caveat that a send 3015 failure that occurs because the Connection could not be established 3016 will not result in a SendError separate from the EstablishmentError 3017 signaling the failure of Connection establishment. 3019 9.2.6. Priority and the Transport Services API 3021 The Transport Services API provides two properties to allow a sender 3022 to signal the relative priority of data transmission: the Priority 3023 Message Property Section 9.1.3.2, and the Connection Priority 3024 Connection Property Section 8.1.2. These properties are designed to 3025 allow the expression and implementation of a wide variety of 3026 approaches to transmission priority in the transport and application 3027 layer, including those which do not appear on the wire (affecting 3028 only sender-side transmission scheduling) as well as those that do 3029 (e.g. [I-D.ietf-httpbis-priority]. 3031 A Transport Services system gives no guarantees about how its 3032 expression of relative priorities will be realized. However, the 3033 Transport Services system will seek to ensure that performance of 3034 relatively-prioritized connections and messages is not worse with 3035 respect to those connections and messages than an equivalent 3036 configuration in which all prioritization properties are left at 3037 their defaults. 3039 The Transport Services API does order Connection Priority over the 3040 Priority Message Property. In the absense of other externalities 3041 (e.g., transport-layer flow control), a priority 1 Message on a 3042 priority 0 Connection will be sent before a priority 0 Message on a 3043 priority 1 Connection in the same group. 3045 9.3. Receiving Data 3047 Once a Connection is established, it can be used for receiving data 3048 (unless the Direction of Communication property is set to 3049 unidirectional send). As with sending, the data is received in 3050 Messages. Receiving is an asynchronous operation, in which each call 3051 to Receive enqueues a request to receive new data from the 3052 connection. Once data has been received, or an error is encountered, 3053 an event will be delivered to complete any pending Receive requests 3054 (see Section 9.3.2). If Messages arrive at the Transport Services 3055 system before Receive requests are issued, ensuing Receive requests 3056 will first operate on these Messages before awaiting any further 3057 Messages. 3059 9.3.1. Enqueuing Receives 3061 Receive takes two parameters to specify the length of data that an 3062 application is willing to receive, both of which are optional and 3063 have default values if not specified. 3065 Connection.Receive(minIncompleteLength?, maxLength?) 3067 By default, Receive will try to deliver complete Messages in a single 3068 event (Section 9.3.2.1). 3070 The application can set a minIncompleteLength value to indicate the 3071 smallest partial Message data size in bytes that should be delivered 3072 in response to this Receive. By default, this value is infinite, 3073 which means that only complete Messages should be delivered (see 3074 Section 9.3.2.2 and Section 9.1.2 for more information on how this is 3075 accomplished). If this value is set to some smaller value, the 3076 associated receive event will be triggered only when at least that 3077 many bytes are available, or the Message is complete with fewer 3078 bytes, or the system needs to free up memory. Applications should 3079 always check the length of the data delivered to the receive event 3080 and not assume it will be as long as minIncompleteLength in the case 3081 of shorter complete Messages or memory issues. 3083 The maxLength argument indicates the maximum size of a Message in 3084 bytes that the application is currently prepared to receive. The 3085 default value for maxLength is infinite. If an incoming Message is 3086 larger than the minimum of this size and the maximum Message size on 3087 receive for the Connection's Protocol Stack, it will be delivered via 3088 ReceivedPartial events (Section 9.3.2.2). 3090 Note that maxLength does not guarantee that the application will 3091 receive that many bytes if they are available; the Transport Services 3092 API could return ReceivedPartial events with less data than maxLength 3093 according to implementation constraints. Note also that maxLength 3094 and minIncompleteLength are intended only to manage buffering, and 3095 are not interpreted as a receiver preference for message reordering. 3097 9.3.2. Receive Events 3099 Each call to Receive will be paired with a single Receive Event, 3100 which can be a success or an error. This allows an application to 3101 provide backpressure to the transport stack when it is temporarily 3102 not ready to receive messages. 3104 The Transport Services API should allow the application to correlate 3105 which call to Receive resulted in a particular Receive Event. The 3106 manner in which this correlation is indicated is implementation- 3107 specific. 3109 9.3.2.1. Received 3111 Connection -> Received 3113 A Received event indicates the delivery of a complete Message. It 3114 contains two objects, the received bytes as messageData, and the 3115 metadata and properties of the received Message as messageContext. 3117 The messageData object provides access to the bytes that were 3118 received for this Message, along with the length of the byte array. 3119 The messageContext is provided to enable retrieving metadata about 3120 the message and referring to the message. The messageContext object 3121 ist described in Section 9.1.1. 3123 See Section 9.1.2 for handling Message framing in situations where 3124 the Protocol Stack only provides a byte-stream transport. 3126 9.3.2.2. ReceivedPartial 3128 Connection -> ReceivedPartial 3130 If a complete Message cannot be delivered in one event, one part of 3131 the Message can be delivered with a ReceivedPartial event. To 3132 continue to receive more of the same Message, the application must 3133 invoke Receive again. 3135 Multiple invocations of ReceivedPartial deliver data for the same 3136 Message by passing the same MessageContext, until the endOfMessage 3137 flag is delivered or a ReceiveError occurs. All partial blocks of a 3138 single Message are delivered in order without gaps. This event does 3139 not support delivering discontiguous partial Messages. If, for 3140 example, Message A is divided into three pieces (A1, A2, A3) and 3141 Message B is divided into three pieces (B1, B2, B3), and 3142 preserveOrder is not Required, the ReceivedPartial may deliver them 3143 in a sequence like this: A1, B1, B2, A2, A3, B3, because the 3144 messageContext allows the application to identify the pieces as 3145 belonging to Message A and B, respectively. However, a sequence 3146 like: A1, A3 will never occur. 3148 If the minIncompleteLength in the Receive request was set to be 3149 infinite (indicating a request to receive only complete Messages), 3150 the ReceivedPartial event may still be delivered if one of the 3151 following conditions is true: 3153 * the underlying Protocol Stack supports message boundary 3154 preservation, and the size of the Message is larger than the 3155 buffers available for a single message; 3157 * the underlying Protocol Stack does not support message boundary 3158 preservation, and the Message Framer (see Section 9.1.2) cannot 3159 determine the end of the message using the buffer space it has 3160 available; or 3162 * the underlying Protocol Stack does not support message boundary 3163 preservation, and no Message Framer was supplied by the 3164 application 3166 Note that in the absence of message boundary preservation or a 3167 Message Framer, all bytes received on the Connection will be 3168 represented as one large Message of indeterminate length. 3170 In the following example, an application only wants to receive up to 3171 1000 bytes at a time from a Connection. If a 1500-byte message 3172 arrives, it would receive the message in two separate ReceivedPartial 3173 events. 3175 Connection.Receive(1, 1000) 3177 // Receive first 1000 bytes, message is incomplete 3178 Connection -> ReceivedPartial 3180 Connection.Receive(1, 1000) 3182 // Receive last 500 bytes, message is now complete 3183 Connection -> ReceivedPartial 3185 9.3.2.3. ReceiveError 3187 Connection -> ReceiveError 3189 A ReceiveError occurs when data is received by the underlying 3190 Protocol Stack that cannot be fully retrieved or parsed, and when it 3191 is useful for the application to be notified of such errors. For 3192 example, a ReceiveError can indicate that a Message (identified via 3193 the MessageContext) that was being partially received previously, but 3194 had not completed, encountered an error and will not be completed. 3195 This can be useful for an application, which may want to use this 3196 error as a hint to remove previously received Message parts from 3197 memory. As another example, if an incoming Message does not fulfill 3198 the Required Minimum Corruption Protection Coverage for Receiving 3199 property (see Section 8.1.1), an application can use this error as a 3200 hint to inform the peer application to adjust the Sending Corruption 3201 Protection Length property (see Section 9.1.3.6). 3203 In contrast, internal protocol reception errors (e.g., loss causing 3204 retransmissions in TCP) are not signalled by this Event. Conditions 3205 that irrevocably lead to the termination of the Connection are 3206 signaled using ConnectionError (see Section 10). 3208 9.3.3. Receive Message Properties 3210 Each Message Context may contain metadata from protocols in the 3211 Protocol Stack; which metadata is available is Protocol Stack 3212 dependent. These are exposed through additional read-only Message 3213 Properties that can be queried from the MessageContext object (see 3214 Section 9.1.1) passed by the receive event. The following metadata 3215 values are supported: 3217 9.3.3.1. UDP(-Lite)-specific Property: ECN 3219 When available, Message metadata carries the value of the Explicit 3220 Congestion Notification (ECN) field. This information can be used 3221 for logging and debugging, and for building applications that need 3222 access to information about the transport internals for their own 3223 operation. This property is specific to UDP and UDP-Lite because 3224 these protocols do not implement congestion control, and hence expose 3225 this functionality to the application (see [RFC8293], following the 3226 guidance in [RFC8085]) 3228 9.3.3.2. Early Data 3230 In some cases it can be valuable to know whether data was read as 3231 part of early data transfer (before connection establishment has 3232 finished). This is useful if applications need to treat early data 3233 separately, e.g., if early data has different security properties 3234 than data sent after connection establishment. In the case of TLS 3235 1.3, client early data can be replayed maliciously (see [RFC8446]). 3236 Thus, receivers might wish to perform additional checks for early 3237 data to ensure it is safely replayable. If TLS 1.3 is available and 3238 the recipient Message was sent as part of early data, the 3239 corresponding metadata carries a flag indicating as such. If early 3240 data is enabled, applications should check this metadata field for 3241 Messages received during connection establishment and respond 3242 accordingly. 3244 9.3.3.3. Receiving Final Messages 3246 The Message Context can indicate whether or not this Message is the 3247 Final Message on a Connection. For any Message that is marked as 3248 Final, the application can assume that there will be no more Messages 3249 received on the Connection once the Message has been completely 3250 delivered. This corresponds to the Final property that may be marked 3251 on a sent Message, see Section 9.1.3.5. 3253 Some transport protocols and peers do not support signaling of the 3254 Final property. Applications therefore should not rely on receiving 3255 a Message marked Final to know that the sending endpoint is done 3256 sending on a connection. 3258 Any calls to Receive once the Final Message has been delivered will 3259 result in errors. 3261 10. Connection Termination 3263 A Connection can be terminated i) by the Local Endpoint (i.e., the 3264 application calls the Close, CloseGroup, Abort or AbortGroup Action), 3265 ii) by the Remote Endpoint (i.e., the remote application calls the 3266 Close, CloseGroup, Abort or AbortGroup Action), or iii) because of an 3267 error (e.g., a timeout). A local call of the Close Action will cause 3268 the Connection to either send a Closed Event or a ConnectionError 3269 Event, and a local call of the CloseGroup Action will cause all of 3270 the Connections in the group to either send a Closed Event or a 3271 ConnectionError Event. A local call of the Abort Action will cause 3272 the Connection to send a ConnectionError Event, indicating local 3273 Abort as a reason, and a local call of the AbortGroup Action will 3274 cause all of the Connections in the group to send a ConnectionError 3275 Event, indicating local Abort as a reason. 3277 Remote Action calls map to Events similar to local calls (e.g., a 3278 remote Close causes the Connection to either send a Closed Event or a 3279 ConnectionError Event), but, different from local Action calls, it is 3280 not guaranteed that such Events will indeed be invoked. When an 3281 application needs to free resources associated with a Connection, it 3282 should therefore not rely on the invocation of such Events due to 3283 termination calls from the Remote Endpoint, but instead use the local 3284 termination Actions. 3286 Close terminates a Connection after satisfying all the requirements 3287 that were specified regarding the delivery of Messages that the 3288 application has already given to the Transport Services system. Upon 3289 successfully satisfying all these requirements, the Connection will 3290 send the Closed Event. For example, if reliable delivery was 3291 requested for a Message handed over before calling Close, the Closed 3292 Event will signify that this Message has indeed been delivered. This 3293 Action does not affect any other Connection in the same Connection 3294 Group. 3296 Connection.Close() 3298 The Closed Event informs the application that a Close Action has 3299 successfully completed, or that the Remote Endpoint has closed the 3300 Connection. There is no guarantee that a remote Close will be 3301 signaled. 3303 Connection -> Closed<> 3304 Abort terminates a Connection without delivering any remaining 3305 Messages. This action does not affect any other Connection that is 3306 entangled with this one in a Connection Group. When the Abort Action 3307 has finished, the Connection will send a ConnectionError Event, 3308 indicating local Abort as a reason. 3310 Connection.Abort() 3312 CloseGroup gracefully terminates a Connection and any other 3313 Connections in the same Connection Group. For example, all of the 3314 Connections in a group might be streams of a single session for a 3315 multistreaming protocol; closing the entire group will close the 3316 underlying session. See also Section 7.4. All Connections in the 3317 group will send a Closed Event when the CloseGroup Action was 3318 successful. As with Close, any Messages remaining to be processed on 3319 a Connection will be handled prior to closing. 3321 Connection.CloseGroup() 3323 AbortGroup terminates a Connection and any other Connections that are 3324 in the same Connection Group without delivering any remaining 3325 Messages. When the AbortGroup Action has finished, all Connections 3326 in the group will send a ConnectionError Event, indicating local 3327 Abort as a reason. 3329 Connection.AbortGroup() 3331 A ConnectionError informs the application that: 1) data could not be 3332 delivered to the peer after a timeout, or 2) the Connection has been 3333 aborted (e.g., because the peer has called Abort). There is no 3334 guarantee that an Abort from the peer will be signaled. 3336 Connection -> ConnectionError 3338 11. Connection State and Ordering of Operations and Events 3340 This Transport Services API is designed to be independent of an 3341 implementation's concurrency model. The details of how exactly 3342 actions are handled, and how events are dispatched, are 3343 implementation dependent. 3345 Each transition of connection state is associated with one of more 3346 events: 3348 * Ready<> occurs when a Connection created with Initiate() or 3349 InitiateWithSend() transitions to Established state. 3351 * ConnectionReceived<> occurs when a Connection created with 3352 Listen() transitions to Established state. 3354 * RendezvousDone<> occurs when a Connection created with 3355 Rendezvous() transitions to Established state. 3357 * Closed<> occurs when a Connection transitions to Closed state 3358 without error. 3360 * EstablishmentError<> occurs when a Connection created with 3361 Initiate() transitions from Establishing state to Closed state due 3362 to an error. 3364 * ConnectionError<> occurs when a Connection transitions to Closed 3365 state due to an error in all other circumstances. 3367 The following diagram shows the possible states of a Connection and 3368 the events that occur upon a transition from one state to another. 3370 (*) (**) 3371 Establishing -----> Established -----> Closing ------> Closed 3372 | ^ 3373 | | 3374 +---------------------------------------------------+ 3375 EstablishmentError<> 3377 (*) Ready<>, ConnectionReceived<>, RendezvousDone<> 3378 (**) Closed<>, ConnectionError<> 3380 Figure 2: Connection State Diagram 3382 The Transport Services API provides the following guarantees about 3383 the ordering of operations: 3385 * Sent<> events will occur on a Connection in the order in which the 3386 Messages were sent (i.e., delivered to the kernel or to the 3387 network interface, depending on implementation). 3389 * Received<> will never occur on a Connection before it is 3390 Established; i.e. before a Ready<> event on that Connection, or a 3391 ConnectionReceived<> or RendezvousDone<> containing that 3392 Connection. 3394 * No events will occur on a Connection after it is Closed; i.e., 3395 after a Closed<> event, an EstablishmentError<> or 3396 ConnectionError<> will not occur on that connection. To ensure 3397 this ordering, Closed<> will not occur on a Connection while other 3398 events on the Connection are still locally outstanding (i.e., 3399 known to the Transport Services API and waiting to be dealt with 3400 by the application). 3402 12. IANA Considerations 3404 RFC-EDITOR: Please remove this section before publication. 3406 This document has no Actions for IANA. Later versions of this 3407 document may create IANA registries for generic transport property 3408 names and transport property namespaces (see Section 4.1). 3410 13. Privacy and Security Considerations 3412 This document describes a generic API for interacting with a 3413 Transport Services system. Part of this API includes configuration 3414 details for transport security protocols, as discussed in 3415 Section 6.3. It does not recommend use (or disuse) of specific 3416 algorithms or protocols. Any API-compatible transport security 3417 protocol ought to work in a Transport Services system. Security 3418 considerations for these protocols are discussed in the respective 3419 specifications. 3421 The described API is used to exchange information between an 3422 application and the Transport Services system. While it is not 3423 necessarily expected that both systems are implemented by the same 3424 authority, it is expected that the Transport Services system 3425 implementation is either provided as a library that is selected by 3426 the application from a trusted party, or that it is part of the 3427 operating system that the application also relies on for other tasks. 3429 In either case, the Transport Services API is an internal interface 3430 that is used to change information locally between two systems. 3431 However, as the Transport Services system is responsible for network 3432 communication, it is in the position to potentially share any 3433 information provided by the application with the network or another 3434 communication peer. Most of the information provided over the 3435 Transport Services API are useful to configure and select protocols 3436 and paths and are not necessarily privacy sensitive. Still, some 3437 information could be privacy sensitive because it might reveal usage 3438 characteristics and habits of the user of an application. 3440 Of course any communication over a network reveals usage 3441 characteristics, as all packets, as well as their timing and size, 3442 are part of the network-visible wire image [RFC8546]. However, the 3443 selection of a protocol and its configuration also impacts which 3444 information is visible, potentially in clear text, and which other 3445 entities can access it. In most cases, information provided for 3446 protocol and path selection should not directly translate to 3447 information that can be observed by network devices on the path. 3448 However, there might be specific configuration information that is 3449 intended for path exposure, e.g., a DiffServ codepoint setting, that 3450 is either provided directly by the application or indirectly 3451 configured for a traffic profile. 3453 Applications should be aware that communication attempts can lead to 3454 more than one connection establishment. This is the case, for 3455 example, when the Transport Services system also executes name 3456 resolution, when support mechanisms such as TURN or ICE are used to 3457 establish connectivity, if protocols or paths are raised, or if a 3458 path fails and fallback or re-establishment is supported in the 3459 Transport Services system. 3461 Applications should also take care to not assume that all data 3462 received using the Transport Services API is always complete or well- 3463 formed. Specifically, messages that are received partially 3464 Section 9.3.2.2 could be a source of truncation attacks if 3465 applications do not distinguish between partial messages and complete 3466 messages. 3468 The Transport Services API explicitly does not require the 3469 application to resolve names, though there is a tradeoff between 3470 early and late binding of addresses to names. Early binding allows 3471 the API implementation to reduce connection setup latency, at the 3472 cost of potentially limited scope for alternate path discovery during 3473 Connection establishment, as well as potential additional information 3474 leakage about application interest when used with a resolution method 3475 (such as DNS without TLS) which does not protect query 3476 confidentiality. 3478 These communication activities are not different from what is used 3479 today. However, the goal of a Transport Services system is to 3480 support such mechanisms as a generic service within the transport 3481 layer. This enables applications to more dynamically benefit from 3482 innovations and new protocols in the transport, although it reduces 3483 transparency of the underlying communication actions to the 3484 application itself. The Transport Services API is designed such that 3485 protocol and path selection can be limited to a small and controlled 3486 set if required by the application for functional or security 3487 purposes. Further, A Transport Services system should provide an 3488 interface to poll information about which protocol and path is 3489 currently in use as well as provide logging about the communication 3490 events of each connection. 3492 14. Acknowledgements 3494 This work has received funding from the European Union's Horizon 2020 3495 research and innovation programme under grant agreements No. 644334 3496 (NEAT) and No. 688421 (MAMI). 3498 This work has been supported by Leibniz Prize project funds of DFG - 3499 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 3500 FE 570/4-1). 3502 This work has been supported by the UK Engineering and Physical 3503 Sciences Research Council under grant EP/R04144X/1. 3505 This work has been supported by the Research Council of Norway under 3506 its "Toppforsk" programme through the "OCARINA" project. 3508 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 3509 Kinnear for their implementation and design efforts, including Happy 3510 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 3511 and Jason Lee for initial work on the Post Sockets interface, from 3512 which this work has evolved. Thanks to Maximilian Franke for asking 3513 good questions based on implementation experience and for 3514 contributing text, e.g., on multicast. 3516 15. References 3518 15.1. Normative References 3520 [I-D.ietf-taps-arch] 3521 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., and 3522 C. Perkins, "An Architecture for Transport Services", Work 3523 in Progress, Internet-Draft, draft-ietf-taps-arch-12, 3 3524 January 2022, . 3527 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3528 Requirement Levels", BCP 14, RFC 2119, 3529 DOI 10.17487/RFC2119, March 1997, 3530 . 3532 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 3533 RFC 2914, DOI 10.17487/RFC2914, September 2000, 3534 . 3536 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 3537 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 3538 . 3540 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3541 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3542 March 2017, . 3544 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3545 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3546 May 2017, . 3548 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 3549 Transport Features Provided by IETF Transport Protocols", 3550 RFC 8303, DOI 10.17487/RFC8303, February 2018, 3551 . 3553 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3554 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3555 . 3557 [RFC8981] Gont, F., Krishnan, S., Narten, T., and R. Draves, 3558 "Temporary Address Extensions for Stateless Address 3559 Autoconfiguration in IPv6", RFC 8981, 3560 DOI 10.17487/RFC8981, February 2021, 3561 . 3563 15.2. Informative References 3565 [I-D.ietf-httpbis-priority] 3566 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3567 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3568 httpbis-priority-12, 17 January 2022, 3569 . 3572 [I-D.ietf-taps-impl] 3573 Brunstrom, A., Pauly, T., Enghardt, T., Tiesel, P. S., and 3574 M. Welzl, "Implementing Interfaces to Transport Services", 3575 Work in Progress, Internet-Draft, draft-ietf-taps-impl-11, 3576 9 January 2022, . 3579 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3580 "Definition of the Differentiated Services Field (DS 3581 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3582 DOI 10.17487/RFC2474, December 1998, 3583 . 3585 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 3586 "Assured Forwarding PHB Group", RFC 2597, 3587 DOI 10.17487/RFC2597, June 1999, 3588 . 3590 [RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le 3591 Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. 3592 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 3593 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 3594 . 3596 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 3597 A., Peterson, J., Sparks, R., Handley, M., and E. 3598 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 3599 DOI 10.17487/RFC3261, June 2002, 3600 . 3602 [RFC3376] Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A. 3603 Thyagarajan, "Internet Group Management Protocol, Version 3604 3", RFC 3376, DOI 10.17487/RFC3376, October 2002, 3605 . 3607 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 3608 Guidelines for DiffServ Service Classes", RFC 4594, 3609 DOI 10.17487/RFC4594, August 2006, 3610 . 3612 [RFC4604] Holbrook, H., Cain, B., and B. Haberman, "Using Internet 3613 Group Management Protocol Version 3 (IGMPv3) and Multicast 3614 Listener Discovery Protocol Version 2 (MLDv2) for Source- 3615 Specific Multicast", RFC 4604, DOI 10.17487/RFC4604, 3616 August 2006, . 3618 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 3619 (ICE): A Protocol for Network Address Translator (NAT) 3620 Traversal for Offer/Answer Protocols", RFC 5245, 3621 DOI 10.17487/RFC5245, April 2010, 3622 . 3624 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3625 Housley, R., and W. Polk, "Internet X.509 Public Key 3626 Infrastructure Certificate and Certificate Revocation List 3627 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3628 . 3630 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 3631 RFC 5482, DOI 10.17487/RFC5482, March 2009, 3632 . 3634 [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated 3635 Services Code Point (DSCP) for Capacity-Admitted Traffic", 3636 RFC 5865, DOI 10.17487/RFC5865, May 2010, 3637 . 3639 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 3640 Time Communication Use Cases and Requirements", RFC 7478, 3641 DOI 10.17487/RFC7478, March 2015, 3642 . 3644 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 3645 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 3646 . 3648 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 3649 (Diffserv) and Real-Time Communication", RFC 7657, 3650 DOI 10.17487/RFC7657, November 2015, 3651 . 3653 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 3654 Ed., "Services Provided by IETF Transport Protocols and 3655 Congestion Control Mechanisms", RFC 8095, 3656 DOI 10.17487/RFC8095, March 2017, 3657 . 3659 [RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation 3660 of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, 3661 August 2017, . 3663 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 3664 "Stream Schedulers and User Message Interleaving for the 3665 Stream Control Transmission Protocol", RFC 8260, 3666 DOI 10.17487/RFC8260, November 2017, 3667 . 3669 [RFC8293] Ghanwani, A., Dunbar, L., McBride, M., Bannai, V., and R. 3670 Krishnan, "A Framework for Multicast in Network 3671 Virtualization over Layer 3", RFC 8293, 3672 DOI 10.17487/RFC8293, January 2018, 3673 . 3675 [RFC8445] Keranen, A., Holmberg, C., and J. Rosenberg, "Interactive 3676 Connectivity Establishment (ICE): A Protocol for Network 3677 Address Translator (NAT) Traversal", RFC 8445, 3678 DOI 10.17487/RFC8445, July 2018, 3679 . 3681 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 3682 D., Mahy, R., and P. Matthews, "Session Traversal 3683 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 3684 February 2020, . 3686 [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a 3687 Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April 3688 2019, . 3690 [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for 3691 Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, 3692 June 2019, . 3694 [RFC8656] Reddy, T., Ed., Johnston, A., Ed., Matthews, P., and J. 3695 Rosenberg, "Traversal Using Relays around NAT (TURN): 3696 Relay Extensions to Session Traversal Utilities for NAT 3697 (STUN)", RFC 8656, DOI 10.17487/RFC8656, February 2020, 3698 . 3700 [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion 3701 Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, 3702 January 2020, . 3704 [RFC8838] Ivov, E., Uberti, J., and P. Saint-Andre, "Trickle ICE: 3705 Incremental Provisioning of Candidates for the Interactive 3706 Connectivity Establishment (ICE) Protocol", RFC 8838, 3707 DOI 10.17487/RFC8838, January 2021, 3708 . 3710 [RFC8899] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 3711 Völker, "Packetization Layer Path MTU Discovery for 3712 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 3713 September 2020, . 3715 [RFC8922] Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. 3716 Wood, "A Survey of the Interaction between Security 3717 Protocols and Transport Services", RFC 8922, 3718 DOI 10.17487/RFC8922, October 2020, 3719 . 3721 [RFC8923] Welzl, M. and S. Gjessing, "A Minimal Set of Transport 3722 Services for End Systems", RFC 8923, DOI 10.17487/RFC8923, 3723 October 2020, . 3725 [TCP-COUPLING] 3726 Islam, S., Welzl, M., Hiorth, K., Hayes, D., Armitage, G., 3727 and S. Gjessing, "ctrlTCP: Reducing Latency through 3728 Coupled, Heterogeneous Multi-Flow TCP Congestion Control", 3729 IEEE INFOCOM Global Internet Symposium (GI) workshop (GI 3730 2018) , 2018. 3732 Appendix A. Implementation Mapping 3734 The way the concepts from this abstract API map into concrete APIs in 3735 a given language on a given platform largely depends on the features 3736 and norms of the language and the platform. Actions could be 3737 implemented as functions or method calls, for instance, and Events 3738 could be implemented via event queues, handler functions or classes, 3739 communicating sequential processes, or other asynchronous calling 3740 conventions. 3742 A.1. Types 3744 The basic types mentioned in Section 1.1 typically have natural 3745 correspondences in practical programming languages, perhaps 3746 constrained by implementation-specific limitations. For example: 3748 * An Integer can typically be represented in C by an int or long, 3749 subject to the underlying platform's ranges for each. 3751 * In C, a Tuple may be represented as a struct with one member for 3752 each of the value types in the ordered grouping. In Python, by 3753 contrast, a Tuple may be represented natively as a tuple, a 3754 sequence of dynamically-typed elements. 3756 * A Collection may be represented as a std::set in C++ or as a set 3757 in Python. In C, it may be represented as an array or as a 3758 higher-level data structure with appropriate accessors defined. 3760 The objects described in Section 1.1 can similarly be represented in 3761 different ways depending on which programming language is used. 3762 Objects like Preconnections, Connections, and Listeners can be long- 3763 lived, and benefit from using object-oriented constructs. Note that 3764 in C, these objects may need to provide a way to release or free 3765 their underlying memory when the application is done using them. For 3766 example, since a Preconnection can be used to initiate multiple 3767 Connections, it is the responsibility of the application to clean up 3768 the Preconnection memory if necessary. 3770 A.2. Events and Errors 3772 This specification treats Events and Errors similarly. Errors, just 3773 as any other Events, may occur asynchronously in network 3774 applications. However, implementations of this API may report Errors 3775 synchronously, according to the error handling idioms of the 3776 implementation platform, where they can be immediately detected, such 3777 as by generating an exception when attempting to initiate a 3778 connection with inconsistent Transport Properties. An error can 3779 provide an optional reason to the application with further details 3780 about why the error occurred. 3782 A.3. Time Duration 3784 Time duration types are implementation-specific. For instance, it 3785 could be a number of seconds, number of milliseconds, or a struct 3786 timeval in C or a user-defined Duration class in C++. 3788 Appendix B. Convenience Functions 3790 B.1. Adding Preference Properties 3792 As Selection Properties of type Preference will be set on a 3793 TransportProperties object quite frequently, implementations can 3794 provide special actions for adding each preference level i.e, 3795 TransportProperties.Set(some_property, avoid) is equivalent to 3796 TransportProperties.Avoid(some_property): 3798 TransportProperties.Require(property) 3799 TransportProperties.Prefer(property) 3800 TransportProperties.Ignore(property) 3801 TransportProperties.Avoid(property) 3802 TransportProperties.Prohibit(property) 3804 B.2. Transport Property Profiles 3806 To ease the use of the Transport Services API specified by this 3807 document, implementations can provide a mechanism to create Transport 3808 Property objects (see Section 6.2) that are pre-configured with 3809 frequently used sets of properties; the following are in common use 3810 in current applications: 3812 B.2.1. reliable-inorder-stream 3814 This profile provides reliable, in-order transport service with 3815 congestion control. TCP is an example of a protocol that provides 3816 this service. It should consist of the following properties: 3818 +=======================+=========+ 3819 | Property | Value | 3820 +=======================+=========+ 3821 | reliability | require | 3822 +-----------------------+---------+ 3823 | preserveOrder | require | 3824 +-----------------------+---------+ 3825 | congestionControl | require | 3826 +-----------------------+---------+ 3827 | preserveMsgBoundaries | ignore | 3828 +-----------------------+---------+ 3830 Table 2: reliable-inorder- 3831 stream preferences 3833 B.2.2. reliable-message 3835 This profile provides message-preserving, reliable, in-order 3836 transport service with congestion control. SCTP is an example of a 3837 protocol that provides this service. It should consist of the 3838 following properties: 3840 +=======================+=========+ 3841 | Property | Value | 3842 +=======================+=========+ 3843 | reliability | require | 3844 +-----------------------+---------+ 3845 | preserveOrder | require | 3846 +-----------------------+---------+ 3847 | congestionControl | require | 3848 +-----------------------+---------+ 3849 | preserveMsgBoundaries | require | 3850 +-----------------------+---------+ 3852 Table 3: reliable-message 3853 preferences 3855 B.2.3. unreliable-datagram 3857 This profile provides a datagram transport service without any 3858 reliability guarantee. An example of a protocol that provides this 3859 service is UDP. It consists of the following properties: 3861 +=======================+=========+ 3862 | Property | Value | 3863 +=======================+=========+ 3864 | reliability | avoid | 3865 +-----------------------+---------+ 3866 | preserveOrder | avoid | 3867 +-----------------------+---------+ 3868 | congestionControl | ignore | 3869 +-----------------------+---------+ 3870 | preserveMsgBoundaries | require | 3871 +-----------------------+---------+ 3872 | safely replayable | true | 3873 +-----------------------+---------+ 3875 Table 4: unreliable-datagram 3876 preferences 3878 Applications that choose this Transport Property Profile would avoid 3879 the additional latency that could be introduced by retransmission or 3880 reordering in a transport protocol. 3882 Applications that choose this Transport Property Profile to reduce 3883 latency should also consider setting an appropriate Capacity Profile 3884 Property, see Section 8.1.6 and might benefit from controlling 3885 checksum coverage, see Section 6.2.7 and Section 6.2.8. 3887 Appendix C. Relationship to the Minimal Set of Transport Services for 3888 End Systems 3890 [RFC8923] identifies a minimal set of transport services that end 3891 systems should offer. These services make all non-security-related 3892 transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT 3893 available that 1) require interaction with the application, and 2) do 3894 not get in the way of a possible implementation over TCP (or, with 3895 limitations, UDP). The following text explains how this minimal set 3896 is reflected in the present API. For brevity, it is based on the 3897 list in Section 4.1 of [RFC8923], updated according to the discussion 3898 in Section 5 of [RFC8923]. The present API covers all elements of 3899 this section. This list is a subset of the transport features in 3900 Appendix A of [RFC8923], which refers to the primitives in "pass 2" 3901 (Section 4) of [RFC8303] for further details on the implementation 3902 with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. 3904 * Connect: Initiate Action (Section 7.1). 3906 * Listen: Listen Action (Section 7.2). 3908 * Specify number of attempts and/or timeout for the first 3909 establishment message: timeout parameter of Initiate (Section 7.1) 3910 or InitiateWithSend Action (Section 9.2.5). 3912 * Disable MPTCP: multipath Property (Section 6.2.14). 3914 * Hand over a message to reliably transfer (possibly multiple times) 3915 before connection establishment: InitiateWithSend Action 3916 (Section 9.2.5). 3918 * Change timeout for aborting connection (using retransmit limit or 3919 time value): connTimeout property, using a time value 3920 (Section 8.1.3). 3922 * Timeout event when data could not be delivered for too long: 3923 ConnectionError Event (Section 10). 3925 * Suggest timeout to the peer: See "TCP-specific Properties: User 3926 Timeout Option (UTO)" (Section 8.2). 3928 * Notification of ICMP error message arrival: softErrorNotify 3929 (Section 6.2.17) and SoftError Event (Section 8.3.1). 3931 * Choose a scheduler to operate between streams of an association: 3932 connScheduler property (Section 8.1.5). 3934 * Configure priority or weight for a scheduler: connPriority 3935 property (Section 8.1.2). 3937 * "Specify checksum coverage used by the sender" and "Disable 3938 checksum when sending": msgChecksumLen property (Section 9.1.3.6) 3939 and fullChecksumSend property (Section 6.2.7). 3941 * "Specify minimum checksum coverage required by receiver" and 3942 "Disable checksum requirement when receiving": recvChecksumLen 3943 property (Section 8.1.1) and fullChecksumRecv property 3944 (Section 6.2.8). 3946 * "Specify DF field": noFragmentation property (Section 9.1.3.9). 3948 * Get max. transport-message size that may be sent using a non- 3949 fragmented IP packet from the configured interface: 3950 singularTransmissionMsgMaxLen property (Section 8.1.11.2). 3952 * Get max. transport-message size that may be received from the 3953 configured interface: recvMsgMaxLen property (Section 8.1.11.4). 3955 * Obtain ECN field: This is a read-only Message Property of the 3956 MessageContext object (see "UDP(-Lite)-specific Property: ECN" 3957 Section 9.3.3.1). 3959 * "Specify DSCP field", "Disable Nagle algorithm", "Enable and 3960 configure a Low Extra Delay Background Transfer": as suggested in 3961 Section 5.5 of [RFC8923], these transport features are 3962 collectively offered via the connCapacityProfile property 3963 (Section 8.1.6). Per-Message control ("Request not to bundle 3964 messages") is offered via the msgCapacityProfile property 3965 (Section 9.1.3.8). 3967 * Close after reliably delivering all remaining data, causing an 3968 event informing the application on the other side: this is offered 3969 by the Close Action with slightly changed semantics in line with 3970 the discussion in Section 5.2 of [RFC8923] (Section 10). 3972 * "Abort without delivering remaining data, causing an event 3973 informing the application on the other side" and "Abort without 3974 delivering remaining data, not causing an event informing the 3975 application on the other side": this is offered by the Abort 3976 action without promising that this is signaled to the other side. 3977 If it is, a ConnectionError Event will be invoked at the peer 3978 (Section 10). 3980 * "Reliably transfer data, with congestion control", "Reliably 3981 transfer a message, with congestion control" and "Unreliably 3982 transfer a message": data is transferred via the Send action 3983 (Section 9.2). Reliability is controlled via the reliability 3984 (Section 6.2.1) property and the msgReliable Message Property 3985 (Section 9.1.3.7). Transmitting data as a message or without 3986 delimiters is controlled via Message Framers (Section 9.1.2). The 3987 choice of congestion control is provided via the congestionControl 3988 property (Section 6.2.9). 3990 * Configurable Message Reliability: the msgLifetime Message Property 3991 implements a time-based way to configure message reliability 3992 (Section 9.1.3.1). 3994 * "Ordered message delivery (potentially slower than unordered)" and 3995 "Unordered message delivery (potentially faster than ordered)": 3996 these two transport features are controlled via the Message 3997 Property msgOrdered (Section 9.1.3.3). 3999 * Request not to delay the acknowledgement (SACK) of a message: 4000 should the protocol support it, this is one of the transport 4001 features the Transport Services system can apply when an 4002 application uses the connCapacityProfile Property (Section 8.1.6) 4003 or the msgCapacityProfile Message Property (Section 9.1.3.8) with 4004 value Low Latency/Interactive. 4006 * Receive data (with no message delimiting): Receive Action 4007 (Section 9.3) and Received Event (Section 9.3.2.1). 4009 * Receive a message: Receive Action (Section 9.3) and Received Event 4010 (Section 9.3.2.1), using Message Framers (Section 9.1.2). 4012 * Information about partial message arrival: Receive Action 4013 (Section 9.3) and ReceivedPartial Event (Section 9.3.2.2). 4015 * Notification of send failures: Expired Event (Section 9.2.2.2) and 4016 SendError Event (Section 9.2.2.3). 4018 * Notification that the stack has no more user data to send: 4019 applications can obtain this information via the Sent Event 4020 (Section 9.2.2.1). 4022 * Notification to a receiver that a partial message delivery has 4023 been aborted: ReceiveError Event (Section 9.3.2.3). 4025 * Notification of Excessive Retransmissions (early warning below 4026 abortion threshold): SoftError Event (Section 8.3.1). 4028 Authors' Addresses 4030 Brian Trammell (editor) 4031 Google Switzerland GmbH 4032 Gustav-Gull-Platz 1 4033 CH- 8004 Zurich 4034 Switzerland 4035 Email: ietf@trammell.ch 4037 Michael Welzl (editor) 4038 University of Oslo 4039 PO Box 1080 Blindern 4040 0316 Oslo 4041 Norway 4042 Email: michawe@ifi.uio.no 4043 Theresa Enghardt 4044 Netflix 4045 121 Albright Way 4046 Los Gatos, CA 95032, 4047 United States of America 4048 Email: ietf@tenghardt.net 4050 Godred Fairhurst 4051 University of Aberdeen 4052 Fraser Noble Building 4053 Aberdeen, AB24 3UE 4054 Email: gorry@erg.abdn.ac.uk 4055 URI: http://www.erg.abdn.ac.uk/ 4057 Mirja Kuehlewind 4058 Ericsson 4059 Ericsson-Allee 1 4060 Herzogenrath 4061 Germany 4062 Email: mirja.kuehlewind@ericsson.com 4064 Colin Perkins 4065 University of Glasgow 4066 School of Computing Science 4067 Glasgow G12 8QQ 4068 United Kingdom 4069 Email: csp@csperkins.org 4071 Philipp S. Tiesel 4072 SAP SE 4073 Konrad-Zuse-Ring 10 4074 14469 Potsdam 4075 Germany 4076 Email: philipp@tiesel.net 4078 Tommy Pauly 4079 Apple Inc. 4080 One Apple Park Way 4081 Cupertino, California 95014, 4082 United States of America 4083 Email: tpauly@apple.com